Additional Features

Attribution callback

You can set up a callback to be notified about attribution changes. We consider a variety of different sources for attribution, so we provide this information asynchronously.

Follow these steps to add the optional callback in your application:

Create a method with the signature of the delegate Action<AdTraceAttribution>.
After creating the AdTraceConfig object, call the adtraceConfig.setAttributionChangedDelegate with the previously created method. You can also use a lambda with the same signature.
If instead of using the AdTrace.prefab the AdTrace.cs script was added to another GameObject, be sure to pass the name of the GameObject as the second parameter of AdTraceConfig.setAttributionChangedDelegate.

Because the callback is configured using the AdTraceConfig instance, call adtraceConfig.setAttributionChangedDelegate before calling AdTrace.start.

using io.adtrace.sdk;

public class ExampleGUI : MonoBehaviour {
    void OnGUI() {
        if (GUI.Button(new Rect(0, 0, Screen.width, Screen.height), "callback")) {
            AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);
            adtraceConfig.setLogLevel(AdTraceLogLevel.Verbose);
            adtraceConfig.setAttributionChangedDelegate(this.attributionChangedDelegate);

            AdTrace.start(adtraceConfig);
        }
    }

    public void attributionChangedDelegate(AdTraceAttribution attribution) {
        Debug.Log("Attribution changed");

        // ...
    }
}

The callback function will be called when the SDK receives final attribution data. Within the callback function you have access to the attribution parameter. Here is a quick summary of its properties:

string trackerToken the tracker token of the current attribution
string trackerName the tracker name of the current attribution
string network the network grouping level of the current attribution
string campaign the campaign grouping level of the current attribution
string adgroup the ad group grouping level of the current attribution
string creative the creative grouping level of the current attribution
string clickLabel the click label of the current attribution
string adid the Adtrace device identifier
string costType the cost type string
double? costAmount the cost amount
string costCurrency the cost currency string

User attribution

This callback, like an attribution callback, is triggered whenever the attribution information changes. Access your user's current attribution information whenever you need it by calling the following method of the AdTrace instance:

AdTraceAttribution attribution = AdTrace.getAttribution();

Important

Current attribution information is available after our backend tracks the app install and triggers the attribution callback. It is not possible to access a user's attribution value before the SDK has been initialized and the attribution callback has been triggered.

Session and event callbacks

You can set up callbacks to notify you of successful and failed events and/or sessions.

Follow these steps to add the callback function for successfully tracked events:

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);
adtraceConfig.setLogLevel(AdTraceLogLevel.Verbose);
adtraceConfig.setEventSuccessDelegate(EventSuccessCallback);

AdTrace.start(adtraceConfig);

// ...

public void EventSuccessCallback(AdTraceEventSuccess eventSuccessData) {
    // ...
}

Add the following callback function for failed tracked events:

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);
adtraceConfig.setLogLevel(AdTraceLogLevel.Verbose);
adtraceConfig.setEventFailureDelegate(EventFailureCallback);

AdTrace.start(adtraceConfig);

// ...

public void EventFailureCallback(AdTraceEventFailure eventFailureData) {
    // ...
}

For successfully tracked sessions:

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);
adtraceConfig.setLogLevel(AdTraceLogLevel.Verbose);
adtraceConfig.setSessionSuccessDelegate(SessionSuccessCallback);

AdTrace.start(adtraceConfig);

// ...

public void SessionSuccessCallback (AdTraceSessionSuccess sessionSuccessData) {
    // ...
}

For failed tracked sessions:

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);
adtraceConfig.setLogLevel(AdTraceLogLevel.Verbose);
adtraceConfig.setSessionFailureDelegate(SessionFailureCallback);

AdTrace.start(adtraceConfig);

// ...

public void SessionFailureCallback (AdTraceSessionFailure sessionFailureData) {
    // ...
}

Callback functions will be called after the SDK tries to send a package to the server. Within the callback you have access to a response data object specifically for the callback. Here is a quick summary of the session response data properties:

string Message the message from the server or the error logged by the SDK
string Timestamp timestamp from the server
string Adid a unique device identifier provided by AdTrace
Dictionary<string, object> JsonResponse the JSON object with the response from the server

Both event response data objects contain:

string EventToken the event token, if the package tracked was an event
string CallbackId the custom defined callback ID set on an event object

Both event and session failed objects also contain:

bool WillRetry indicates there will be an attempt to resend the package at a later time

Device IDs

The Adtrace SDK lets you receive device identifiers.

IDFA (iOS Identifier)

To obtain the IDFA, call the function getIdfa of the AdTrace instance:

