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.

Adtrace implementation TWA implementation structure

Defining the issue

As more and more developers use TWA for android apps and there is no stable official way to communicate between native android code and web loaded (as web bridge does), and as the application needed to be considered like a normal native android app, requests need to be sent from native. the issues are:

1. native thread runs the web page ASAP (initial sdk tasks might not have time to be initialized, so no session and sdk_click)
2. events mostly happen on user interaction, which in this case is the web interface, these data must be connected to the sdk_click sent by native. (in simpler words, events must be connected to the install, which is related to device id)

How to fix these issues

in order to explain simpler and according to the code, make sure to check TWA example project and it's branches

App opens and web page launch

the trick is to delay launch a little bit(considering UX it must not be more than few seconds, generally not more than 3-5 seconds) and make sure Adtrace sdk is initialized properly.

question: how to make sure sdk initialized properly?

answer: set attribution callback. this callback is called whenever sdk_click is sent successfully and a device is created by adtrace server. it will passes an Attribution object which contains adid. whenever adid is generated by the server the device is created. this process takes at most 1-2 seconds.

Sending events

The trick for this is to use S2S (server to server) event. the rule is to send S2S event for each device (e.g. sdk_click or install) exactly as it happens. so what unifity each sdk_click from others in terms of SDK is device ID (does not matter which device id as long as it is known by both native and web page).

Step 1: pass device ID to web page

When launching TWA from android native it can accept url with query parameters. so the web page must be expecting a device id from the native.

Step 2: call server to send event along with device ID

Assuming step 1 is done correctly, now web page accesses device id. the only parameter needed for S2S event can be configured by server expect device id which is provided from web page. in simpler words web page calls server (customer's server) to send specific event (event token from panel) for a specific device or install (device id).

Step 3: configure sending S2S event from customer's servers

Now, server has all the needed information for sending S2S event. the process of sending S2S event and troubleshooting it is provided by S2S document. please contact with Adtrace support for the documents.