Adtrace Sdk Unity by adtrace - 2


This is the Unity SDK of

Unknown VersionMIT LicenseUpdated 65 days agoCreated on June 10th, 2019
Go to source

English | فارسی

Adtrace logo


This is the Unity SDK of Adtrace™. It supports iOS, Android. You can read more about Adtrace™ at

Note: Adtrace Unity SDK is compatible with Unity 5 and newer versions.

Table of contents

Quick start


Event tracking

Custom parameters

Additional features

Testing and troubleshooting

Quick start

Example app

There are example Unity scene inside the ExampleGUI directory. In there you can check how the AdTrace SDK can be integrated.

And The source for this example scene is ExampleGUI.cs .

Getting started

To integrate the Adtrace SDK into your Unity project, follow these steps.

Get the SDK

As of version 1.0.3, you can download the latest version from our releases page.

Add the SDK to your project

Open your project in the Unity Editor, go to Assets → Import Package → Custom Package and select the downloaded Unity package file.

Import package

Adtrace project settings

Once the AdTrace SDK has been added to your app, certain tweaks are going to be performed so that the AdTrace SDK can work properly. Below you can find a description of every additional thing that the AdTrace SDK performs after you’ve added it to your app and what needs to be done by you in order for AdTrace SDK to work properly.

Google Play Services

Since August 1st 2014, apps in the Google Play Store must use the Google Advertising ID to uniquely identify devices. To allow the AdTrace SDK to use the Google Advertising ID, integrate Google Play Services. To do this add play-services-ads-identifier into the Assets/Plugins/Android folder of your Unity project.

There is two way to download this:

Testing for the Google advertising ID

To check whether the AdTrace SDK is receiving the Google advertising ID, start your app by configuring the SDK to run in sandbox mode and set the log level to verbose. After that, track a session or an event in the app and check the list of parameters recorded in the verbose logs. If you see the gps_adid parameter, our SDK has successfully read the Google advertising ID.

Proguard settings

If you are using Proguard, add these lines to your Proguard file:

