SDK v5 migration guide

Before you begin

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

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

Install the SDK

To start using SDK v5, you need to add it as a dependency in your project. To do this:

Remove any older versions of the SDK you currently have in your build.gradle file.

Add the following dependencies to your build.gradle file:

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

Update the initialization method

Changed in v5

In SDK v4, the initialization method is Adjust.onCreate(AdjustConfig). This has been changed to Adjust.initSdk(AdjustConfig) in SDK v5.

Kotlin
Java

Adjust.onCreate(adjustConfig) // v4
Adjust.initSdk(adjustConfig) // v5

Adjust.onCreate(adjustConfig); // v4
Adjust.initSdk(adjustConfig); // v5

Configure the SDK Signature library

SDK v5 includes the SDK signature library. You can test this by following the testing steps in the Signature library integration guide.

Signature protection is inactive by default. To enable it, you need to:

Enforce signature validation.
Provide your app’s SHA-1 fingerprints prior to testing.

Once you’ve installed the v5 SDK, you need to update your existing Adjust code to use the new APIs.

New APIs

Added in v5

The following APIs have been added in SDK v5.

Install referrer getters

SDK v5 contains new getter methods for fetching install referrer information.

Kotlin
Java

Adjust.getGooglePlayInstallReferrer(
   applicationContext,
   object : OnGooglePlayInstallReferrerReadListener {
         override fun onInstallReferrerRead(referrerDetails: GooglePlayInstallReferrerDetails) {}
         override fun onFailure(message: String) {}
   })

AdjustHuaweiReferrer.getHuaweiAdsInstallReferrer(
   applicationContext,
   object : OnHuaweiInstallReferrerReadListener() {
         fun onInstallReferrerDetailsRead(referrerDetails: HuaweiInstallReferrerDetails?) {}
         fun onFail(message: String?) {}
   })


AdjustHuaweiReferrer.getHuaweiAppGalleryInstallReferrer(
   applicationContext,
   object : OnHuaweiInstallReferrerReadListener() {
         fun onInstallReferrerDetailsRead(referrerDetails: HuaweiInstallReferrerDetails?) {}
         fun onFail(message: String?) {}
   })

AdjustSamsungReferrer.getSamsungInstallReferrer(
   applicationContext,
   object : OnSamsungInstallReferrerReadListener() {
         fun onSamsungInstallReferrerRead(referrerDetails: SamsungInstallReferrerDetails?) {}
         fun onFail(message: String?) {}
   })

AdjustVivoReferrer.getVivoInstallReferrer(
   applicationContext,
   object : OnVivoInstallReferrerReadListener() {
         fun onVivoInstallReferrerRead(referrerDetails: VivoInstallReferrerDetails?) {}
         fun onFail(message: String?) {}
   })

AdjustXiaomiReferrer.getXiaomiInstallReferrer(
   applicationContext,
   object : OnXiaomiInstallReferrerReadListener() {
         fun onXiaomiInstallReferrerRead(referrerDetails: XiaomiInstallReferrerDetails?) {}
         fun onFail(message: String?) {}
   })

Adjust.getGooglePlayInstallReferrer(getApplicationContext(), new OnGooglePlayInstallReferrerReadListener() {
    @Override
    public void onInstallReferrerRead(GooglePlayInstallReferrerDetails referrerDetails) {
    }

    @Override
    public void onFailure(String message) {
    }
});

AdjustHuaweiReferrer.getHuaweiAdsInstallReferrer(getApplicationContext(), new OnHuaweiInstallReferrerReadListener() {
   @Override
   public void onInstallReferrerDetailsRead(HuaweiInstallReferrerDetails referrerDetails) {
   }


   @Override
   public void onFail(String message) {
   }
});

AdjustHuaweiReferrer.getHuaweiAppGalleryInstallReferrer(getApplicationContext(), new OnHuaweiInstallReferrerReadListener() {
   @Override
   public void onInstallReferrerDetailsRead(HuaweiInstallReferrerDetails referrerDetails) {
   }


   @Override
   public void onFail(String message) {
   }
});

