Set up the SDK

Platform:

Version:

The justtrack SDK provides powerful tracking capabilities for attribution, events, and more.

This guide shows you how to add the justtrack SDK to your app.

Add the SDK dependency

In your settings.gradle, add the justtrack Maven repository:

Kotlin
Groovy

dependencyResolutionManagement {
    repositories {
        // ... your other repositories
        maven(url = "https://sdk.justtrack.io/maven")
    }
}

dependencyResolutionManagement {
    repositories {
        // ... your other repositories
        maven {
            url "https://sdk.justtrack.io/maven"
        }
    }
}

Then, in your module-level build.gradle, add the SDK dependency:

Kotlin
Groovy

dependencies {
  implementation("io.justtrack:justtrack-android-sdk:8.0.0")
}

dependencies {
  implementation "io.justtrack:justtrack-android-sdk:8.0.0"
}

Please view the latest version here.

Using CocoaPods

You can use CocoaPods to add the justtrack SDK to your app. Add the following line to your Podfile:

pod 'JustTrackSDK', '8.0.0'

Afterwards, run pod install in your project to actually download and install the justtrack SDK for your project.

Using Carthage

You can also use Carthage. Add the following line to your Cartfile:

binary "https://sdk.justtrack.io/carthage/JustTrackSDK.json" == 8.0.0

Afterwards, run carthage update inside the project directory to download the justtrack SDK for your project.

Using Swift Package Manager

The SDK is available via Swift Package Manager. To add the SDK package to your Xcode project, select File > Add Package Dependency and enter its repository URL https://github.com/justtrackio/justtrack-sdk-spm.

The justtrack SDK is available as a Unity package. You have to add https://registry.npmjs.org as the scoped registry to add it to your game. Navigate to Window → Package Manager, then select Advanced Project Settings from the gear menu. Now add the justtrack Package Registry to your game:

After adding the scoped registry, you need to add the justtrack SDK to your project. Select Packages: My Registries in the drop-down menu, select the justtrack SDK and install it into your game. Use the latest available version if possible:

You can also add the scoped registry and package directly to your Packages/manifest.json. Afterwards, your manifest.json should look like this:

{
  "dependencies": {
    // ... other dependencies of your game ...
    "io.justtrack.justtrack-unity-sdk": "8.0.0"
  },
  "scopedRegistries": [
    // ... other scoped registries ...
    {
      "name": "justtrack Package Registry",
      "url": "https://registry.npmjs.org",
      "scopes": [
        "io.justtrack"
      ]
    }
  ]
}

Install the dependencies

The justtrack SDK uses the External Dependency Manager for Unity from Google to download the justtrack SDK as well as its dependencies. You can select an appropriate version from this list.

You can install the justtrack SDK for React Native from npm using:

npm install react-native-justtrack-sdk --save

Download justtrack-sdk-godot-1.0.0.zip from GitHub Releases and unzip it into the root of your Godot project. You should end up with:

res://addons/justtrack_sdk/

GetGameInstance()->GetSubsystem<UJustTrackSubsystem>()->TrackEvent(
    TEXT("tutorial_finished"),
    { { TEXT("difficulty"), TEXT("hard") } },
    42.0,
    EJustTrackEventUnit::Seconds,
    FString(),
    FJustTrackVoidResult());

Then enable the plugin in your Godot editor: Project → Project Settings → Plugins → enable JustTrack SDK.

This registers the JustTrackSdk autoload so the singleton is available from any GDScript without an import.

The justtrack SDK ships as an Unreal Engine plugin. To add it to your project, install the binary release.

Using the binary release

Download the latest release from justtrack-unreal-sdk on GitHub.
Unzip the archive.
Copy the JustTrackSDK directory into your project's Plugins/ directory, so that the plugin descriptor ends up at:
```
<YourProject>/Plugins/JustTrackSDK/JustTrackSDK.uplugin
```
Create the Plugins directory yourself if your project doesn't have one yet.

Enable the plugin

After you install the plugin, add it to your .uproject file:

"Plugins": [
  {
    "Name": "JustTrackSDK",
    "Enabled": true
  }
]

