Basic Setup

This is the Android SDK of Adtrace. You can read more about Adtrace at our website.

Example apps

Java Example app
Kotlin Example app
TWA Example app
WebBridge Example app
TV Example app
WebBridge js files

Basic setup

The followings are the minimum required steps to integrate the Adtrace SDK in your Android app. We assume that you are using Android Studio for your Android development. The minimum supported Android API level for the Adtrace SDK integration is 9 (Gingerbread).

Add Adtrace SDK(s)

If you are using Maven, add the following to your build.gradle file:

Maven

build.gradle

dependencies {
implementation 'io.adtrace:android-sdk:2.5.1'
implementation 'com.android.installreferrer:installreferrer:2.2'

// Add the following if you are using the Adtrace SDK inside web views on your app
implementation 'io.adtrace:android-sdk-plugin-webbridge:2.5.1'
}

Add as an archive

You can find latest versions of the SDKs on Maven Central Repository. you can also add the Adtrace SDK and web view extension as JAR or AAR files, which can be downloaded from our releases page.

warning

Note: DO NOT confuse this case with TWA (Trusted Web Activity).

Note: The minimum supported Android API level for the web view extension is 17 (Jelly Bean).

Add Google Play Services

Since the 1st of August 2014, apps in the Google Play Store must use the Google Advertising ID to uniquely identify devices. To enable the Google Advertising ID for our SDK, you must integrate Google Play Services. If you haven't done this yet, please add dependency to the Google Play Services library by adding the following dependency to your dependencies block of app's build.gradle file:

build.gradle

dependencies {
    implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
}

info

The Adtrace SDK is not tied to any specific version of the play-services-analytics part of the Google Play Services library. You can use the latest version of the library, or any other version you need.

Add Permissions

tip

If your app targets children, you should remove the AD_ID permission to prevent the Adtrace SDK from reading it. See Set up apps for children instructions.

The Adtrace SDK requires the following permissions. Add them to your AndroidManifest.xml file if they are not already present:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

If you are not targeting the Google Play Store, you need to add the following permission:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

If you are targeting Android 12 (API level 31) and above , you need to add the com.google.android.gms.AD_ID permission to read the device's advertising ID.

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

Set up Proguard

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.** { *; }

If you are not publishing your app in the Google Play Store, use the following io.adtrace.sdk package rules:

-keep public class io.adtrace.sdk.** { *; }

Add Install Referrer

The install referrer is a unique identifier which you can use to attribute an app install to a source. The Adtrace SDK requires this information to perform attribution.

To support the Google Play Referrer API, make sure you have the following in your build.gradle file:

build.gradle

dependencies {
    implementation 'com.android.installreferrer:installreferrer:2.2'
}

Important

Google has deprecated the INSTALL_REFERRER intent method of delivering referrer information for Google Play Services. If you are currently using this method, please migrate to the Google Play Referrer API.

Integrate to your app

If you are integrating Adtrace into a standard app (native) follow standard app instructions. if you are integrating Adtrace into web views, use webview app instructions.

Standard SDK

We recommend using a global Android Application class to initialize the Adtrace SDK. If you do not have this set up, follow these steps:

1. Create a class that extends the Application.
2. Open the AndroidManifest.xml file and locate the application element.
3. Add the android:name attribute and set it to the name of your application class. For example, if your Application class is named GlobalApplication:

AndroidManifest.xml

<application
    android:name=".GlobalApplication">
    <!-- ... -->
</application>

4. In your Application class, find or add the onCreate method. Add the following code to initialize the Adtrace SDK:

GlobalApplication.java

import io.adtrace.sdk.AdTrace;
import io.adtrace.sdk.AdTraceConfig;

public class GlobalApplication extends Application {

@Override
public void onCreate() {
super.onCreate();
String appToken = "{YourAppToken}";
String environment = AdTraceConfig.ENVIRONMENT_SANDBOX;
AdTraceConfig config = new AdTraceConfig(this, appToken, environment);
AdTrace.onCreate(config);
}
}

tip

you can find App Token in Adtrace panel.

5. Set the environment variable to either sandbox or production mode. When running tests you should ensure that your environment is set to AdTraceConfig.ENVIRONMENT_SANDBOX. Change this to AdTraceConfig.ENVIRONMENT_PRODUCTION before release.

String environment = AdTraceConfig.ENVIRONMENT_SANDBOX;
String environment = AdTraceConfig.ENVIRONMENT_PRODUCTION;

WebView SDK

Before you start, you will need to obtain the reference to your WebView object. Once you have done this:

1. Call webView.getSettings().setJavaScriptEnabled(true) to enable Javascript in the web view.
2. Start the default instance of AdTraceBridgeInstance by calling AdTraceBridge.registerAndGetInstance(getApplication(), webview). This will register the Adtrace bridge as a Javascript interface in the web view.
3. Call AdTraceBridge.setWebView() to set a new WebView if needed.
4. Call AdTraceBridge.unregister() to unregister the AdTraceBridgeInstance and WebView. Once you have completed these steps, your activity should look like this:

MainActivity.java

public class MainActivity extends Activity {
@Override protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

WebView webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);
webView.setWebChromeClient(new WebChromeClient());
webView.setWebViewClient(new WebViewClient());

AdTraceBridge.registerAndGetInstance(getApplication(), webView);
try {
webView.loadUrl("file:///android_asset/AdTraceExample-WebView.html");
} catch (Exception e) {
e.printStackTrace();
}

}