AdjustSamsungReferrer.getSamsungInstallReferrer(getApplicationContext(), new OnSamsungInstallReferrerReadListener() {
   @Override
   public void onSamsungInstallReferrerRead(SamsungInstallReferrerDetails referrerDetails) {
   }


   @Override
   public void onFail(String message) {
   }
});

AdjustVivoReferrer.getVivoInstallReferrer(getApplicationContext(), new OnVivoInstallReferrerReadListener() {
   @Override
   public void onVivoInstallReferrerRead(VivoInstallReferrerDetails referrerDetails) {
   }


   @Override
   public void onFail(String message) {
   }
});

AdjustXiaomiReferrer.getXiaomiInstallReferrer(getApplicationContext(), new OnXiaomiInstallReferrerReadListener() {
   @Override
   public void onXiaomiInstallReferrerRead(XiaomiInstallReferrerDetails referrerDetails) {
   }


   @Override
   public void onFail(String message) {
   }
});

Changed APIs

Changed in v5

The following APIs have changed in SDK v5.

Disable and enable the SDK

In SDK v4, you can enable and disable the SDK by calling Adjust.setEnabled() with a boolean value.

Call Adjust.setEnabled(false) to disable the SDK.
Call Adjust.setEnabled(true) to enable the SDK

Kotlin
Java

Adjust.setEnabled(false) // disable SDK
Adjust.setEnabled(true) // enable SDK

Adjust.setEnabled(false); // disable SDK
Adjust.setEnabled(true); // enable SDK

In SDK v5, this feature is split into separate commands for clarity.

Call Adjust.disable() to disable the SDK.
Call Adjust.enable() to enable the SDK.

Kotlin
Java

Adjust.disable() // disable SDK
Adjust.enable() // enable SDK

Adjust.disable(); // disable SDK
Adjust.enable(); // enable SDK

Offline mode

In SDK v4, you can enable and disable offline mode in the SDK by calling Adjust.setOfflineMode() with a boolean value.

Kotlin
Java

Adjust.setOfflineMode(false) // put SDK in offline mode
Adjust.setOfflineMode(true) // put SDK back in online mode

Adjust.setOfflineMode(false); // put SDK in offline mode
Adjust.setOfflineMode(true); // put SDK back in online mode

In SDK v5, this feature is split into separate commands for clarity.

Call Adjust.switchToOfflineMode() to set the SDK to offline mode.
Call Adjust.switchBackToOnlineMode() to set the SDK back to online mode.

Kotlin
Java

Adjust.switchToOfflineMode() // put SDK in offline mode
Adjust.switchBackToOnlineMode() // put SDK back in online mode

Adjust.switchToOfflineMode(); // put SDK in offline mode
Adjust.switchBackToOnlineMode(); // put SDK back in online mode

Preinstall recording

In SDK v4, you can enable the SDK to record activity from apps that came preinstalled on a user’s device by calling the setPreinstallTrackingEnabled method of your AdjustConfig instance with a boolean argument.

Kotlin
Java

adjustConfig.setPreinstallTrackingEnabled(true)

adjustConfig.setPreinstallTrackingEnabled(true);

In SDK v5, this method has been renamed to enablePreinstallTracking for clarity. This method takes no arguments.

Kotlin
Java

adjustConfig.enablePreinstallTracking()

adjustConfig.enablePreinstallTracking();

Send session information

In SDK v4, you need to register activity lifecycle callbacks by implementing ActivityLifecycleCallbacks and calling Adjust.onResume() and Adjust.onPause() on Activity resume and pause respectively.

In SDK v5, the ActivityLifecycleCallbacks functionality is handled by the SDK. You should remove all custom activity lifecycle callbacks from your code.

Session callback parameters

Session callback parameters has been renamed to Global callback parameters in SDK v5.

Kotlin
Java

Adjust.addSessionCallbackParameter("foo", "bar")
Adjust.removeSessionCallbackParameter("foo")
Adjust.resetSessionCallbackParameters()

Adjust.addGlobalCallbackParameter("foo", "bar")
Adjust.removeGlobalCallbackParameter("foo")
Adjust.removeGlobalCallbackParameters()

Adjust.addSessionCallbackParameter("foo", "bar");
Adjust.removeSessionCallbackParameter("foo");
Adjust.resetSessionCallbackParameters();