-keep public class io.adtrace.sdk.** { *; }
-keep class {
    int SUCCESS;
-keep class {$Info getAdvertisingIdInfo(android.content.Context);
-keep class$Info {
    java.lang.String getId();
    boolean isLimitAdTrackingEnabled();
-keep public class** { *; }

Google Install Referrer

In order to attribute the install of an Android app, AdTrace needs information about the Google install referrer. You can set up your app to get this by using the Google Play Referrer API or by catching the Google Play Store intent with a broadcast receiver.

Google introduced the Google Play Referrer API in order to provide a more reliable and secure way than the Google Play Store intent to obtain install referrer information and to help attribution providers fight click injections. The Google Play Store intent will exist in parallel with the API temporarily, but is set to be deprecated in the future. We encourage you to support this.

The AdTrace post-build process catches the Google Play Store intent; you can take a few additional steps to add support for the new Google Play Referrer API.

To add support for the Google Play Referrer API, download the install referrer library and place the AAR file into your Assets/Plugins/Android folder:

Integrate the SDK into your app

Add the prefab from Assets/AdTrace/Prefab/AdTrace.prefab to the first scene.

You can edit the AdTrace script parameters in the prefab Inspector menu to set up the following options:

AdTrace Prefab

Replace {YourAppToken} with your actual App Token.

Depending on whether you are building your app for testing or for production, change the Environment setting to either ‘Sandbox’ or ‘Production’.

Important: Set the value to Sandbox if you or someone else is testing your app. Make sure to set the environment to Production before you publish the app. Set it back to Sandbox if you start testing again. Also, have in mind that by default AdTrace panel is showing production traffic of your app, so in case you want to see traffic you generated while testing in sandbox mode, make sure to switch to sandbox traffic view within panel.

We use the environment setting to distinguish between real traffic and artificial traffic from test devices. Please make sure to keep your environment setting updated.

If you don’t want the Adtrace SDK to start automatically with the app’s Awake event, select Start Manually. With this option, you’ll initialize and start the Adtrace SDK from the within the code by calling the AdTrace.start method with the AdTraceConfig object as a parameter.

Post-build process

To complete the app build process, the Adtrace Unity package performs custom post-build actions to ensure the Adtrace SDK can work properly inside the app.

This process is performed by the OnPostprocessBuild method in AdTraceEditor.cs. Log output messages are written to the Unity IDE console output window.

iOS post-build process

To execute the iOS post-build process properly, use Unity 5 or later and have iOS build support installed. The iOS post-build process makes the following changes to your generated Xcode project:

  • Adds the iAd.framework (needed for Apple Search Ads tracking)
  • Adds the AdSupport.framework (needed for reading IDFA)
  • Adds the CoreTelephony.framework (needed for reading MMC and MNC)
  • Adds the other linker flag -ObjC (needed to recognize Adtrace Objective-C categories during build time)
  • Enables Objective-C exceptions

Android post-build process

The Android post-build process makes changes to the AndroidManifest.xml file located in Assets/Plugins/Android/. It also checks for the presence of the AndroidManifest.xml file in the Android plugins folder. If the file is not there, it creates a copy from our compatible manifest file AdtraceAndroidManifest.xml. If there is already an AndroidManifest.xml file, it makes the following changes:

  • Adds the INTERNET permission (needed for Internet connection)
  • Adds the ACCESS_WIFI_STATE permission (needed if you are not distributing your app via the Play Store)
  • Adds the ACCESS_NETWORK_STATE permission (needed for reading the MMC and MNC)
  • Adds the BIND_GET_INSTALL_REFERRER_SERVICE permission (needed for the new Google install referrer API to work)
  • Adds the Adtrace broadcast receiver (needed for getting install referrer information via Google Play Store intent). For more details, consult the official Android SDK README.

Note: If you are using your own broadcast receiver to handle the INSTALL_REFERRER intent, you don’t need to add the Adtrace broadcast receiver to your manifest file. Remove it, but add the call to the Adtrace broadcast receiver inside your own receiver, as described in the Android guide.

SDK signature

If the SDK signature is enabled on your account and you have access to App Secrets in your panel, add all secret parameters (secretId, info1, info2, info3, info4) to the setAppSecret method of AdTraceConfig instance:

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

adtraceConfig.setAppSecret(secretId, info1, info2, info3, info4);


The SDK signature is now integrated in your app.

Adtrace logging

You can increase or decrease the granularity of the logs you see by changing the value of Log Level to one of the following:

  • Verbose - enable all logs
  • Debug - disable verbose logs
  • Info - disable debug logs (default)
  • Warn - disable info logs
  • Error - disable warning logs
  • Assert - disable error logs
  • Suppress - disable all logs

If you want to disable all of your log output when initializing the AdTrace SDK manually, set the log level to suppress and use a constructor for the AdTraceConfig object. This opens a boolean parameter where you can enter whether the suppress log level should be supported or not:

string appToken = "{YourAppToken}";
AdTraceEnvironment environment = AdTraceEnvironment.Sandbox;

AdTraceConfig config = new AdTraceConfig(appToken, environment, true);



Deeplinking Overview

We support deeplinking on iOS and Android platforms.

If you are using AdTrace tracker URLs with deeplinking enabled, it is possible to receive information about the deeplink URL and its content. Users may interact with the URL regardless of whether they have your app installed on their device (standard deeplinking) or not (deferred deeplinking).

With standard deeplinking, the Android platform lets you receive deeplink content; however, Android does not automatically support deferred deeplinking. To access deferred deeplink content, you can use the AdTrace SDK.

Set up deeplink handling in your app on a native level within your generated Xcode project (for iOS) and Android Studio / Eclipse project (for Android).

Standard deeplinking

Information about standard deeplinks cannot be delivered to you in Unity C# code. Once you enable your app to handle deeplinking, you’ll get information about the deeplink on a native level. For more information, here’s how to enable deeplinking for Android and iOS apps.

Deferred deeplinking

In order to get content information about the deferred deeplink, set a callback method on the AdTraceConfig object. This will receive one string parameter where the content of the URL is delivered. Set this method on the config object by calling the method setDeferredDeeplinkDelegate:

// ...

private void DeferredDeeplinkCallback(string deeplinkURL) {
   Debug.Log("Deeplink URL: " + deeplinkURL);

   // ...

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



With deferred deeplinking, there is an additional setting you can set on the AdTraceConfig object. Once the AdTrace SDK gets the deferred deeplink information, you can choose whether our SDK should open the URL or not. You can set this option by calling the setLaunchDeferredDeeplink method on the config object:

// ...

private void DeferredDeeplinkCallback(string deeplinkURL) {
   Debug.Log ("Deeplink URL: " + deeplinkURL);

   // ...

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



If nothing is set, the AdTrace SDK will always try to launch the URL by default.

To enable your apps to support deeplinking, set up schemes for each supported platform.

To set up deeplink handling in an Android app on a native level, follow the instructions in our official Android SDK README.

This should be done in native Android Studio / Eclipse project.

This should be done in native Xcode project.

To set up deeplink handling in an iOS app on a nativel level, please use a native Xcode project and follow the instructions in our official iOS SDK README.

Event tracking

Track an event

You can use AdTrace to track any event in your app. If you want to track every tap on a button, create a new event token in your panel. Let’s say that the event token is abc123. In your button’s click handler method, add the following lines to track the click:

AdTraceEvent adtraceEvent = new AdTraceEvent("abc123");

Track revenue

If your users generate revenue by engaging with advertisements or making in-app purchases, you can track this with events. For example: if one add tap is worth one Euro cent, you can track the revenue event like this:

AdTraceEvent adtraceEvent = new AdTraceEvent("abc123");
adtraceEvent.setRevenue(0.01, "EUR");

When you set a currency token, AdTrace will automatically convert the incoming revenues using the open exchange API into a reporting revenue of your choice.

If you want to track in-app purchases, please make sure to call trackEvent only if the purchase is finished and the item has been purchased. This is important in order to avoid tracking revenue your users did not actually generate.

Revenue deduplication

Add an optional transaction ID to avoid tracking duplicated revenues. The SDK remembers the last ten transaction IDs and skips revenue events with duplicate transaction IDs. This is especially useful for tracking in-app purchases.

AdTraceEvent adtraceEvent = new AdTraceEvent("abc123");

adtraceEvent.setRevenue(0.01, "EUR");


Custom parameters

Custom parameters overview

In addition to the data points the AdTrace SDK collects by default, you can use the AdTrace SDK to track and add as many custom values as you need (user IDs, product IDs, etc.) to the event or session. Custom parameters are only available as raw data and will not appear in your AdTrace panel.

Use callback parameters for the values you collect for your own internal use, and partner parameters for those you share with external partners. If a value (e.g. product ID) is tracked both for internal use and external partner use, we recommend using both callback and partner parameters.

Event parameters

Event callback parameters

If you register a callback URL for events in your panel, we will send a GET request to that URL whenever the event is tracked. You can also put key-value pairs in an object and pass it to the trackEvent method. We will then append these parameters to your callback URL.

For example, if you’ve registered the URL, then you would track an event like this:

AdTraceEvent adtraceEvent = new AdTraceEvent("abc123");

adtraceEvent.addCallbackParameter("key", "value");
adtraceEvent.addCallbackParameter("foo", "bar");


In this case we would track the event and send a request to:

Event partner parameters

Once your parameters are activated in the panel, you can send them to your network partners.

This works the same way as callback parameters; add them by calling the addPartnerParameter method on your AdTraceEvent instance.

AdTraceEvent adtraceEvent = new AdTraceEvent("abc123");

adtraceEvent.addPartnerParameter("key", "value");
adtraceEvent.addPartnerParameter("foo", "bar");


Event callback identifier

You can add custom string identifiers to each event you want to track. We report this identifier in your event callbacks, letting you know which event was successfully tracked. Set the identifier by calling the setCallbackId method on your AdTraceEvent instance:

AdTraceEvent adtraceEvent = new AdTraceEvent("abc123");



Event value

You can also add custom string value to event. You can set this value by calling the setEventValue method on your AdTraceEvent instance:

AdTraceEvent adtraceEvent = new AdTraceEvent("abc123");



Session parameters

Session parameters are saved locally and sent with every AdTrace SDK event and session. Whenever you add these parameters, we save them (so you don’t need to add them again). Adding the same parameter twice will have no effect.

It’s possible to send session parameters before the AdTrace SDK has launched. Using the SDK delay, you can therefore retrieve additional values (for instance, an authentication token from the app’s server), so that all information can be sent at once with the SDK’s initialization.

Session callback parameters

You can save event callback parameters to be sent with every AdTrace SDK session.

The session callback parameters’ interface is similar to the one for event callback parameters. Instead of adding the key and its value to an event, add them via a call to the addSessionCallbackParameter method of the AdTrace instance:

AdTrace.addSessionCallbackParameter("foo", "bar");

Session callback parameters merge with event callback parameters, sending all of the information as one, but event callback parameters take precedence over session callback parameters. If you add an event callback parameter with the same key as a session callback parameter, we will show the event value.

You can remove a specific session callback parameter by passing the desired key to the removeSessionCallbackParameter method of the AdTrace instance.


To remove all keys and their corresponding values from the session callback parameters, you can reset them with the resetSessionCallbackParameters method of the AdTrace instance.


Session partner parameters

In the same way that session callback parameters are sent with every event or session that triggers our SDK, there are also session partner parameters.

These are transmitted to network partners for all of the integrations activated in your panel.

The session partner parameters interface is similar to the event partner parameters interface, however instead of adding the key and its value to an event, add it by calling the addSessionPartnerParameter method of the AdTrace instance.

AdTrace.addSessionPartnerParameter("foo", "bar");

Session partner parameters merge with event partner parameters. However, event partner parameters take precedence over session partner parameters. If you add an event partner parameter with the same key as a session partner parameter, we will show the event value.

To remove a specific session partner parameter, pass the desired key to the removeSessionPartnerParameter method of the AdTrace instance.


To remove all keys and their corresponding values from the session partner parameters, reset it with the resetSessionPartnerParameters method of the AdTrace instance.


Delay start

Delaying the start of the AdTrace SDK gives your app time to receive any session parameters (such as unique identifiers) you may want to send on install.

Set the initial delay time in seconds with the method setDelayStart in the AdTraceConfig instance:


In this example, the AdTrace SDK is prevented from sending the initial install session and any new event for 5.5 seconds. After 5.5 seconds (or if you call AdTrace.sendFirstPackages() during that time), every session parameter is added to the delayed install session and events, and the AdTrace SDK will work as usual.

You can delay the start time of the AdTrace SDK for a maximum of 10 seconds.

Additional features

Once you integrate the AdTrace SDK into your project, you can take advantage of the following features:

Push token (uninstall tracking)

Push tokens are used for Audience Builder and client callbacks; they are also required for uninstall and reinstall tracking.

To send us a push notification token, call the setDeviceToken method on the AdTrace instance when you obtain your app’s push notification token (or whenever its value changes):


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:

  1. Create a method with the signature of the delegate Action<AdTraceAttribution>.

  2. After creating the AdTraceConfig object, call the adtraceConfig.setAttributionChangedDelegate with the previously created method. You can also use a lambda with the same signature.

  3. 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 com.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);


    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

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);


// ...

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

Add the following callback function for failed tracked events:

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);


// ...

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

For successfully tracked sessions:

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);


// ...

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

For failed tracked sessions:

// ...

AdTraceConfig adtraceConfig = new AdTraceConfig("{Your App Token}", AdTraceEnvironment.Sandbox);


// ...

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

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();

Note: 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.

Send installed apps

To increase the accuracy and security in fraud detection, you can enable the sending of installed applications on user’s device as follows:


Note: This option is disabled by default.

Device IDs

The AdTrace SDK lets you receive device identifiers.

iOS Advertising Identifier

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

string idfa = AdTrace.getIdfa();

Google Play Services advertising identifier

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.

Amazon advertising identifier

If you need to get the Amazon advertising ID, call the getAmazonAdId method on AdTrace instance:

string amazonAdId = AdTrace.getAmazonAdId();

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.

Pre-installed trackers

To use the AdTrace SDK to recognize users whose devices came with your app pre-installed, follow these steps:

  1. Create a new tracker in your panel.
  2. Set the default tracker of your AdTraceConfig:
AdTraceConfig adtraceConfig = new AdTraceConfig(appToken, environment);

Replace {TrackerToken} with the tracker token you created in step 2. E.g. {abc123}

Although the panel displays a tracker URL (including, in your source code you should only enter the six or seven-character token and not the entire URL.

  1. Build and run your app. You should see a line like the following in the log output:

    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.


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.


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}");



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}");



GDPR right to be forgotten

In accordance with article 17 of the EU’s General Data Protection Regulation (GDPR), you can notify AdTrace when a user has exercised their right to be forgotten. Calling the following method will instruct the AdTrace SDK to communicate the user’s choice to be forgotten to the AdTrace backend:


Upon receiving this information, AdTrace will erase the user’s data and the AdTrace SDK will stop tracking the user. No requests from this device will be sent to AdTrace in the future.

Please note that even when testing, this decision is permanent. It is not reversible.

Testing and troubleshooting

Debug information in iOS

Even with the post build script it is possible that the project is not ready to run out of the box.

If needed, disable dSYM File. In the Project Navigator, select the Unity-iPhone project. Click the Build Settings tab and search for debug information. There should be an Debug Information Format or DEBUG_INFORMATION_FORMAT option. Change it from DWARF with dSYM File to DWARF.

Show all projects by adtrace