Integrate SDK

Learn how to initialize and start the Android SDK.

Before you begin

  • You must install the Android SDK.
  • Ensure that in your app build.gradle file, applicationId's value (in the defaultConfig block) matches the app's app ID in AppsFlyer.
  • Get the AppsFlyer dev key. It is required to successfully initialize the SDK.
  • The codes in this document are example implementations. Make sure to change the <AF_DEV_KEY> and other placeholders as needed.
  • All the steps in this document are mandatory unless stated otherwise.

Initializing the Android SDK

It's recommended to initialize the SDK in the global Application class/subclass. That is to ensure the SDK can start in any scenario (for example, deep linking).

Step 1: Import AppsFlyerLib
In your global Application class, import AppsFlyerLib:

import com.appsflyer.AppsFlyerLib;
import com.appsflyer.AppsFlyerLib

Step 2: Initialize the SDK
In the global Application onCreate, call init with the following arguments:

AppsFlyerLib.getInstance().init(<AF_DEV_KEY>, null, this);
AppsFlyerLib.getInstance().init(<AF_DEV_KEY>, null, this)
  1. The first argument is your AppsFlyer dev key.
  2. The second argument is a Nullable AppsFlyerConversionListener. If you don't need conversion data, we recommend passing a null as the second argument. For more information, see Conversion data.
  3. The third argument is the Application Context.

Starting the Android SDK

In the Application's onCreate method, after calling init, call start and pass it the Application's Context as the first argument:

AppsFlyerLib.getInstance().start(this);
AppsFlyerLib.getInstance().start(this)

Deferring SDK start

Optional
You can defer the SDK initialization by calling start from an Activity class, instead of calling it in the Application class. init should still be called in the Application class.

Typical usage of deferred SDK start is when an app would like to request consent from the user to collect data in the Main Activity, and call start after getting the user's consent.

⚠️

Important notice

If the app calls start from an Activity, it should pass the Activity Context to the SDK.
Failing to pass the activity context will not trigger the SDK, thus losing attribution data and in-app events.

Starting with a response listener

To receive confirmation that the SDK was started successfully, create an AppsFlyerRequestListener object and pass it as the third argument of start:

AppsFlyerLib.getInstance().start(getApplicationContext(), <AF_DEV_KEY>, new AppsFlyerRequestListener() {
  @Override
  public void onSuccess() {
    Log.d(LOG_TAG, "Launch sent successfully, got 200 response code from server");
  }
  
  @Override
  public void onError(int i, @NonNull String s) {
    Log.d(LOG_TAG, "Launch failed to be sent:\n" +
          "Error code: " + i + "\n"
          + "Error description: " + s);
  }
});
AppsFlyerLib.getInstance().start(this, <AF_DEV_KEY>, object : AppsFlyerRequestListener {
  override fun onSuccess() {
    Log.d(LOG_TAG, "Launch sent successfully")
    }
  
  override fun onError(errorCode: Int, errorDesc: String) {
    Log.d(LOG_TAG, "Launch failed to be sent:\n" +
          "Error code: " + errorCode + "\n"
          + "Error description: " + errorDesc)
    }
})
  • The onSuccess() callback method is invoked for every 200 response to an attribution request made by the SDK.
  • The onError(String error) callback method is invoked for any other response and returns the response as the error string.

Full example

The following example demonstrates how to initialize and start the SDK from the Application class.

import android.app.Application;
import com.appsflyer.AppsFlyerLib;
// ...
public class AFApplication extends Application {
    // ...
    @Override
    public void onCreate() {
        super.onCreate();
        // ...
        AppsFlyerLib.getInstance().init(<AF_DEV_KEY>, null, this);
        AppsFlyerLib.getInstance().start(this);
        // ...
    }
    // ...
}
import android.app.Application
import com.appsflyer.AppsFlyerLib
// ...
class AFApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // ...
        AppsFlyerLib.getInstance().init(<AF_DEV_KEY>, null, this)
        AppsFlyerLib.getInstance().start(this)
        // ...
    }
    // ...
}