Adjust.addGlobalCallbackParameter("foo", "bar");
Adjust.removeGlobalCallbackParameter("foo");
Adjust.removeGlobalCallbackParameters();

Session partner parameters

Session partner parameters has been renamed to Global partner parameters in SDK v5.

Kotlin
Java

Adjust.addSessionPartnerParameter("foo", "bar")
Adjust.removeSessionPartnerParameter("foo")
Adjust.resetSessionPartnerParameters()

Adjust.addGlobalPartnerParameter("foo", "bar")
Adjust.removeGlobalPartnerParameter("foo")
Adjust.removeGlobalPartnerParameters()

Adjust.addSessionPartnerParameter("foo", "bar");
Adjust.removeSessionPartnerParameter("foo");
Adjust.resetSessionPartnerParameters();

Adjust.addGlobalPartnerParameter("foo", "bar");
Adjust.removeGlobalPartnerParameter("foo");
Adjust.removeGlobalPartnerParameters();

Event deduplication

In SDK v4, event deduplication is coupled with the event order ID and is limited to a maximum of 10 unique IDs.

Kotlin
Java

val event = AdjustEvent("event_token")
event.setOrderId("deduplication_id")
Adjust.trackEvent(event)

AdjustEvent event = new AdjustEvent("event_token");
event.setOrderId("deduplication_id");
Adjust.trackEvent(event);

In SDK v5, the feature is decoupled from order ID. A new ID field called deduplicationId has been added for event deduplication. Users can set a custom limit on the number of deduplicationId that can be added to the list for identifying duplicate events. By default, the limit is set to 10.

Kotlin
Java

val adjustConfig = AdjustConfig(this, appToken, environment)

adjustConfig.setEventDeduplicationIdsMaxSize(20) // if not set, then 10
Adjust.initSdk(adjustConfig)

val event = AdjustEvent("event_token")
event.setDeduplicationId("deduplication_id")
Adjust.trackEvent(event)

AdjustConfig adjustConfig = new AdjustConfig(this, appToken, environment);

adjustConfig.setEventDeduplicationIdsMaxSize(20); // if not set, then 10
Adjust.initSdk(adjustConfig);

AdjustEvent event = new AdjustEvent("event_token");
event.setDeduplicationId("deduplication_id");
Adjust.trackEvent(event);

AdjustAttribution class

In SDK v4, the AdjustAttribution calls has a property called adid. In SDK v5, the adid property has been removed from the AdjustAttribution class. You can retrieve the device’s ADID using the getAdid() getter method.

Reattribution using deep links

The method used for passing deep link data to the Adjust SDK has been renamed.

v4: Adjust.appWillOpenUrl().
v5: Adjust.processDeeplink().

Kotlin
Java

Adjust.appWillOpenUrl(url, applicationContext) //v4
Adjust.processDeeplink(adjustDeepLink, applicationContext) //v5

Adjust.appWillOpenUrl(url, getApplicationContext()); //v4
Adjust.processDeeplink(adjustDeepLink, getApplicationContext()); //v5

Deferred deep linking callback

In SDK v4, you can call the setOnDeeplinkResponseListener method to handle deferred deep link callbacks.

Kotlin
Java

adjustConfig.setOnDeeplinkResponseListener { deeplink ->
   Log.d("example", "Deferred deep link callback called!")
   true
}

adjustConfig.setOnDeeplinkResponseListener(new OnDeeplinkResponseListener() {
            @Override
            public boolean launchReceivedDeeplink(Uri deeplink) {
                Log.d("example", "Deferred deep link callback called!");
                return true;
            }
        });

In SDK v5, this method is has been renamed to setOnDeferredDeeplinkResponseListener for clarity. All arguments are the same.

Kotlin
Java

adjustConfig.setOnDeferredDeeplinkResponseListener {uri ->
            Log.d("example", "Deferred deep link callback called!")
            true
        }

adjustConfig.setOnDeferredDeeplinkResponseListener(new OnDeferredDeeplinkResponseListener() {
            @Override
            public boolean launchReceivedDeeplink(Uri deeplink) {
                Log.d("example", "Deferred deep link callback called!");
                return true;
            }
        });

