Android SDK integration guide

The Adjust Android SDK enables you to record attribution, events, and more in your Android app. Follow the steps in this guide to set up your app to work with the Adjust SDK.

Before you begin

Here’s what you need to do before updating to SDK v5:

1. SDK v5 supports SDK signature verification natively. If you currently use the SDK signature library, you need to uninstall this first.
2. If your app targets API versions lower than 21 you need to update your app before you can use SDK v5.

1. Set up your environment

To use the Adjust SDK, you need to add it to your project as a dependency. The Adjust SDK is available on Maven.

To add the Adjust SDK to your project:

1. Add the following beta repository to your build.gradle file:

   repositories {
      maven {
         url "https://oss.sonatype.org/content/repositories/snapshots/"
      }
   }

2. Add the Adjust SDK and Android install referrer implementations to your build.gradle file. Optionally add the Adjust web view bridge if you use web views in your app.

   dependencies {
      implementation 'com.adjust.sdk:adjust-android:5.0.0-SNAPSHOT'
      implementation 'com.android.installreferrer:installreferrer:2.2'
      // Add the following if you are using the Adjust SDK inside web views on your app
      implementation 'com.adjust.sdk:adjust-android-webbridge:5.0.0-SNAPSHOT'
   }

2. Add Google Play Services

Apps that target the Google Play Store must use the gps_adid (Google Advertising ID) to identify devices. You need to add the play-services-ads-identifier AAR to your project to access the gps_adid.

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

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

3. Add permissions

To give the Adjust SDK access to device information, you need to declare which permissions your app requires. To do this, add permissions to your AndroidManifest.xml file.

Add the following permissions to get access to online features:

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

If your app doesn’t target the Google Play Store, add the following permission to access the device’s network state:

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

The Adjust SDK includes the com.google.android.gms.AD_ID permission by default. If you need to make your app COPPA (Children’s Online Privacy Protection Act) compliant or if your app doesn’t target the Google Play Store, you must remove this permission using a remove directive.

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

4. Set up Proguard

If you’re using Proguard to optimize your app, you must add rules to prevent Proguard from removing classes.

-keep class com.adjust.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’re not publishing your app in the Google Play Store, add the following rule:

-keep public class com.adjust.sdk.** { *; }

5. Set up install referrer

An install referrer is a unique identifier used to attribute an install to a source. The Adjust SDK requires this information to perform attribution. Use one of the following methods to retrieve the install referrer information:

Google Play Referrer API

The Google Play Referrer API is available to apps that target the Google Play Store.

To support the Google Play Referrer API, add the following to your build.gradle file:

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

If you’re using Proguard, remember to add a rule to prevent the dependency from being removed.

-keep public class com.android.installreferrer.** { *; }

Huawei Referrer API

The Huawei Referrer API is available to apps that target Huawei devices. The Adjust SDK can record installs on Huawei devices using the Adjust Huawei Referrer plugin.

To install this plugin, add the following dependency to your build.gradle file:

dependencies {
   implementation: "com.adjust.sdk:adjust-android-huawei-referrer:5.0.0-SNAPSHOT"
}

Xiaomi referrer plugin

The Xiaomi referrer plugin enables you to record install referrer values for apps that target Xiaomi devices. See the plugin documentation for install information.

Samsung referrer plugin

The Samsung referrer plugin enables you to record install referrer values for apps that target the Samsung Galaxy store. See the plugin documentation for install information.

Meta referrer integration

The Adjust SDK supports the Meta Install Referrer using the Adjust Meta Install Referrer plugin. See the documentation for integration details.

6. Integrate the Adjust SDK

The following information is required to initialize the Adjust SDK:

• appToken: Your Adjust app token.
• environment: The environment your app is running in. Set this to AdjustConfig.ENVIRONMENT_SANDBOX to test your app locally.

The recommended way to initialize the Adjust SDK is inside a global Android Application class. If you haven’t already set this up for your app, 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 to the <application> element and set it to the name of your application class. For example, if your Application class is named GlobalApplication, you would set the following:

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

4. Find the initSdk method in your Application class or add one if it doesn’t exist. Pass the following parameters to initialize the Adjust SDK:

   • Your appToken
   • The environment you want to run the app in
   • The LogLevel you want to record

