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.

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

   1
   dependencies {
   2
      implementation 'com.adjust.sdk:adjust-android:5.0.2'
   3
      implementation 'com.android.installreferrer:installreferrer:2.2'
   4
      // Add the following if you are using the Adjust SDK inside web views on your app
   5
      implementation 'com.adjust.sdk:adjust-android-webbridge:5.0.2'
   6
   }

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:

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

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:

1
<uses-permission android:name="android.permission.INTERNET"/>
2
<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:

1
<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.

1
<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.

1
-keep class com.adjust.sdk.** { *; }
2
-keep class com.google.android.gms.common.ConnectionResult {
3
   int SUCCESS;
4
}
5
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
6
   com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
7
}
8
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
9
   java.lang.String getId();
10
   boolean isLimitAdTrackingEnabled();
11
}
12
-keep public class com.android.installreferrer.** { *; }

If you're not publishing your app in the Google Play Store, add the following rule:

1
-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:

1
dependencies {
2
   implementation 'com.android.installreferrer:installreferrer:2.2'
3
}

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

1
-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:

1
dependencies {
2
   implementation: "com.adjust.sdk:adjust-android-huawei-referrer:5.0.0"
3
}

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. Set up SDK Signature

If you want to use the SDK signature library to secure communications between the Adjust SDK and Adjust's servers, follow the instructions in the SDK signature guide on the Adjust Help Center.

7. 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:

   1
   <application android:name=".GlobalApplication">
   2
      <!-- ... -->
   3
   </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

1
import com.adjust.sdk.Adjust;
2
import com.adjust.sdk.AdjustConfig;
3

4
class GlobalApplication : Application () {
5
   override fun onCreate() {
6
      super.onCreate()
7

8
      val appToken = "{YourAppToken}"
9
      val environment = AdjustConfig.ENVIRONMENT_SANDBOX;
10
      val config = AdjustConfig(this, appToken, environment)
11
      config.setLogLevel(LogLevel.VERBOSE)
12
      Adjust.initSdk(config)
13
   }
14
}

1
import com.adjust.sdk.Adjust;
2
import com.adjust.sdk.AdjustConfig;
3

4
public class GlobalApplication extends Application {
5
   @Override
6
   public void onCreate() {
7
      super.onCreate();
8

9
      String appToken = "{YourAppToken}";
10
      String environment = AdjustConfig.ENVIRONMENT_SANDBOX;
11
      AdjustConfig config = new AdjustConfig(this, appToken, environment);
12
      config.setLogLevel(LogLevel.VERBOSE)
13
      Adjust.initSdk(config);
14
   }
15
}

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:

   • Kotlin
   • Java

   1
   class MainActivity : Activity() {
   2
      override fun onCreate(savedInstanceState: Bundle?) {
   3
            super.onCreate(savedInstanceState)
   4
            setContentView(R.layout.activity_main)
   5
   
   6
            val webView = findViewById<WebView>(R.id.webView)
   7
            webView.settings.javaScriptEnabled = true
   8
            webView.webChromeClient = WebChromeClient()
   9
            webView.webViewClient = WebViewClient()
   10
   
   11
            AdjustBridge.registerAndGetInstance(application, webView)
   12
            try {
   13
               webView.loadUrl("file:///android_asset/AdjustExample-WebView.html")
   14
            } catch (e: Exception) {
   15
               e.printStackTrace()
   16
            }
   17
      }
   18
   
   19
      override fun onDestroy() {
   20
         AdjustBridge.unregister()
   21
   
   22
         super.onDestroy()
   23
      }
   24
   }

   1
   public class MainActivity extends Activity {
   2
      @Override
   3
      protected void onCreate(Bundle savedInstanceState) {
   4
         super.onCreate(savedInstanceState);
   5
         setContentView(R.layout.activity_main);
   6
   
   7
         WebView webView = (WebView) findViewById(R.id.webView);
   8
         webView.getSettings().setJavaScriptEnabled(true);
   9
         webView.setWebChromeClient(new WebChromeClient());
   10
         webView.setWebViewClient(new WebViewClient());
   11
   
   12
         AdjustBridge.registerAndGetInstance(getApplication(), webview);
   13
         try {
   14
               webView.loadUrl("file:///android_asset/AdjustExample-WebView.html");
   15
         } catch (Exception e) {
   16
               e.printStackTrace();
   17
         }
   18
      }
   19
   
   20
      @Override
   21
      protected void onDestroy() {
   22
         AdjustBridge.unregister();
   23
   
   24
         super.onDestroy();
   25
      }
   26
   }

6. Import the Adjust Javascript files in your HTML:

   1
   <script type="text/javascript" src="adjust.js"></script>
   2
   <script type="text/javascript" src="adjust_event.js"></script>
   3
   <script type="text/javascript" src="adjust_third_party_sharing.js"></script>
   4
   <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:

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

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.

1
val appToken = "{YourAppToken}"
2
val environment = AdjustConfig.ENVIRONMENT_PRODUCTION;
3
val config = AdjustConfig(this, appToken, environment)
4
config.setLogLevel(LogLevel.WARN)
5
Adjust.initSdk(config)

1
String appToken = "{YourAppToken}";
2
String environment = AdjustConfig.ENVIRONMENT_PRODUCTION;
3
AdjustConfig config = new AdjustConfig(this, appToken, environment);
4
config.setLogLevel(LogLevel.WARN)
5
Adjust.initSdk(config);