COPPA compliance

In SDK v4, you can mark your app as COPPA compliant by calling the setCoppaCompliantEnabled method on your AdjustConfig instance with a boolean value.

Kotlin
Java

adjustConfig.setCoppaCompliantEnabled(true)

adjustConfig.setCoppaCompliantEnabled(true);

In SDK v5, this method has been renamed to enableCoppaCompliance for clarity. This method takes no arguments.

Kotlin
Java

adjustConfig.enableCoppaCompliance()

adjustConfig.enableCoppaCompliance();

Play Store Kids Apps

In SDK v4, you can mark an app as a Play Store Kids app by calling the setPlayStoreKidsAppEnabled method on your AdjustConfig instance with a boolean argument.

Kotlin
Java

adjustConfig.setPlayStoreKidsAppEnabled(true)

adjustConfig.setPlayStoreKidsAppEnabled(true);

In SDK v5, this method has been renamed to enablePlayStoreKidsCompliance for clarity. This method takes no arguments.

Kotlin
Java

adjustConfig.enablePlayStoreKidsCompliance()

adjustConfig.enablePlayStoreKidsCompliance();

Send ad revenue from a specific source

In SDK v4, ad revenue sources are defined as constants in the AdjustConfig class. In SDK v5, ad revenue sources need to be passed as a string.

Kotlin
Java

val adjustAdRevenue = AdjustAdRevenue(AdjustConfig.AD_REVENUE_APPLOVIN_MAX) // v4
val adjustAdRevenue = AdjustAdRevenue("applovin_max_sdk") // v5

AdjustAdRevenue adjustAdRevenue = new AdjustAdRevenue(AdjustConfig.AD_REVENUE_APPLOVIN_MAX); // v4
AdjustAdRevenue adjustAdRevenue = new AdjustAdRevenue("applovin_max_sdk"); // v5

v4	v5
`AdjustConfig.AD_REVENUE_APPLOVIN_MAX`	`"applovin_max_sdk"`
`AdjustConfig.AD_REVENUE_ADMOB`	`"admob_sdk"`
`AdjustConfig.AD_REVENUE_IRONSOURCE`	`"ironsource_sdk"`
`AdjustConfig.AD_REVENUE_ADMOST`	`"admost_sdk"`
`AdjustConfig.AD_REVENUE_UNITY`	`"unity_sdk"`
`AdjustConfig.AD_REVENUE_HELIUM_CHARTBOOST`	`"helium_chartboost_sdk"`
`AdjustConfig.AD_REVENUE_ADX`	`"adx_sdk"`
`AdjustConfig.AD_REVENUE_SOURCE_PUBLISHER`	`"publisher_sdk"`
`AdjustConfig.AD_REVENUE_TRADPLUS`	`"tradplus_sdk"`
`AdjustConfig.AD_REVENUE_TOPON`	`"topon_sdk"`
`AdjustConfig.AD_REVENUE_MOPUB`	`"mopub"`

Set data residency and URL strategy

In SDK v4, URL strategy and data residency domains are defined as constants in the AdjustConfig class.

Kotlin
Java

adjustConfig.setUrlStrategy(AdjustConfig.DATA_RESIDENCY_EU)

adjustConfig.setUrlStrategy(AdjustConfig.DATA_RESIDENCY_EU);

In SDK v5, you need to pass your chosen domain or domains as an array. You can also set the following:

useSubdomains (boolean): Whether the source should prefix a subdomain.
isDataResidency (boolean): Whether the domain should be used for data residency.

Kotlin
Java

val domains: List<String> = mutableListOf("domain") // eg. eu.adjust.com
val useSubdomains = true // or false
val isDataResidency = false // or true for data residency
adjustConfig.setUrlStrategy(domains, useSubdomains, isDataResidency)

List<String> domains = Arrays.asList("domain"); // eg. eu.adjust.com
boolean useSubdomains = true; // or false
boolean isDataResidency = false; // or true for data residency
adjustConfig.setUrlStrategy(domains, useSubdomains, isDataResidency);

Check the table below to see how to configure your URL strategy in SDK v5.

