Get started with the Android SDK

Tip:

We're releasing a new version of our Android SDK. Want to get early access and try out the new features?
You can find:

Improved support for customers with super apps or separate BI systems
Added flexibility for retrieving adid information, higher limits on event deduplication, and improved caching and replaying of information from the SDK
Refined information on attribution callbacks, simplified debugging, and more intuitive method names

Click here to complete the application and sign up now! 🚀

The Adjust Android SDK enables you to track attribution, events, and much more in your Android app. Follow the steps in this guide to set up your app to work with the Adjust SDK. You can also check out our example apps on GitHub.

Step one: set up your environment

To start using the Adjust SDK, you will need to add it to your project as a dependency.

Important:

The minimum supported Android API level for the Adjust SDK integration is 9 (Gingerbread). The minimum supported Android API level for the web view extension is 17 (Jelly Bean).

Maven

Add the following to your build.gradle file:

dependencies {
   implementation 'com.adjust.sdk:adjust-android:4.33.5'
   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:4.33.5'
}

Add as an archive

Step two: add Google Play Services

Apps in the Google Play Store need to use the Google Advertising ID to identify devices. To enable the Google Advertising ID for our SDK, you need to integrate Google Play Services. To do this, add the Google Play Services library to your project. Add the following dependency to the dependencies section of your build.gradle file.

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

Note:

The Adjust SDK is not tied to any version of the play-services-analytics dependency. You can use the any version of the Google Play Services library.

Collect App Set Identifier

Note:

The App Set ID is available in Adjust SDK v4.33.5 and above.

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'
}

Step three: add permissions

Note:

If your app targets children, you should remove the AD_ID permission to prevent the Adjust SDK from reading it. See Set up apps for children for instructions.

The Adjust 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"/>

Step four: set up Proguard

If you are using Proguard in your application, add the following lines to your Proguard file:

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

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

Step five: set up install referrer

The install referrer is a unique identifier which you can use to attribute an app install to a source. The Adjust SDK requires this information to perform attribution. There are 4 methods you can use to gather this information:

Use the Google Play Referrer API.
Listen for the INSTALL_REFERRER intent with a broadcast receiver.
Use the Huawei Referrer API (only for Huawei devices).
Use the Facebook referrer integration.
Use a plugin to access device-specific values.

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.

Google Play Referrer API

Note:

This feature is supported in Adjust SDK v4.12.0 and later.

To support the Google Play Referrer API, make sure you have the following in your build.gradle file:

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

If you are using Proguard, make sure you have added the following setting in your Proguard file:

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

INSTALL_REFERRER intent

If you are working with a store that supports the INSTALL_REFERRER intent, you can capture this with a broadcast receiver. Add the following receiver inside the application tag in your AndroidManifest.xml:

<receiver
    android:name="com.adjust.sdk.AdjustReferrerReceiver"
    android:permission="android.permission.INSTALL_PACKAGES"
    android:exported="true" >
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

This receiver will retrieve the install referrer and pass it to the Adjust backend.

If you are using a different broadcast receiver, you will need to set it up to communicate with Adjust. Follow these instructions to enable communication with the Adjust broadcast receiver.

Huawei Referrer API

Meta referrer integration

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

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

Java

adjustConfig.setFbAppId(<FB_APP_ID_STRING>);

Samsung referrer plugin

Xiaomi referrer plugin

Step six: integrate the SDK into your app

If you are integrating the Adjust SDK into a standard app, follow the Standard SDK setup steps. If you are integrating the SDK for web views, follow the Web Views SDK setup steps.

Standard SDK

We recommend using a global Android Application class to initialize the Adjust SDK. If you do not have this set up, follow these steps:

Create a class that extends the Application.
Open the AndroidManifest.xml file and locate the <application> element.
Add the android:name attribute and set it to the name of your application class. For example, if your Application class is named GlobalApplication:

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

In your Application class, find or add the onCreate method. Add the following code to initialize the Adjust SDK:

import com.adjust.sdk.Adjust;
import com.adjust.sdk.AdjustConfig;

public class GlobalApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        String appToken = "{YourAppToken}";
        String environment = AdjustConfig.ENVIRONMENT_SANDBOX;
        AdjustConfig config = new AdjustConfig(this, appToken, environment);
        Adjust.onCreate(config);
    }
}

Tip:

You can find your app token in your Adjust dashboard.

Set the environment variable to either sandbox or production mode.

Important:

When running tests you should ensure that your environment is set to AdjustConfig.ENVIRONMENT_SANDBOX. Change this to AdjustConfig.ENVIRONMENT_PRODUCTION before you submit your application to the App Store.

String environment = AdjustConfig.ENVIRONMENT_SANDBOX;
String environment = AdjustConfig.ENVIRONMENT_PRODUCTION;

Web View SDK

Before you start, you will need to obtain the reference to your WebView object. Once you have done this:

Call webView.getSettings().setJavaScriptEnabled(true) to enable Javascript in the web view.
Start the default instance of AdjustBridgeInstance by calling AdjustBridge.registerAndGetInstance(getApplication(), webview). This will register the Adjust bridge as a Javascript interface in the web view.
Call AdjustBridge.setWebView() to set a new WebView if needed.
Call AdjustBridge.unregister() to unregister the AdjustBridgeInstance and WebView.

Once you have completed these steps, your activity should look like this:

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());

        AdjustBridge.registerAndGetInstance(getApplication(), webview);
        try {
            webView.loadUrl("file:///android_asset/AdjustExample-WebView.html");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
    
    @Override
    protected void onDestroy() {
        AdjustBridge.unregister();

        super.onDestroy();
    }
}

Congratulations! You have added the Adjust bridge to your app. The Javascript bridge will be able to communicate between your page and the Adjust SDK.

In your HTML file, import the Adjust Javascript files from the SDK:

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

Add your references to the Javascript files. Use these in your HTML file to initialize the Adjust SDK:

let yourAppToken = '{YourAppToken}';
let environment = AdjustConfig.EnvironmentSandbox;
let adjustConfig = new AdjustConfig(yourAppToken, environment);

Adjust.onCreate(adjustConfig);

Tip:

You can find your app token in your Adjust dashboard.

Important:

When running tests you should ensure that your environment is set to AdjustConfig.EnvironmentSandbox. Change this to AdjustConfig.EnvironmentProduction before you submit your application to the App Store.

let environment = AdjustConfig.EnvironmentSandbox;
let environment = AdjustConfig.EnvironmentProduction;

Step seven: set up session tracking

You need to set up session tracking so that the SDK can pass session information to the Adjust backend. Follow the instructions below to set this up in your app.

API level 14 and higher

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 update each activity by following the instructions below. If you have Adjust.onResume and Adjust.onPause calls on your app's activities, remove them.
Edit the onActivityResumed(Activity activity) method and add a call to Adjust.onResume(). Edit the onActivityPaused(Activity activity) method and add a call to Adjust.onPause().
Add the onCreate() method to your Adjust SDK configuration step. Call registerActivityLifecycleCallbacks with an instance of the created ActivityLifecycleCallbacks class:

import com.adjust.sdk.Adjust;
import com.adjust.sdk.AdjustConfig;

public class GlobalApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        String appToken = "{YourAppToken}";
        String environment = AdjustConfig.ENVIRONMENT_SANDBOX;
        AdjustConfig config = new AdjustConfig(this, appToken, environment);
        Adjust.onCreate(config);

        registerActivityLifecycleCallbacks(new AdjustLifecycleCallbacks());
    }

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

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

         //...
     }
  }

API level 9 to 13

If the minSdkVersion in your gradle file is between 9 and 13, consider changing it to 14 or above. This will simplify the integration process. Check the Android dashboard for information about the market share of major versions.

You need to call certain methods when pausing or resuming an Activity. This is so that the Adjust SDK does not miss the start or end of a session. To do this, follow these steps for each Activity in your app:

In your Activity's onResume method, call Adjust.onResume(). Create the method if needed.
In your Activity's onPause method, call Adjust.onPause(). Create the method if needed.

After these steps, your activity should look like this:

import com.adjust.sdk.Adjust;

public class YourActivity extends Activity {
    protected void onResume() {
        super.onResume();
        Adjust.onResume();
    }
    protected void onPause() {
        super.onPause();
        Adjust.onPause();
    }
}

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.

Step eight: set up logging

To set the verbosity of logging, call the setLogLevel method on your config instance.

Java

Javascript

adjustConfig.setLogLevel(LogLevel.WARN);

If you want to disable all logging, set the log level to suppress:

Java

Javascript

AdjustConfig config = new AdjustConfig(this, appToken, environment, true);
config.setLogLevel(LogLevel.SUPRESS);
Adjust.onCreate(config);

Step nine: 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 Adjust SDK.