Unreal enables plugins in your project's Plugins/ directory by default, so this entry is optional, but it keeps the dependency visible and under version control. You can also enable the plugin from Edit > Plugins, where it appears as justtrack SDK under Analytics.

Next, add JustTrackSDK to your game module's dependencies in Source/<YourProject>/<YourProject>.Build.cs:

PrivateDependencyModuleNames.AddRange(new string[] { "JustTrackSDK" });

Add this even for a Blueprint-only integration. The plugin's module targets Android and iOS, so Unreal compiles it only when your target references it by name. Without the reference, the editor mounts the plugin but never builds it, and the subsystem, the settings page, and the Blueprint nodes are all missing.

Finally, close the editor and rebuild your project. Adding a module changes which binaries your target links, and Live Coding can't pick that up while the editor runs.

Compatibility

Before integrating, make sure your project meets the minimum requirements for your platform.

Requirement	Minimum
Android OS	API 21 (Android 5.0)
AGP	8.6.0
Gradle	8.7

Requirement	Minimum
iOS	12
Xcode	16.0
Swift	5.0

Requirement	Minimum
Unity Editor	2022 LTS
Unity External Dependency Manager	1.2.183

Requirement	Minimum
React	18.2.0
React Native	0.71.0

Requirement	Minimum
Dart SDK	3.9.2
Flutter	3.3.0
Android OS	API 24 (Android 7.0)
iOS	13.0
Swift	5.0

Requirement	Minimum
Godot	4.3
Android OS	API 21 (Android 5.0)
iOS	13.0

Requirement	Minimum
Unreal Engine	5.7
Android OS	API 26 (Android 8.0)
iOS	15.0
Xcode	16.4

Find your API token

For the next step, you'll need to obtain an API token. Follow our guide to find your API token.

Instantiate the SDK

The main entry point to the SDK is the JustTrackSdk interface. Create an SDK instance using the JustTrackSdkBuilder:

import io.justtrack.JustTrackSdk
import io.justtrack.JustTrackSdkBuilder

class MainActivity : Activity() {
    private lateinit var sdk: JustTrackSdk

    override fun onCreate(savedInstanceState: Bundle?) {
        // ...
        sdk = JustTrackSdkBuilder(this, "...paste your API token here").build()
    }
}

The main entry point to the SDK is the JustTrackSdk protocol. Create an SDK instance using the JustTrackSdkBuilder:

do {
    let sdk = try JustTrackSdkBuilder(apiToken: "... paste your API token here").build()
} catch {
    // apiToken has invalid format...
}

Add the prefab

After finishing the installation of the justtrack SDK and its dependencies you should see a new justtrack menu. Navigate to the first scene of your game, and select Create SDK instance from the justtrack menu.

The justtrack SDK supports two initialization modes. You can configure all settings through the Unity editor, or initialize the SDK manually from code at runtime.

Settings UI
Runtime Constructor

This is the default approach. After creating the SDK instance in your scene, select it and configure your settings in the inspector (via justtrack > Show Settings in the menu, or by selecting the prefab instance):

Set your API Token for Android, iOS, and WebGL as applicable.
Configure integrations and other options as needed.

The SDK initializes itself automatically when the scene loads.

If you need to initialize the SDK dynamically (for example, to determine settings at runtime or load tokens from a remote config), enable Use Runtime Constructor in the justtrack settings (justtrack > Show Settings).

When this option is enabled, the SDK prefab won't auto-initialize. Instead, call JustTrackSDK.Init() from your own code when you're ready:

using JustTrack;

JustTrackSDK.Init(
    apiToken,               // your justtrack API token
    trackingId,             // optional: tracking ID (pass null if unused)
    trackingProvider,       // optional: tracking provider (pass null if unused)
    customUserId,           // optional: your own user ID (pass null if unused)
    automaticInAppPurchaseTracking, // true to enable automatic IAP tracking
    manualStart,            // true to delay SDK start until you call Start()
    enableConsoleLogging,   // true to enable console logging
    serverUrl,              // optional: custom server URL (pass null for default)
    bundleId,               // optional: custom bundle ID (pass null for default)
    appVersion,             // optional: custom app version (pass null for default)
    appCode                 // optional: custom app version code (pass null for default)
);

using JustTrack;

