Skip to main content
Version: 3.0.0+

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 21 (Android 5.0 / Lollipop).

Maven​

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

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

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.

Iranian app stores

If you distribute on Myket, also add the optional Myket install referrer plugin. If you distribute on Cafe Bazaar, add the optional Cafe Bazaar install referrer plugin. Apps that target Google Play alone can skip both.

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;
Automatic lifecycle (SDK 3.0.0+)

From Adtrace Android SDK 3.0.0+, lifecycle and session tracking are handled automatically after AdTrace.onCreate(config). You do not need to call AdTrace.onResume() / AdTrace.onPause() or register ActivityLifecycleCallbacks for Adtrace.

If you integrate SDK 2.6.0, switch the docs version to 2.6.0 for the manual session-tracking steps.

7. WebBridge​

Optional. Only for apps that use an Android WebView. Native-only apps can skip to 8. 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.

8. 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"

9. 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
  • Confirmed automatic lifecycle handling (SDK 3.0.0+; no manual 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.