Integrate the Adjust Web View SDK

If your app uses web views, you need to use the Adjust Web View SDK to record information. You need to obtain the reference to your WebView object. Once you’ve done this, follow these steps:

1. Call webView.getSettings().setJavaScriptEnabled(true) to enable Javascript in the web view.
2. Start the default AdjustBridgeInstance by calling AdjustBridge.registerAndGetInstance(getApplication(), webview). This registers the Adjust bridge as a Javascript interface in the web view.
3. Call AdjustBridge.setWebView() to set a new WebView.
4. Call AdjustBridge.unregister() to unregister the AdjustBridgeInstance and the WebView.
5. Here’s an example of a full setup:

6. Import the Adjust Javascript files in your HTML:

   <script type="text/javascript" src="adjust.js"></script>
   <script type="text/javascript" src="adjust_event.js"></script>
   <script type="text/javascript" src="adjust_third_party_sharing.js"></script>
   <script type="text/javascript" src="adjust_config.js"></script>

7. You can now initialize the Adjust SDK in your web view by passing your appToken and environment to the AdjustConfig class:

   let yourAppToken = "{YourAppToken}";
   let environment = AdjustConfig.EnvironmentSandbox;
   let adjustConfig = new AdjustConfig(yourAppToken, environment);
   adjustConfig.setLogLevel(AdjustConfig.LogLevelVerbose);
   Adjust.initSdk(adjustConfig);

7. Build your app for production

Once you’ve finished your testing, you can build your app for production. To do this, you need to update your config object.

1. Adjust your log level to return only what you need.
2. Set your environment to AdjustConfig.ENVIRONMENT_PRODUCTION.

The Adjust Android SDK enables you to record attribution, events, and more in your Android app. Follow the steps in this guide to set up your app to work with the Adjust SDK.

1. Get the Adjust SDK

To use the Adjust SDK in your Android app, you need to add it to your project. You can download the latest version from the GitHub releases page.

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

dependencies {
   implementation 'com.adjust.sdk:adjust-android:v4.38.5'
   implementation 'com.android.installreferrer:installreferrer:2.2'
   // Add the following if you're using the Adjust SDK inside web views on your app
   implementation 'com.adjust.sdk:adjust-android-webbridge:v4.38.5'
}

2. Add Google Play Services

Apps that target the Google Play Store must use the gps_adid (Google Advertising ID) to identify devices. You need to add the play-services-ads-identifier AAR to your project to access the gps_adid.

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

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

Collect App Set Identifier

The App Set Identifier is a unique identifier that enables you to measure information from any of your apps that a user has installed on their device. All apps by the same developer share the same App Set ID, meaning you can gather meaningful insights from users across all your apps. To record a device’s App Set ID, you need to add the following permission to your build.gradle file:

dependencies {
   implementation 'com.google.android.gms:play-services-appset:16.0.2'
}

If this permission is enabled, the App Set ID is sent to Adjust’s servers as part of the device information payload.

3. Add permissions

To give the Adjust SDK access to device information, you need to declare which permissions your app requires. To do this, add permissions to your AndroidManifest.xml file.

Add the following permissions to get access to online features:

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

If your app doesn’t target the Google Play Store, add the following permission to access the device’s network state:

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

The Adjust SDK includes the com.google.android.gms.AD_ID permission by default. If you need to make your app COPPA (Children’s Online Privacy Protection Act) compliant or if your app doesn’t target the Google Play Store, you must remove this permission using a remove directive.

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

4. Set up Proguard

If you’re using Proguard to optimize your app, you must add rules to prevent Proguard from removing classes.

-keep class com.adjust.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’re not publishing your app in the Google Play Store, add the following rule:

-keep public class com.adjust.sdk.** { *; }

5. Set up install referrer

An install referrer is a unique identifier used to attribute an install to a source. The Adjust SDK requires this information to perform attribution. Use one of the following methods to retrieve the install referrer information:

Google Play Referrer API

The Google Play Referrer API is available to apps that target the Google Play Store.

To support the Google Play Referrer API, add the following to your build.gradle file:

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

If you’re using Proguard, remember to add a rule to prevent the dependency from being removed.

-keep public class com.android.installreferrer.** { *; }