string idfa = AdTrace.getIdfa();

GPS AdId (Google Play Services advertising identifier)

The Google Play Services Advertising Identifier (Google advertising ID) is a unique identifier for a device. Users can opt out of sharing their Google advertising ID by toggling the "Opt out of Ads Personalization" setting on their device. When a user has enabled this setting, the Adtrace SDK returns a string of zeros when trying to read the Google advertising ID.

Attention

If you are targeting Android 12 and above (API level 31), you need to add the com.google.android.gms.AD_ID permission to your app. If you do not add this permission, you will not be able to read the Google advertising ID even if the user has not opted out of sharing their ID.

The Google advertising ID can only be read in a background thread. If you call the method getGoogleAdId of the AdTrace instance with an Action<string> delegate, it will work in any situation:

AdTrace.getGoogleAdId((string googleAdId) => {
    // ...
});

You will now have access to the Google advertising ID as the variable googleAdId.

AdId (Adtrace device identifier)

Our backend generates a unique Adtrace device identifier (known as an adid) for every device that has your app installed. In order to get this identifier, call this method on AdTrace instance:

String adid = AdTrace.getAdid();

Information about the adid is only available after our backend tracks the app install. It is not possible to access the adid value before the SDK has been initialized and the installation of your app has been successfully tracked.

Set external device ID (Experimental)

An external device identifier is a custom value that you can assign to a device or user. They can help you to recognize users across sessions and platforms. They can also help you to deduplicate installs by user so that a user isn't counted as multiple new installs.

You can also use an external device ID as a custom identifier for a device. This can be useful if you use these identifiers elsewhere and want to keep continuity.

warning

This setting requires Adtrace SDK v2+ or later.

To set an external device ID, assign the identifier to the externalDeviceId property of your config instance. Do this before you initialize the Adtrace SDK.

AdTraceConfig.setExternalDeviceId("{Your-External-Device-Id}")

Remember

You need to make sure this ID is unique to the user or device depending on your use-case. Using the same ID across different users or devices could lead to duplicated data. Talk to your Adtrace representative for more information.

Default tracker

Create a new tracker in your panel.
Open your app delegate and set the default tracker of your config:

adtraceConfig.setDefaultTracker("{TrackerToken}");

Replace {TrackerToken} with the tracker token you created in step one. Please note that the panel displays a tracker URL (including http://app.adtrace.io/). In your source code, you should specify only the six or seven-character token and not the entire URL.
Build and run your app. You should see a line like the following in your LogCat:

Default tracker: 'abc123'

Offline mode

Offline mode suspends transmission to our servers while retaining tracked data to be sent at a later point. While the Adtrace SDK is in offline mode, all information is saved in a file. Please be careful not to trigger too many events in offline mode.

Activate offline mode by calling setOfflineMode with the parameter true.

AdTrace.setOfflineMode(true);

Deactivate offline mode by calling setOfflineMode with false. When you put the Adtrace SDK back into online mode, all saved information is sent to our servers with the correct time information.

This setting is not remembered between sessions, meaning that the SDK is in online mode whenever it starts, even if the app was terminated in offline mode.

Disable tracking

You can disable Adtrace SDK tracking by invoking the method setEnabled with the enabled parameter as false. This setting is remembered between sessions, but it can only be activated after the first session.

AdTrace.setEnabled(false);

You can check if the Adtrace SDK is currently active with the method isEnabled. It is always possible to activate the Adtrace SDK by invoking setEnabled with the enabled parameter set to true.

Event buffering

If your app makes heavy use of event tracking, you might want to delay some network requests in order to send them in one batch every minute. You can enable event buffering with your AdTraceConfig instance:

AdTraceConfig adtraceConfig = new AdTraceConfig("{YourAppToken}", "{YourEnvironment}");

adtraceConfig.setEventBufferingEnabled(true);

AdTrace.start(adtraceConfig);

If nothing is set, event buffering is disabled by default.

Background tracking

The default behaviour of the Adtrace SDK is to pause sending network requests while the app is in the background. You can change this in your AdTraceConfig instance:

AdTraceConfig adtraceConfig = new AdTraceConfig("{YourAppToken}", "{YourEnvironment}");

adtraceConfig.setSendInBackground(true);

AdTrace.start(adtraceConfig);

Attribution callback​

User attribution​

Session and event callbacks​

Device IDs​

IDFA (iOS Identifier)​

GPS AdId (Google Play Services advertising identifier)​

AdId (Adtrace device identifier)​

Set external device ID (Experimental)​

Default tracker​

Offline mode​

Disable tracking​

Event buffering​

Background tracking​