v4	v5 - main and fallback domain	v5 - use sub domains	v5 - is Data Residency
`AdjustConfig.DATA_RESIDENCY_EU`	`"eu.adjust.com"`	`true`	`true`
`AdjustConfig.DATA_RESIDENCY_TR`	`"tr.adjust.com"`	`true`	`true`
`AdjustConfig.DATA_RESIDENCY_US`	`"us.adjust.com"`	`true`	`true`
`AdjustConfig.URL_STRATEGY_CHINA`	`"adjust.world"`, `"adjust.com"`	`true`	`false`
`AdjustConfig.URL_STRATEGY_CN`	`"adjust.cn"`, `"adjust.com"`	`true`	`false`
`AdjustConfig.URL_STRATEGY_CN_ONLY`	`"adjust.cn"`	`true`	`false`
`AdjustConfig.URL_STRATEGY_INDIA`	`"adjust.net.in"`, `"adjust.com"`	`true`	`false`

adjustConfig.setUrlStrategy(listOf("adjust.net.in", "adjust.com"), true, false)

adjustConfig.setUrlStrategy(listOf("adjust.world", "adjust.com"), true, false)

adjustConfig.setUrlStrategy(listOf("adjust.cn"), true, false)

adjustConfig.setUrlStrategy(listOf("eu.adjust.com"), true, true)

adjustConfig.setUrlStrategy(listOf("tr.adjust.com"), true, true)

adjustConfig.setUrlStrategy(listOf("us.adjust.com"), true, true)

config.setUrlStrategy(Arrays.asList("adjust.net.in", "adjust.com"), true, false);

adjustConfig.setUrlStrategy(Arrays.asList("adjust.world", "adjust.com"), true, false);

adjustConfig.setUrlStrategy(Arrays.asList("adjust.cn"), true, false);

adjustConfig.setUrlStrategy(Arrays.asList("eu.adjust.com"), true, true);

adjustConfig.setUrlStrategy(Arrays.asList("tr.adjust.com"), true, true);

adjustConfig.setUrlStrategy(Arrays.asList("us.adjust.com"), true, true);

Device ID getters

In SDK v4, all device ID getter methods run synchronously. In SDK v5, these methods have been changed to run asynchronously.

Kotlin
Java

Adjust.getGoogleAdId(this, object : OnGoogleAdIdReadListener {
   override fun onGoogleAdIdRead(googleAdId: String) {}
})

Adjust.getAdid { adid ->
  // read adid
}

Adjust.getAttribution {attribution ->
   // read attribution
}

AdjustOaid.getOaid(applicationContext, object : OnOaidReadListener() {
      fun onOaidRead(oaid: String?) {}
      fun onFail(message: String?) {}
   })

Adjust.getAmazonAdId(applicationContext, object : OnAmazonAdIdReadListener {
      override fun onAmazonAdIdRead(amazonAdId: String) {}
   })

Adjust.getSdkVersion {sdkVersion ->
   // read sdk version
}

Adjust.isEnabled(applicationContext) { isEnabled ->
   // read isEnabled
}

Adjust.getGoogleAdId(this, new OnGoogleAdIdReadListener() {
    @Override
    public void onGoogleAdIdRead(String googleAdId) {}
});

Adjust.getAdid(new OnAdidReadListener() {
    @Override
    public void onAdidRead(String adid) {
    }
});

Adjust.getAttribution(new OnAttributionReadListener() {
    @Override
    public void onAttributionRead(AdjustAttribution attribution) {
    }
});

AdjustOaid.getOaid(getApplicationContext(), new OnOaidReadListener() {
   @Override
   public void onOaidRead(String oaid) {
   }


   @Override
   public void onFail(String message) {
   }
});

Adjust.getAmazonAdId(getApplicationContext(), new OnAmazonAdIdReadListener() {
    @Override
    public void onAmazonAdIdRead(String amazonAdId) {
    }
});

Adjust.getSdkVersion(new OnSdkVersionReadListener() {
    @Override
    public void onSdkVersionRead(String sdkVersion) {
    }
});

Adjust.isEnabled(getApplicationContext(), new OnIsEnabledListener() {
    @Override
    public void onIsEnabledRead(boolean isEnabled) {

    }
});