Huawei Referrer API

The Huawei Referrer API is available to apps that target Huawei devices. The Adjust SDK can record installs on Huawei devices using Huawei App Gallery v10.4 and later. You don’t need to make any changes to support this API.

Xiaomi referrer plugin

The Xiaomi referrer plugin enables you to record install referrer values for apps that target Xiaomi devices. See the plugin documentation for install information.

Samsung referrer plugin

The Samsung referrer plugin enables you to record install referrer values for apps that target the Samsung Galaxy store. See the plugin documentation for install information.

Meta referrer integration

The Adjust SDK supports the Meta Install Referrer in v4.36.0 and above. To enable this feature:

1. Find your Meta app ID in your App Dashboard. See Meta’s App Dashboard documentation for more information.
2. Pass your App ID as a String argument to the AdjustConfig.setFbAppId method.

6. Integrate the Adjust SDK

The following information is required to initialize the Adjust SDK:

• appToken: Your Adjust app token.
• environment: The environment your app is running in. Set this to AdjustConfig.ENVIRONMENT_SANDBOX to test your app locally.

The recommended way to initialize the Adjust SDK is inside a global Android Application class. If you haven’t already set this up for your app, 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 to the <application> element and set it to the name of your application class. For example, if your Application class is named GlobalApplication, you would set the following:

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

4. Find the onCreate method in your Application class or add one if it doesn’t exist. Pass the following parameters to initialize the Adjust SDK:

   • Your appToken
   • The environment you want to run the app in
   • The LogLevel you want to record

Integrate the Adjust Web View SDK

If your app uses web views, you need to use the Adjust Web View SDK to record information. You need to obtain the reference to your WebView object. Once you’ve done this, follow these steps:

1. Call webView.getSettings().setJavaScriptEnabled(true) to enable Javascript in the web view.
2. Start the default AdjustBridgeInstance by calling AdjustBridge.registerAndGetInstance(getApplication(), webview). This registers the Adjust bridge as a Javascript interface in the web view.
3. Call AdjustBridge.setWebView() to set a new WebView.
4. Call AdjustBridge.unregister() to unregister the AdjustBridgeInstance and the WebView.
5. Here’s an example of a full setup:

6. Import the Adjust Javascript files in your HTML:

<script type="text/javascript" src="adjust.js"></script>
<script type="text/javascript" src="adjust_event.js"></script>
<script type="text/javascript" src="adjust_third_party_sharing.js"></script>
<script type="text/javascript" src="adjust_config.js"></script>

7. You can now initialize the Adjust SDK in your web view by passing your appToken and environment to the AdjustConfig class:

let yourAppToken = "{YourAppToken}";
let environment = AdjustConfig.EnvironmentSandbox;
let adjustConfig = new AdjustConfig(yourAppToken, environment);
adjustConfig.setLogLevel(AdjustConfig.LogLevelVerbose);
Adjust.onCreate(adjustConfig);

7. Configure session recording

To record session information, you need to call methods at different stages of your app’s activity lifecycle. These stages are different depending on the API level your app targets.

API level 14 and above

To set up session recording for API level 14 and above:

1. If you have Adjust.onResume and Adjust.onPause calls in your activities, remove them.
2. Add a private class that implements the ActivityLifecycleCallbacks interface.
3. Edit the onActivityResumed(Activity activity) method and add a call to Adjust.onResume().
4. Edit the onActivityPaused(Activity activity) method and add a call to Adjust.onPause().
5. Add the onCreate() method to your Adjust SDK configuration step.
6. Call registerActivityLifecycleCallbacks with an instance of the created ActivityLifecycleCallbacks class:

API level 9 to 13

To set up session recording in apps targeting API level 13 and below, follow these steps:

1. Add a call to Adjust.onResume() in your activity’s onResume method.
2. Add a call to Adjust.onPause() in your activity’s onPause method.
3. Repeat these steps for each activity in your app. Depending on your coding style, you might want to add this in a common superclass of all your activities.

8. Build your app for production

Once you’ve finished your testing, you can build your app for production. To do this, you need to update your config object.

1. Adjust your log level to return only what you need.
2. Set your environment to AdjustConfig.ENVIRONMENT_PRODUCTION.