JustTrackSDK.Init(
    apiToken,               // your justtrack API token
    trackingId,             // optional: tracking ID (pass null if unused)
    trackingProvider,       // optional: tracking provider (pass null if unused)
    customUserId,           // optional: your own user ID (pass null if unused)
    automaticInAppPurchaseTracking, // true to enable automatic IAP tracking
    manualStart,            // true to delay SDK start until you call Start()
    enableConsoleLogging,   // true to enable console logging
    enableConnectionTracking, // true to add the connection type to every event
    serverUrl,              // optional: custom server URL (pass null for default)
    bundleId,               // optional: custom bundle ID (pass null for default)
    new ApplicationVersion("1.0.0", "1") // optional: custom app version (pass null for default)
);

note

You still need the SDK prefab in your scene. The prefab manages the SDK lifecycle — it just won't call Init() automatically when Use Runtime Constructor is enabled.

You first have to initialize the SDK with your API token:

import * as JustTrackSdk from 'react-native-justtrack-sdk';

await new JustTrackSdk.JusttrackSdkBuilder(apiToken).initialize();

Only after initializing the SDK will you be able to call the methods to attribute the current user or send user events.

You first have to initialize the SDK with your API token:

import 'package:justtrack_sdk/justtrack_sdk.dart';

void main() async {
  await JusttrackSdk.initialize('...paste your API token here');
}

The SDK must be initialized before calling any methods.

The JustTrackSdk autoload is available globally. Because initialization completes asynchronously, connect to the initialized signal before calling initialize():

func _ready() -> void:
    JustTrackSdk.initialized.connect(_on_sdk_initialized)
    JustTrackSdk.initialize_failed.connect(_on_sdk_initialize_failed)
    JustTrackSdk.initialize("...paste your API token here")

func _on_sdk_initialized() -> void:
    print("justtrack SDK ready")

func _on_sdk_initialize_failed(code: String, message: String) -> void:
    push_error("justtrack SDK init failed [%s]: %s" % [code, message])

The main entry point to the SDK is UJustTrackSubsystem, a game instance subsystem. Get it with GetGameInstance()->GetSubsystem<UJustTrackSubsystem>() in C++, or with the Get justtrack node in Blueprint.

The plugin supports two configuration paths. You can configure everything in the editor, or build the configuration in code and initialize the SDK yourself.

Project Settings
Runtime configuration (C++)
Runtime configuration (Blueprint)

Open Project Settings > Plugins > justtrack SDK and configure your integration:

Turn off Configure at Runtime. It's on by default, and while it's on the SDK ignores the settings below.
Paste your API token into Android API Token and iOS API Token.
Adjust the remaining options as needed, such as Manual Start or Logging Enabled.

With Configure at Runtime off and Initialize On Startup on, the subsystem initializes itself as soon as the game instance starts, so there's nothing left to call.

If you'd rather decide when initialization happens, turn off Initialize On Startup and initialize from the saved settings later:

#include "JustTrackSettings.h"
#include "JustTrackSubsystem.h"

UJustTrackSubsystem* JustTrack = GetGameInstance()->GetSubsystem<UJustTrackSubsystem>();

FJustTrackVoidResult OnComplete;
OnComplete.BindUFunction(this, GET_FUNCTION_NAME_CHECKED(AMyActor, HandleJustTrackReady));
JustTrack->InitializeSdk(UJustTrackSettings::Get().MakeConfig(), OnComplete);

Leave Configure at Runtime on, which is the default, and build an FJustTrackConfig yourself. This is the option to pick when your token or server URL isn't known until runtime:

#include "JustTrackSubsystem.h"

UJustTrackSubsystem* JustTrack = GetGameInstance()->GetSubsystem<UJustTrackSubsystem>();

FJustTrackConfig Config;
Config.ApiToken = TEXT("...paste your API token here");

FJustTrackVoidResult OnComplete;
OnComplete.BindUFunction(this, GET_FUNCTION_NAME_CHECKED(AMyActor, HandleJustTrackReady));
JustTrack->InitializeSdk(Config, OnComplete);

The callback reports whether initialization succeeded:

void AMyActor::HandleJustTrackReady(bool bSuccess, const FJustTrackError& Error)
{
    if (!bSuccess)
    {
        UE_LOG(LogTemp, Warning, TEXT("justtrack init failed: %s (%s)"), *Error.Message, *Error.Code);
        return;
    }

    // The SDK is ready.
}