Removed APIs

Removed in v5

The following APIs have been removed in SDK v5.

Event buffering

SDK v4 supports event buffering. This feature stores requests event, ad revenue, push tokens, and other information on a local buffer to send at a later date.

Kotlin
Java

adjustConfig.setEventBufferingEnabled(true)

adjustConfig.setEventBufferingEnabled(true);

This setting has been removed in SDK v5.

Custom user agent string

SDK v4 supports setting a custom User Agent by calling AdjustConfig.setUserAgent() with a user agent string.

Kotlin
Java

adjustConfig.setUserAgent("user_agent_value")

adjustConfig.setUserAgent("user_agent_value");

This setting has been removed in SDK v5.

Set whether a device is known

In SDK v4, you can call the AdjustConfig.setDeviceKnown() method to manually inform the SDK whether a device is known.

Kotlin
Java

adjustConfig.setDeviceKnown(true)

adjustConfig.setDeviceKnown(true);

This setting has been removed in SDK v5.

Delay SDK start

SDK v4 supports delaying the start of the SDK by calling AdjustConfig.setDelayStart() with up to 120 seconds of delay.

Kotlin
Java

adjustConfig.setDelayStart(delay)

adjustConfig.setDelayStart(delay);

This setting has been removed in SDK v5.

In SDK v4, you can call the Adjust.disableThirdPartySharing() method to globally disable sharing information with third parties globally.

Kotlin
Java

Adjust.disableThirdPartySharing(applicationContext)

Adjust.disableThirdPartySharing(getApplicationContext());

This feature has been removed from SDK v5. In SDK v5, use the Adjust.trackThirdPartySharing() method to enable or disable third party sharing.

Kotlin
Java

val adjustThirdPartySharing = AdjustThirdPartySharing(true)
Adjust.trackThirdPartySharing(adjustThirdPartySharing)

AdjustThirdPartySharing adjustThirdPartySharing = new AdjustThirdPartySharing(true);
Adjust.trackThirdPartySharing(adjustThirdPartySharing);

Set an App Secret

SDK v4 supports setting an App Secret by calling setAppSecret method on your AdjustConfig instance to sign the SDK traffic with.

Kotlin
Java

adjustConfig.setAppSecret(secretId, info1, info2, info3, info4)

adjustConfig.setAppSecret(secretId, info1, info2, info3, info4);

This setting has been removed in SDK v5.

New plugins

Added in v5

The following plugins have been added to SDK v5.

Huawei Install Referrer plugin

SDK v5 supports a Huawei Install Referrer plugin to record a device’s Huawei Install Referrer information. To add the plugin, add the following dependency to your build.gradle file:

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

Meta Install Referrer plugin

SDK v5 supports a Meta Install Referrer plugin to record Meta Install Referrer information. To read this information:

Add the following dependency to your build.gradle file:

dependencies {
   implementation 'com.adjust.sdk:adjust-android-meta-referrer:5.0.0'
}

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.

Kotlin
Java

val config = AdjustConfig(this, appToken, environment)
config.setFbAppId(<FB_APP_ID_STRING>)
Adjust.initSdk(config)

AdjustConfig config = new AdjustConfig(this, appToken, environment);
config.setFbAppId(<FB_APP_ID_STRING>);
Adjust.initSdk(config);

Removed plugins

Removed in v5

The following plugins have been removed in SDK v5:

Criteo
Trademob
Sociomantic

SDK v5 migration guide

Before you begin

Install the SDK

Update the initialization method

Configure the SDK Signature library

New APIs

Install referrer getters

Changed APIs

Disable and enable the SDK

Offline mode

Preinstall recording

Send session information

Session callback parameters

Session partner parameters

Event deduplication

AdjustAttribution class

Reattribution using deep links

Deferred deep linking callback

COPPA compliance

Play Store Kids Apps

Send ad revenue from a specific source

Set data residency and URL strategy

Examples

Device ID getters

Removed APIs

Event buffering

Custom user agent string

Set whether a device is known

Delay SDK start

Disable third party sharing globally

Set an App Secret

New plugins

Huawei Install Referrer plugin

Meta Install Referrer plugin

Removed plugins