Skip to main content

Getting started with the Android SDK

This guide walks you through the initial setup of the Adtrace Android SDK. You'll learn how to install the SDK, configure your project, initialize the SDK, and verify that your integration is successful. By the end of this guide, your app will be ready to track installs, sessions, and events.

Choose your integration type​

This page covers native Android apps (Java / Kotlin). For TWA or WebBridge, choose your path on the Android SDK overview.

1. Get the Adtrace SDK​

Add the Adtrace SDK to your Android project using one of these methods:

These steps assume you are using Android Studio. If your app uses an Android WebView, also complete the WebBridge (WebView) guide after the native setup steps (or use Case A if tracking is JS-only). For Google Play Store apps, also complete Add Install Referrer.

Important

The minimum supported Android API level for the Adtrace SDK integration is 9 (Gingerbread).

Maven​

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

build.gradle
dependencies {
    implementation 'io.adtrace:android-sdk:2.6.0'
}

2. Add Google Play Services​

Apps that target the Google Play Store must use the Google Advertising ID (gps_adid) to identify devices. Add the play-services-ads-identifier dependency so the Adtrace SDK can read it:

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

3. Add Install Referrer​

Apps that target the Google Play Store must use the Google Play Referrer API so Adtrace can attribute installs. Add the Install Referrer library to your app:

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

If you use Proguard or R8, keep the Install Referrer classes. The required rule is already included in Set up Proguard.

4. Add Permissions​

Declare the permissions the Adtrace SDK needs in your AndroidManifest.xml.

Required permissions​

Add these permissions for network access:

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

If your app does not target the Google Play Store​

Add this permission so the SDK can read network state:

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

Google Advertising ID (AD_ID)​

If your app targets Android 12 (API level 31) or higher and the Google Play Store, add this permission so the SDK can read the advertising ID (gps_adid):

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

If your app targets children (COPPA / Play Store Kids) or must not read the advertising ID, remove the permission instead:

AndroidManifest.xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove"/>
</manifest>

See apps for children for the full kids setup.

5. Set up Proguard​

If you use Proguard (or R8) to optimize your app, add these rules so required classes are not removed.

proguard-rules.pro
-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 your app does not target the Google Play Store​

Add this rule as well:

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

6. Initialize the Adtrace SDK​

This section is for native Android apps (Java / Kotlin). For WebView apps, go to WebBridge (WebView). For Trusted Web Activity, follow the TWA documentation.

To initialize the Adtrace SDK you need:

  • appToken: your Adtrace app token from the Adtrace panel
  • environment: use AdTraceConfig.ENVIRONMENT_SANDBOX while testing and AdTraceConfig.ENVIRONMENT_PRODUCTION before you publish. Adtrace uses this to separate test traffic from real traffic. Switch back to sandbox when you test again.

Initialize the SDK in a global Android Application class. If you do not have one yet, follow these steps:

  1. Create a class that extends Application.
  2. Open AndroidManifest.xml and find the <application> element.
  3. Set android:name to your application class. For example, if the class is GlobalApplication:
AndroidManifest.xml
<application
    android:name=".GlobalApplication">
    <!-- ... -->
</application>
  1. In your Application class, initialize Adtrace in onCreate:
GlobalApplication.java
import android.app.Application;
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);
    }
}

Replace {YourAppToken} with your app token from the Adtrace panel.

  1. Set environment based on your stage:
// Testing
String environment = AdTraceConfig.ENVIRONMENT_SANDBOX;

// Production (before release)
String environment = AdTraceConfig.ENVIRONMENT_PRODUCTION;
tip

Initialization alone is not enough. Continue with Configure session tracking so the SDK records sessions correctly.

7. Configure session tracking​

Session tracking tells the Adtrace SDK when your app starts and pauses so it can send accurate session data to the Adtrace backend. This step is required for the SDK to work correctly.

Call Adtrace lifecycle methods at the right points in your app lifecycle. The setup depends on your app's minSdkVersion.

Add session tracking to the GlobalApplication class from Initialize the Adtrace SDK:

  1. If you already call AdTrace.onResume() or AdTrace.onPause() in individual activities, remove those calls.
  2. After AdTrace.onCreate(config) in Application.onCreate, register an ActivityLifecycleCallbacks implementation.
  3. In onActivityResumed, call AdTrace.onResume().
  4. In onActivityPaused, call AdTrace.onPause().

Add this line after AdTrace.onCreate(config):

registerActivityLifecycleCallbacks(new AdTraceLifecycleCallbacks());

Add this class inside your Application class:

private static final class AdTraceLifecycleCallbacks implements Application.ActivityLifecycleCallbacks {
    @Override
    public void onActivityResumed(Activity activity) {
        AdTrace.onResume();
    }

    @Override
    public void onActivityPaused(Activity activity) {
        AdTrace.onPause();
    }

    @Override
    public void onActivityCreated(Activity activity, Bundle savedInstanceState) {}

    @Override
    public void onActivityStarted(Activity activity) {}

    @Override
    public void onActivityStopped(Activity activity) {}