Github link

Setting the Customer User ID

Optional
The Customer User ID (CUID) is a unique user identifier created outside the SDK by the app owner. If made available to the SDK, it can be associated with installs and other in-app events. These CUID-tagged events can be cross-referenced with user data from other devices and applications.

There are two ways to set the CUID, depending on whether or not the SDK is started from the Application class or the Activity class (see Starting the Android SDK).

Set the CUID in the Application class

If you started the SDK from the Application class (see Starting the Android SDK), pause the SDK to prevent the install data from being sent to AppsFlyer before the CUID is provided.

To achieve the delay, set waitForCustomerUserId to true after init and before start.

AppsFlyerLib.getInstance().init(AF_DEV_KEY, getConversionListener(), getApplicationContext());
AppsFlyerLib.getInstance().waitForCustomerUserId(true);
AppsFlyerLib.getInstance().start(this);

After calling start, you can add your custom code that makes the CUID available.
Once the CUID is available, the final step includes setting the CUID, releasing the SDK from the waiting mode, and sending the attribution data with the customer ID to AppsFlyer. This step is performed using the call to setCustomerIdAndLogSession.

AppsFlyerLib.getInstance().setCustomerIdAndLogSession(<CUSTOMER_ID>, this);

Other than setCustomerIdAndLogSession, do not use setCustomerUserId or any other AppsFlyer SDK functionality, as the waiting SDK will ignore it.

Example code

public class AFApplication extends Application {
  private static final String AF_DEV_KEY = <AF_DEV_KEY>;
  @Override
  public void onCreate() {
    super.onCreate();
    AppsFlyerConversionListener conversionDataListener = 
    new AppsFlyerConversionListener() {
      ...
    };
    AppsFlyerLib.getInstance().init(AF_DEV_KEY, getConversionListener(), getApplicationContext());
    AppsFlyerLib.getInstance().waitForCustomerUserId(true);
    AppsFlyerLib.getInstance().start(this);
    // Do your magic to get the customerUserID
    // any AppsFlyer SDK code invoked here will be discarded
    // ...
    // Once the customerUserID is available, call setCustomerIdAndLogSession(). 
    // setCustomerIdAndLogSession() sets the CUID, releases the waiting mode,
    // and sends the attribution data with the customer ID to AppsFlyer.
    AppsFlyerLib.getInstance().setCustomerIdAndLogSession(<CUSTOMER_ID>, this);
  }
}

📘

Note

If you wish to remove the waiting mode from the SDK initialization fow, it is not enough to delete the call to waitForCustomerUserId(true). It is also required to replace it with waitForCustomerUserID(false). Simply removing the call is insufficient because the 'waitForCustomerUserId' boolean flag is stored in the Android Shared Preferences.

Set the CUID in an Activity class

If you started the SDK from an Activity class (see Deferring SDK start), we recommend setting the CUID after init and before start. This ensures that the install event can be recorded with the CUID.

Use the setCustomerUserId function to set the CUID.

public void setCustomerUserId(String id);

Usage example:

// Do your magic to get the customerUserID
...
AppsFlyerLib.getInstance().init(AF_DEV_KEY, conversionListener, this);  
AppsFlyerLib.getInstance().setCustomerUserId(<MY_CUID>);
...
//Now you can call start    
AppsFlyerLib.getInstance().start(this , AF_DEV_KEY );

Enabling debug mode

Optional
You can enable debug logs by calling setDebugLog:

AppsFlyerLib.getInstance().setDebugLog(true);
AppsFlyerLib.getInstance().setDebugLog(true)

📘

Note

To see full debug logs, make sure to call setDebugLog before invoking other SDK methods.

See example.

🚧

Warning

To avoid leaking sensitive information, make sure debug logs are disabled before distributing the app.

Testing the integration

Optional
For detailed integration testing instructions, see the Android SDK integration testing guide.