The callback target must be a UFUNCTION, because BindUFunction resolves it by name.

Both runtime paths take the same configuration. FJustTrackConfig in C++ and JustTrackConfig in Blueprint accept these fields:

Field	Blueprint pin	Description
`ApiToken`	Api Token	Required. Initialization fails if it's empty.
`ApplicationId`	Application Id	Android package name or iOS bundle ID. Leave empty to detect it automatically.
`ApplicationVersionName`	Application Version Name	Application version name. Only used when `ApplicationVersionCode` is also set.
`ApplicationVersionCode`	Application Version Code	Application version code. Only used when `ApplicationVersionName` is also set.
`UserId`	User Id	Your own user ID. Leave empty to set it later.
`ServerUrl`	Server Url	Backend URL override. Must start with `http://` or `https://`. Leave empty for the default.
`bManualStart`	Manual Start	When true, tracking waits until you call `Start()`.
`bLoggingEnabled`	Logging Enabled	Whether the native SDK writes to the device log.

Every callback runs on the game thread, so you can touch UObjects directly. Call IsInitialized() at any point to check whether the SDK is ready.

Track user connection status with events

The SDK can record whether the device was online or offline when an event happened. Enable connection tracking, and every event you track carries the jt_connection_type predefined dimension with the value online or offline. This is useful when you want to tell real user behavior apart from events that queued up while the device had no connection.

Connection tracking is off by default. Turn it on when you create the SDK:

await new JustTrackSdk.JusttrackSdkBuilder(apiToken)
  .withEnableConnectionTracking(true)
  .initialize();

Ad tracking transparency

Starting with iOS 14, the justtrack SDK can only access the IDFA if the user allowed the app to track them. By default, the justtrack SDK doesn't request this permission and can (albeit somewhat limited) still attribute the user to the correct campaign. To improve this precision, you can ask the user for permission to track them.

You can use JustTrack.requestTrackingAuthorization to prompt the user for permission on iOS 14+. On earlier versions it will fall back to a simple check whether the user allowed tracking at all (there is nothing to prompt the user for). It will also track the decision of the user (only for the first time a user got a prompt), so you can check, how many of your users actually grant you permission to track them. Initialization of the justtrack SDK could then look like this:

JustTrack.requestTrackingAuthorization { success in
    // success is true if we got permission, false otherwise. You can use this for your own logic,
    // we will ignore this here
    do {
        // create the instance of the JustTrack SDK only after trying to get permission to read the IDFA
        let sdk = try JustTrackSdkBuilder(apiToken: apiToken).build()
        // use the SDK for your app
    } catch {
        // your API token had an invalid format
    }
}

You have to set the NSUserTrackingUsageDescription key in your Info.plist file when requesting the tracking permission from the user.

Ad tracking transparency for iOS Starting with iOS 14, the justtrack SDK can only access the

IDFA if the user allowed the app to track them. The justtrack SDK doesn't request this permission but can (albeit somewhat limited) still attribute the user to the correct campaign. To improve this precision, you can ask the user for permission to track them.

Ad tracking transparency for iOS

Starting with iOS 14, the justtrack SDK can only access the IDFA if the user allowed the app to track them. By default the SDK can still attribute users with limited precision. To improve it, call request_tracking_authorization() before initialize() and wait for the tracking_authorization_result signal:

func _ready() -> void:
    JustTrackSdk.tracking_authorization_result.connect(_on_tracking_auth)
    JustTrackSdk.request_tracking_authorization()

func _on_tracking_auth(granted: bool) -> void:
    JustTrackSdk.initialized.connect(_on_sdk_initialized)
    JustTrackSdk.initialize("...paste your API token here")

func _on_sdk_initialized() -> void:
    print("justtrack SDK ready")

You must add the NSUserTrackingUsageDescription key to your app's Info.plist when requesting tracking permission.

On Android, request_tracking_authorization() is a no-op and always fires true.

Ad tracking transparency for iOS

Starting with iOS 14, the justtrack SDK can only access the IDFA if the user allowed the app to track them. By default the SDK doesn't request this permission and still attributes the user, albeit with less precision. To improve precision, ask the user for permission.

