Skip to main content

Basic Setup

Getting started​

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

Get the SDK​

As of version 2.0.1, you can add Adtrace SDK from 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.

Integrate the SDK into your app​

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

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

  • Start Manually
  • Event Buffering
  • Send In Background
  • Launch Deferred Deeplink
  • App Token
  • Log Level
  • Environment

Replace {YourAppToken} with your actual App Token. you can access it in adtrace panel.

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.

You can find an example scene with a button menu showing these options here: Assets/AdTrace/ExampleGUI/ExampleGUI.unity.

The source for this scene is located at Assets/AdTrace/ExampleGUI/ExampleGUI.cs.

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);
config.setLogLevel(AdTraceLogLevel.Suppress);

AdTrace.start(config);

If your target is Windows-based and you want to see the compiled logs from our library in released mode, redirect the log output to your app while testing it in debug mode.

Call the method setLogDelegate in the AdTraceConfig instance before starting the SDK.

//...
adtraceConfig.setLogDelegate(msg => Debug.Log(msg));
//...
AdTrace.start(adtraceConfig);

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, copy the google-play-services_lib folder (part of the Android SDK) into the Assets/Plugins/Android folder of your Unity project.

There are two main ways to download the Android SDK. Any tool using the Android SDK Manager will offer a quick link to download and install the Android SDK tools. Once installed, you can find the libraries in the SDK_FOLDER/extras/google/google_play_services/libproject/ folder.

If you aren't using any tools with the Android SDK Manager, download the official standalone Android SDK. Next, download the Android SDK Tools. by following the instructions in the SDK Readme.txt README provided by Google, located in the Android SDK folder.

You can now add only the part of the Google Play Services library that the Adtrace SDK needs the basement. To do this, add the play-services-basement-x.y.z.aar file to your Assets/Plugins/Android folder.

With Google Play Services library 15.0.0, Google has moved the classes needed to get the Google advertising ID into a play-services-ads-identifier package. Add this package to your app if you are using library version 15.0.0 or later. When you’re finished, please test to make sure the Adtrace SDK correctly obtains the Google advertising ID; we have noticed some inconsistencies, depending upon which Unity integrated development environment (IDE) version you use.

Download Google play services ads identifier: maven , direct link

Add permission to gather Google advertising ID​

If you are targeting Android 12 and above (API level 31), you need to add the com.google.android.gms.AD_ID permission to read the device's advertising ID. This is not done automatically during the post-build process Add the following line to your AndroidManifest.xml to enable the permission.

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

For more information, see Google's AdvertisingIdClient.Info documentation.

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 class io.adtrace.sdk.** { *; }
-keep class com.google.android.gms.common.ConnectionResult {
    int SUCCESS;
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
    com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
    java.lang.String getId();
    boolean isLimitAdTrackingEnabled();
}
-keep public class com.android.installreferrer.** { *; }

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 from Maven repository or via direct link and place the AAR file into your Plugins/Android

Huawei Referrer API​

As of v2.0.1, the Adtrace SDK supports install tracking on Huawei devices with Huawei App Gallery version 10.4 and higher. for more information see how to use oaid native plugin.

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 AdServices.framework (needed for Apple Search Ads tracking)
  • Adds the AdSupport.framework (needed for reading IDFA)
  • Adds the CoreTelephony.framework (needed for reading type of network device is connected to)
  • Adds the other linker flag -ObjC (needed to recognize Adtrace Objective-C categories during build time)
  • Enables Objective-C exceptions

In case you enable iOS 14+ support (Assets/AdTrace/Toggle iOS 14 Support), iOS post-build process will add two additional frameworks to your Xcode project:

  • Adds the AppTrackingTransparency.framework (needed to ask for user's consent to be tracked and obtain status of that consent)
  • Adds the StoreKit.framework (needed for communication with SKAdNetwork framework)

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 type of network device is connected to)
  • 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 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.