Basic Setup
Getting started
Unity SDK 3.0.0 wraps Android SDK 3.0.1 and iOS SDK 3.0.0. A running app reports unity3.0.0@android3.0.1 or unity3.0.0@ios3.0.0.
Get the SDK
Download AdTrace.unitypackage from the v3.0.0 release (or the latest build on the 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/Prefab/AdTrace.prefab to the first scene.
You can edit the Adtrace script parameters in the prefab Inspector 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 app token from the Adtrace panel.
Depending on whether you are building for testing or production, set Environment to Sandbox or Production.
Use Sandbox while testing. Switch to Production before you publish.
If you do not want the SDK to start on the scene Awake event, enable Start Manually and call AdTrace.start once from code:
AdTraceConfig config = new AdTraceConfig("{YourAppToken}", AdTraceEnvironment.Sandbox);
config.setLogLevel(AdTraceLogLevel.Verbose);
AdTrace.start(config);
setExternalDeviceId is a method on that config object. Call it before AdTrace.start:
AdTraceConfig config = new AdTraceConfig("{YourAppToken}", AdTraceEnvironment.Sandbox);
config.setExternalDeviceId("{YourExternalDeviceId}");
AdTrace.start(config);
Example scene: Assets/AdTrace/ExampleGUI/ExampleGUI.unity (source: 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 logsDebug- disable verbose logsInfo- disable debug logs (default)Warn- disable info logsError- disable warning logsAssert- disable error logsSuppress- 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
Apps targeting Android 12+ (API 31) need the com.google.android.gms.AD_ID permission to read the advertising ID.
From Unity SDK 3.0.0, the Unity post-build step adds com.google.android.gms.permission.AD_ID when the app manifest does not already declare it. You can still add it manually if you manage the manifest yourself:
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
The Android library shipped in the package is adtrace-android.aar. Unity 2022.3 can keep Target API 32. The Myket, Cafe Bazaar, and Samsung referrer plugins do not require Android platform 34.
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
Store referrers
Myket, Cafe Bazaar, and Samsung are separate packages on the same v3.0.0 release. Import only the store your app uses, after the core AdTrace.unitypackage.
| Package | Also includes |
|---|---|
AdTraceMyketReferrer.unitypackage | kotlin-stdlib |
AdTraceCafeBazaarReferrer.unitypackage | the same kotlin-stdlib |
AdTraceSamsungReferrer.unitypackage | no Kotlin library |
Each store prefab leaves referrer reading off by default. Call the matching method before AdTrace.start when that store referrer should be read:
AdTraceMyketReferrer.ReadMyketReferrer();
AdTraceCafeBazaarReferrer.ReadCafeBazaarReferrer();
AdTraceSamsungReferrer.ReadSamsungReferrer();
Opt-out methods: DoNotReadMyketReferrer, DoNotReadCafeBazaarReferrer, and DoNotReadSamsungReferrer.
Huawei Referrer API
The Adtrace SDK supports install tracking on Huawei devices with Huawei App Gallery version 10.4 and higher. See OAID / Huawei for the 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
Minimum iOS and tvOS is 12.0. The post-build step raises a lower deployment target and copies PrivacyInfo.xcprivacy into the Xcode project.
To run the iOS post-build process properly, use Unity 5 or later with iOS build support installed. It makes the following changes to the generated Xcode project:
- Adds the
iAd.framework(Apple Search Ads) - Adds the
AdServices.framework(Apple Search Ads) - Adds the
AdSupport.framework(IDFA) - Adds the
CoreTelephony.framework(network type) - Adds the other linker flag
-ObjC - Enables
Objective-C exceptions - Copies
PrivacyInfo.xcprivacy
If you enable iOS 14+ support (Assets/AdTrace/Toggle iOS 14 Support), the post-build process also adds:
AppTrackingTransparency.framework(ATT consent)StoreKit.framework(SKAdNetwork)
Android post-build process
The Android post-build process updates AndroidManifest.xml under Assets/Plugins/Android/. If the file is missing, it copies AdTraceAndroidManifest.xml. When a manifest already exists, it makes these changes:
- Adds the
INTERNETpermission - Adds the
ACCESS_WIFI_STATEpermission (needed if you are not distributing via the Play Store) - Adds the
ACCESS_NETWORK_STATEpermission - Adds the
BIND_GET_INSTALL_REFERRER_SERVICEpermission (Google Play Referrer API) - Adds
com.google.android.gms.permission.AD_IDwhen it is not already declared (Unity SDK 3.0.0+) - Adds the Adtrace broadcast receiver for the Google Play Store
INSTALL_REFERRERintent (see the Android SDK README)
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.