    @Override
    public void onActivitySaveInstanceState(Activity activity, Bundle outState) {}

    @Override
    public void onActivityDestroyed(Activity activity) {}
}

Complete Application class (init + session tracking)​

Use this as the final GlobalApplication for API level 14 and above:

GlobalApplication.java
import android.app.Activity;
import android.app.Application;
import android.os.Bundle;
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();
        }

        @Override
        public void onActivityCreated(Activity activity, Bundle savedInstanceState) {}

        @Override
        public void onActivityStarted(Activity activity) {}

        @Override
        public void onActivityStopped(Activity activity) {}

        @Override
        public void onActivitySaveInstanceState(Activity activity, Bundle outState) {}

        @Override
        public void onActivityDestroyed(Activity activity) {}
    }
}

API level 9 to 13 (optional)​

Most apps can skip this section and use API level 14 and above above. Expand only if your minSdkVersion is still between 9 and 13.

Show session setup for API level 9 to 13
tip

If possible, raise minSdkVersion to 14 or higher so you can use the ActivityLifecycleCallbacks setup above.

For apps that still target API level 13 or below, call Adtrace in every activity:

  1. In each activity's onResume, call AdTrace.onResume().
  2. In each activity's onPause, call AdTrace.onPause().
  3. Repeat for every activity in your app. You can put this in a shared base activity class if you use one.
YourActivity.java
import io.adtrace.sdk.AdTrace;

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

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

8. WebBridge​

Optional. Only for apps that use an Android WebView. Native-only apps can skip to 9. Test the integration. For TWA apps, use the TWA documentation instead. Do not use WebBridge for TWA.

If your app loads content in a WebView and you need Adtrace to record activity from that web layer, follow the dedicated WebBridge (WebView) guide.

That guide covers:

  • Case A (WebBridge-only): initialize from JavaScript
  • Case B (hybrid): initialize from native, track from native and JS
  • Bridge registration, JS assets, APIs, and troubleshooting
One SDK instance

Initialize Adtrace once per process (native or JS). Calling onCreate twice logs AdTrace already initialized.

See also the WebBridge example app.

9. Test the integration​

A successful install (first open after install) must be recorded before sessions and events appear correctly in Adtrace. Use the steps below to verify your integration.

Prepare a clean test device​

To trigger a real install for testing:

  1. Use a phone that has never installed your app, or uninstall the app from the device.
  2. Reset the Google Advertising ID (gps_adid): open Settings → Google → Ads → Google Advertising ID (or Reset advertising ID), then reset it.
  3. Install and open the app again.

If you use an emulator, use an AVD image that includes Google Play. Emulators without Google Play cannot provide a valid Google Advertising ID.

You can find your Google Advertising ID (gps_adid) on the device under Settings → Google → Ads.

Test in the Adtrace panel​

If you use the Adtrace panel:

  1. Copy your device Google Advertising ID (gps_adid) from Settings → Google → Ads.
  2. Open the Adtrace panel, select your app, then go to Settings → Testing Console.
  3. Enter the device ID, choose the ID type (gps_adid), and check whether an install is recorded for that device.

If no install appears, review the earlier setup steps and the example apps, then try again on a clean device.

Test with logs (optional)​

  1. Set log level to verbose and environment to ENVIRONMENT_SANDBOX.
  2. Connect the device and filter Logcat with the AdTrace tag.
  3. Uninstall, reset advertising ID if needed, reinstall, and open the app.
  4. In the server response logs, look for an adid value. Receiving adid means the install was recorded successfully.
Logcat response (example)
"adid" : "mhxd6or7d3u57fnbdy2r4urdrdxr7tlr"

10. Build your app for production​

After you finish testing, update your AdTraceConfig before you ship the app:

  1. Adjust your log level so the SDK returns only the logs you need in production.
  2. Set environment to AdTraceConfig.ENVIRONMENT_PRODUCTION.
import io.adtrace.sdk.AdTrace;
import io.adtrace.sdk.AdTraceConfig;
import io.adtrace.sdk.LogLevel;

String appToken = "{YourAppToken}";
String environment = AdTraceConfig.ENVIRONMENT_PRODUCTION;
AdTraceConfig config = new AdTraceConfig(this, appToken, environment);
config.setLogLevel(LogLevel.WARN);
AdTrace.onCreate(config);

Sandbox and production traffic are separated in the Adtrace panel, so you can filter test data from real users.

You are ready to build and run your production app and start attributing users with the Adtrace SDK.

Checklist​

Before you move on, confirm you have completed:

  • Added the Adtrace SDK dependency
  • Added Google Play Services Ads Identifier (Play Store apps)
  • Added the Install Referrer library (Play Store apps)
  • Declared required permissions in AndroidManifest.xml
  • Added Proguard/R8 keep rules (if you use Proguard or R8)
  • Initialized Adtrace in your Application class
  • Configured session tracking (onResume / onPause)
  • Verified a successful install in Testing Console or logs
  • Switched to ENVIRONMENT_PRODUCTION for release

Next steps​

Track user actions next: follow Event Tracking to send custom events from your Android app.