@Override protected void onDestroy() {
AdTraceBridge.unregister();
super.onDestroy();
}
}

Now the Javascript bridge will be able to communicate between your page and the Adtrace Android Native SDK. In your HTML file, import the Adtrace Javascript files which are located in the root of the assets folder . If your HTML file is there as well, import them like this:

<script type="text/javascript" src="adtrace.js"></script>
<script type="text/javascript" src="adtrace_event.js"></script>
<script type="text/javascript" src="adtrace_third_party_sharing.js"></script>
<script type="text/javascript" src="adtrace_config.js"></script>

js files to import in your html

Once you add your references to the Javascript files, use them in your HTML file to initialize the Adtrace SDK:

let yourAppToken = "{YourAppToken}";
let environment = AdTraceConfig.EnvironmentSandbox;
let adtraceConfig = new AdTraceConfig(yourAppToken, environment);
AdTrace.onCreate(adtraceConfig);

Replace {YourAppToken} with your app token. You can find this in the panel.

Next, set your environment to the corresponding value, depending on whether you are still testing or are in production mode:

let environment = AdTraceConfig.EnvironmentSandbox;
let environment = AdTraceConfig.EnvironmentProduction;

tip

you can find App Token in Adtrace Panel.

tip

Set your value to AdTraceConfig.EnvironmentSandbox if (and only if) you or someone else is testing your app. Make sure you set the environment to AdTraceConfig.EnvironmentProduction just before you publish the app. Set it back to AdTraceConfig.EnvironmentSandbox if you start developing and testing again. We use this environment to distinguish between real traffic and test traffic from test devices. Keeping it updated according to your current status is very important!

Session tracking

You need to set up session tracking so that the SDK can start to send information to the Adtrace backend. Follow the instructions below to set this up in your app.

warning

Session tracking are essential for the SDK to function properly. The SDK must "start" when the app starts and "pause" when the app pauses to ensure accurate data collection.

API level 14 and higher

1. Add a private class that implements the ActivityLifecycleCallbacks interface. If you don't have access to this interface, your app is targeting an Android API level lower than 14. You will have to manually update each activity by following the instructions. If you have AdTrace.onResume and AdTrace.onPause calls on each of your app's activities, you should remove them.
2. Edit the onActivityResumed(Activity activity) method and add a call to AdTrace.onResume(). Edit the onActivityPaused(Activity activity) method and add a call to AdTrace.onPause().
3. Add the onCreate() method with the Adtrace SDK is configured and call registerActivityLifecycleCallbacks with an instance of the created ActivityLifecycleCallbacks class.

import io.adtrace.sdk.AdTrace;
import io.adtrace.sdk.AdTraceConfig;

public class GlobalApplication extends Application {
@Override public void onCreate() {
super.onCreate();
String appToken = "{YourAppToken}";
String environment = AdTraceConfig.ENVIRONMENT_SANDBOX;
AdTraceConfig config = new AdTraceConfig(this, appToken, environment);
AdTrace.onCreate(config);

registerActivityLifecycleCallbacks(new AdTraceLifecycleCallbacks());
//...
}
private static final class AdTraceLifecycleCallbacks implements ActivityLifecycleCallbacks {
@Override public void onActivityResumed(Activity activity) {
AdTrace.onResume();
}
@Override public void onActivityPaused(Activity activity) {
AdTrace.onPause();
}
}
}

API level between 9 and 13

If your app minSdkVersion in gradle is between 9 and 13, consider updating it to at least 14 to simplify the integration process. Consult the official Android panel to find out the latest market share of the major versions.

To provide proper session tracking, certain Adtrace SDK methods are called every time an activity resumes or pauses (otherwise the SDK might miss a session start or end). In order to do so, follow these steps for each Activity of your app:

• In your Activity's onResume method, call AdTrace.onResume(). Create the method if needed.
• In your Activity's onPause method, call AdTrace.onPause(). Create the method if needed.

After these steps, your activity should look like this:

import io.adtrace.sdk.AdTrace;

// ...
public class YourActivity extends Activity {
protected void onResume() {
super.onResume();
AdTrace.onResume();
}

protected void onPause() {
super.onPause();
AdTrace.onPause();
}
}

Repeat these steps for every Activity in your app. Don't forget to repeat these steps whenever you create a new activity in the future. Depending on your coding style, you might want to implement this in a common superclass of all your activities.

SDK log

To set the verbosity of logging, call the setLogLevel method on your config instance.

Java

adtraceConfig.setLogLevel(LogLevel.WARN);

Javascript

adtraceConfig.setLogLevel(AdTraceConfig.LogLevelWarn);

If you want to disable all logging, set the log level to suppress:

• Java
• Javascript

AdTraceConfig config = new AdTraceConfig(this, appToken, environment, true);
config.setLogLevel(LogLevel.SUPPRESS);
AdTrace.onCreate(config);

production mode

When you want to debug, use sandbox and before publishing your application set environment to production. the only difference between these two modes is that your requests will be separated from the production and real one from your users, and you can filter it in the panel. this also stops the logs from being printed.

Build your app

Well done! You should now be able to build and run your app. Enable logging to check for any issues. You are ready to start attributing your users with the Adtrace SDK.

For Trusted Web Activity (TWA) apps, see the dedicated TWA Integration guide.