Call RequestTrackingAuthorization before InitializeSdk, so the first attribution request already carries the user's decision:

void AMyActor::AskForTrackingPermission()
{
    UJustTrackSubsystem* JustTrack = GetGameInstance()->GetSubsystem<UJustTrackSubsystem>();

    FJustTrackTrackingAuthorizationResult OnComplete;
    OnComplete.BindUFunction(this, GET_FUNCTION_NAME_CHECKED(AMyActor, HandleTrackingAuthorization));
    JustTrack->RequestTrackingAuthorization(OnComplete);
}

void AMyActor::HandleTrackingAuthorization(bool bGranted)
{
    // bGranted tells you whether you may read the IDFA. Initialize the SDK either way.
    InitializeJustTrack();
}

You have to set the NSUserTrackingUsageDescription key in your iOS build settings when requesting the tracking permission from the user.

RequestTrackingAuthorization doesn't need an initialized SDK, so you can call it as early as you like. On Android there's nothing to prompt for, and the callback fires immediately with true.

The justtrack SDK will call SKAdNetwork.registerAppForAdNetworkAttribution upon startup. This will cause the device to send a postback describing the attribution of the app after 24 to 48 hours. The SDK also registers the justtrack backend as the receiver for the copy of the postback for the advertised app (iOS 15+).

Ad tracking transparency for iOS

Starting with iOS 14, the justtrack SDK can only access the IDFA if the user allowed the app to track them. By default the justtrack SDK doesn't request this permission and can (albeit somewhat limited) still attribute the user to the correct campaign. You can ask the user for permission to track them to improve the precision of the attribution.

The request for this permission needs to happen before the justtrack SDK is initialized (as we otherwise won't get an IDFA for the user). To help you with this you can configure the justtrack SDK to request this permission on your behalf upon app start. Go to the iOS settings of the SDK, enable "Request Tracking Permission", and set a message to be displayed to your users (so they know why you need the permission):

If you provide a message, it will overwrite the NSUserTrackingUsageDescription property in your Info.plist file (see also NSUserTrackingUsageDescription). If you instead set "Ignore Empty Tracking Description" the justtrack SDK assumes you already provide that setting somewhere else and does no longer warn about the missing description.

The justtrack SDK can also forward the answer of the user for the permission request to the Facebook Audience Network (via FAN method). If you don't use the Facebook Audience Network (FAN), you can leave the setting at "No Integration". If you are using the Unity version of the FAN, select "Unity Integration", otherwise, select "Native Integration". In both cases a small code file will be added to your game (you need to allow injecting the code) which is used to forward the permission upon runtime.

Configure Facebook Audience Network Integration

If you need to integrate with additional frameworks, you can use JustTrackSDK.OnTrackingAuthorization to be notified about the decision of the user:

using JustTrack;

JustTrackSDK.OnTrackingAuthorization((authorized) => {
    if (authorized) {
        // access to the GAID/IDFA has been authorized
    } else {
        // access to the GAID/IDFA has been forbidden
    }
});

That’s it!

Once instantiated, JustTrackSdk is ready to attribute your users. See our guide on tracking events next.

Add the SDK dependency​

Using CocoaPods​

Using Carthage​

Using Swift Package Manager​

Install the dependencies​

Using the binary release​

Enable the plugin​

Compatibility​

Find your API token​

Instantiate the SDK​

Add the prefab​

Track user connection status with events​

Ad tracking transparency​

Ad tracking transparency for iOS Starting with iOS 14, the justtrack SDK can only access the​

Ad tracking transparency for iOS​

Ad tracking transparency for iOS​

Ad tracking transparency for iOS​

That’s it!​

Add the SDK dependency

Using CocoaPods

Using Carthage

Using Swift Package Manager

Install the dependencies

Using the binary release

Enable the plugin

Compatibility

Find your API token

Instantiate the SDK

Add the prefab

Track user connection status with events

Ad tracking transparency

Ad tracking transparency for iOS Starting with iOS 14, the justtrack SDK can only access the

Ad tracking transparency for iOS

Ad tracking transparency for iOS

Ad tracking transparency for iOS

That’s it!