SDK v5 migration guide

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 remove the signature library from your app first.

2. The minimum supported API versions for SDK v5 have been updated. If your app targets a lower version, you need to update it first.

   • iOS: 12.0
   • Android: 21

Install the SDK

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

Cordova plugin

To add the Adjust Cordova SDK to your Cordova plugin, run the following command:

> cordova plugin add com.adjust.sdk
Fetching plugin "com.adjust.sdk" via npm
Installing "com.adjust.sdk" for android
Installing "com.adjust.sdk" for ios

Ionic

If you use Ionic to build your app, add the SDK from the awesome-cordova-plugins repository by running the following command:

> npm install @awesome-cordova-plugins/adjust --save
> ionic cordova plugin add com.adjust.sdk

Update the initialization method

In SDK v4, the initialization method is Adjust.create. This has been changed to Adjust.initSdk in SDK v5.

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

Changed APIs

The following APIs have been 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.

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.

Adjust.disable();
Adjust.enable();

Send information in background

In SDK v4, you can call the setSendInBackground method on your adjustConfig instance with a boolean value to enable the SDK to send information to Adjust while your app is running in the background.

adjustConfig.setSendInBackground(true);

In SDK v5, you need to call the enableSendingInBackground method on your adjustConfig instance to enable the SDK to send information to Adjust while your app is running in the background. The default state is false.

adjustConfig.enableSendingInBackground();

Preinstalled app measurement

In SDK v4, you can call the setPreinstallTrackingEnabled method on your adjustConfig instance with the value true to enable measuring preinstalled apps.

adjustConfig.setPreinstallTrackingEnabled(true);

In SDK v5, you need to call the enablePreinstallTracking method on your adjustConfig instance to enable measuring preinstalled apps. The default state is false.

adjustConfig.enablePreinstallTracking();

Disable AdServices information reading

In SDK v4, you can call the setAllowAdServicesInfoReading method on your adjustConfig with the value false to prevent the Adjust SDK from reading AdServices information.

adjustConfig.setAllowAdServicesInfoReading(false);

In SDK v5, you need to call the disableAdServices method on your adjustConfig instance to prevent the Adjust SDK from reading AdServices information. The default state is true.

adjustConfig.disableAdServices();

Disable IDFA reading

In SDK v4, you can call the setAllowIdfaReading method on your adjustConfig with the value false to prevent the Adjust SDK from reading the device’s IDFA.

adjustConfig.setAllowIdfaReading(false);

In SDK v5, you need to call the disableIdfaReading method on your adjustConfig instance to prevent the Adjust SDK from reading the device’s IDFA. The default state is true.

adjustConfig.disableIdfaReading();

Enable cost data in attribution

In SDK v4, you can call the setNeedsCost method on your adjustConfig instance with the value true to enable cost data in the device’s attribution information.

adjustConfig.setNeedsCost(true);

In SDK v5, you need to call the enableCostDataInAttribution method on your adjustConfig instance to enable cost data in the device’s attribution information. The default state is false.

adjustConfig.enableCostDataInAttribution();

Set attribution callback

In SDK v4, you can set a delegate callback function to trigger when the user’s attribution data changes by calling the setAttributionCallbackListener method on your AdjustConfig instance.

adjustConfig.setAttributionCallbackListener(function (attribution) {});

In SDK v5, this method has been renamed to setAttributionCallback. All arguments remain the same.

adjustConfig.setAttributionCallback(function (attribution) {});

Enable LinkMe

In SDK v4, you can call the setLinkMeEnabled method on your adjustConfig instance with the value true to enable Adjust LinkMe.

adjustConfig.setLinkMeEnabled(true);

In SDK v5, you need to call the enableLinkMe method on your adjustConfig instance to enable Adjust LinkMe. The default state is false.

adjustConfig.enableLinkMe();

Only read device IDs once

In SDK v4, you can call the setReadDeviceInfoOnceEnabled method on your adjustConfig with the value true to instruct the SDK to only read device IDs once.

adjustConfig.setReadDeviceInfoOnceEnabled(true);

In SDK v5, you need to call the enableDeviceIdsReadingOnce method on your adjustConfig to instruct the SDK to only read device IDs once. The default state is false.

adjustConfig.enableDeviceIdsReadingOnce();

Offline mode

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

Adjust.setOfflineMode(true);
Adjust.setOfflineMode(false);

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.

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

Session callback parameters

In SDK v4, you can add session callback parameters by passing a key-value pair to the Adjust.addSessionCallbackParameter method and remove individual parameters using the Adjust.removeSessionCallbackParameter method.

Adjust.addSessionCallbackParameter("key", "value");
Adjust.removeSessionCallbackParameter("key");
Adjust.resetSessionCallbackParameters();

In SDK v5, session callback parameters are renamed to global parameters.

Adjust.addGlobalCallbackParameter("key", "value");
Adjust.removeGlobalCallbackParameter("key");
Adjust.removeGlobalCallbackParameters();

Session partner parameters

In SDK v4, you can add session partner parameters by passing a key-value pair to the Adjust.addSessionPartnerParameter method and remove individual parameters using the Adjust.removeSessionPartnerParameter method.

Adjust.addSessionPartnerParameter("key", "value");
Adjust.removeSessionPartnerParameter("key");
Adjust.resetSessionPartnerParameters();

In SDK v5, session partner parameters are renamed to global partner parameters.

Adjust.addGlobalPartnerParameter("key", "value");
Adjust.removeGlobalPartnerParameter("key");
Adjust.removeGlobalPartnerParameters();

Event deduplication

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

adjustEvent.setTransactionId("transaction-id");

In SDK v5, the feature is decoupled from transaction ID. A new ID field called deduplicationId has been added for event deduplication.

adjustEvent.setDeduplicationId("deduplication-id");

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.

adjustConfig.setEventDeduplicationIdsMaxSize(20);

Session success callbacks

In SDK v4, you can call the setSessionTrackingSucceededCallbackListener to register a succeeded session recording by the SDK.

adjustConfig.setSessionTrackingSucceededCallbackListener(
   function (sessionSuccess) {
      // Printing all session success properties.
      console.log("Session recording succeeded!");
      console.log(sessionSuccess.message);
      console.log(sessionSuccess.timestamp);
      console.log(sessionSuccess.adid);
      console.log(sessionSuccess.jsonResponse);
   },
);

In SDK v5, this has been renamed to setSessionTrackingSucceededCallback. The jsonResponse property has been changed from a map to a JSON string for iOS.

adjustConfig.setSessionTrackingSucceededCallback(function (sessionSuccess) {
   // Printing all session success properties.
   console.log("Session recording succeeded!");
   console.log(sessionSuccess.message);
   console.log(sessionSuccess.timestamp);
   console.log(sessionSuccess.adid);
   console.log(sessionSuccess.jsonResponse);
});

Session failure callbacks

In SDK v4, you can call the setSessionTrackingFailedCallbackListener to register a failed session recording by the SDK.

adjustConfig.setSessionTrackingFailedCallbackListener(
   function (sessionFailure) {
      console.log("Session recording failed!");
      console.log(sessionFailure.message);
      console.log(sessionFailure.timestamp);
      console.log(sessionFailure.adid);
      console.log(sessionFailure.willRetry);
      console.log(sessionFailure.jsonResponse);
   },
);

In SDK v5, this has been renamed to setSessionTrackingFailedCallback.

adjustConfig.setSessionTrackingFailedCallback(function (sessionFailure) {
   console.log("Session recording failed!");
   console.log(sessionFailure.message);
   console.log(sessionFailure.timestamp);
   console.log(sessionFailure.adid);
   console.log(sessionFailure.willRetry);
   console.log(sessionFailure.jsonResponse);
});

Event success callbacks

In SDK v4, you can call the setEventTrackingSucceededCallbackListener to register a succeeded event recording by the SDK.

adjustConfig.setEventTrackingSucceededCallbackListener(function (eventSuccess) {
   // Printing all event success properties.
   console.log("Event recording succeeded!");
   console.log(eventSuccess.message);
   console.log(eventSuccess.timestamp);
   console.log(eventSuccess.eventToken);
   console.log(eventSuccess.callbackId);
   console.log(eventSuccess.adid);
   console.log(eventSuccess.jsonResponse);
});

In SDK v5, this has been renamed to setEventTrackingSucceededCallback.

adjustConfig.setEventTrackingSucceededCallback(function (eventSuccess) {
   // Printing all event success properties.
   console.log("Event recording succeeded!");
   console.log(eventSuccess.message);
   console.log(eventSuccess.timestamp);
   console.log(eventSuccess.eventToken);
   console.log(eventSuccess.callbackId);
   console.log(eventSuccess.adid);
   console.log(eventSuccess.jsonResponse);
});

Event failure callbacks

In SDK v4, you can call the setEventTrackingFailedCallbackListener to register a failed event recording by the SDK.

adjustConfig.setEventTrackingFailedCallbackListener(function (eventFailure) {
   // Printing all event failure properties.
   console.log("Event recording failed!");
   console.log(eventFailure.message);
   console.log(eventFailure.timestamp);
   console.log(eventFailure.eventToken);
   console.log(eventFailure.callbackId);
   console.log(eventFailure.adid);
   console.log(eventFailure.willRetry);
   console.log(eventFailure.jsonResponse);
});

In SDK v5, this has been renamed to setEventTrackingFailedCallback.

adjustConfig.setEventTrackingFailedCallback(function (eventFailure) {
   // Printing all event failure properties.
   console.log("Event recording failed!");
   console.log(eventFailure.message);
   console.log(eventFailure.timestamp);
   console.log(eventFailure.eventToken);
   console.log(eventFailure.callbackId);
   console.log(eventFailure.adid);
   console.log(eventFailure.willRetry);
   console.log(eventFailure.jsonResponse);
});

App Store Subscriptions

In SDK v4, you can set a new subscription by configuring an AdjustAppStoreSubscription object. This object is initialized with four arguments: price, currency, transactionId, and receipt.

var subscription = new AdjustAppStoreSubscription(
   price,
   currency,
   transactionId,
   receipt,
);

In SDK v5, you don’t need to pass the receipt argument as it’s no longer needed for purchase verification.

var subscription = new AdjustAppStoreSubscription(
   price,
   currency,
   transactionId,
);

Reattribution using deep links

In SDK v4, you can pass your deep link information to the Adjust.appWillOpenUrl method.

Adjust.appWillOpenUrl("url");

In SDK v5, this has been renamed to Adjust.processDeeplink for clarity. A new AdjustDeeplink class has been added for constructing deep links. To process a deep link, instantiate an AdjustDeeplink object with your deep link URL and pass it to the Adjust.processDeeplink method.

Adjust.processDeeplink(new AdjustDeeplink("url"));

Launch deferred deep links

In SDK v4, you can call the setShouldlaunchDeeplink method on your adjustConfig instance with the value false to disable the SDK to open deep links.

adjustConfig.setShouldLaunchDeeplink(false);

In SDK v5, deep links are opened by default. You need to call the disableDeferredDeeplinkOpening method on your adjustConfig instance to disable the SDK to open deep links.

adjustConfig.disableDeferredDeeplinkOpening();

Deep link resolution

In SDK v4, you can resolve a shortened deep link by passing the url to the processDeeplink method.

Adjust.processDeeplink("url", function (resolvedLink) {
   console.log("Resolved link: " + resolvedLink);
});

In SDK v5, you need to send an AdjustDeeplink object initialized with the deep link url. This returns the original unshortened deep link.

Adjust.processAndResolveDeeplink(
   new AdjustDeeplink("url"),
   function (resolvedLink) {
      console.log("Resolved link: " + resolvedLink);
   },
);

Deep link callback listener

In SDK v4, you can configure a listener function that fires when a deep link is received by calling the setDeferredDeeplinkCallbackListener method on your AdjustConfig instance.

adjustConfig.setDeferredDeeplinkCallbackListener(function (deeplink) {
   console.log("Deferred deep link = " + deeplink);
});

In SDK v5, this method has been renamed to setDeferredDeeplinkCallback. All arguments remain the same.

adjustConfig.setDeferredDeeplinkCallback(function (deeplink) {
   console.log("Deferred deep link = " + deeplink);
});

COPPA compliance

In SDK v4, you can call the coppaCompliantEnabled method on your adjustConfig instance with the value true to enable COPPA compliance.

adjustConfig.setCoppaCompliantEnabled(true);

In SDK v5, you need to call the enableCoppaCompliance method on your adjustConfig instance to enable COPPA compliance. The default state is false.

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 the value true. This is read during SDK initialization, which means that the value can’t be updated once the SDK is initialized.

adjustConfig.setPlayStoreKidsAppEnabled(true);

In SDK v5, you need to call the enablePlayStoreKidsCompliance method of your adjustConfig instance to enable compliance. The default state is false.

adjustConfig.enablePlayStoreKidsCompliance();

Set data residency and URL strategy

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

adjustConfig.setUrlStrategy(AdjustConfig.DataResidencyEU);

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

• useSubdomains (boolean): Whether the domain should be treated as an Adjust domain. If true, the SDK will prefix the domains with Adjust-specific subdomains. If false, the SDK will use the provided domain as-is, without adding any prefixes.
• isDataResidency (boolean): Whether the domain should be used for data residency.

adjustConfig.setUrlStrategy(["eu.adjust.com"], true, true);

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

Record ad revenue

In SDK v4, you can record ad revenue by calling the trackAdRevenue method, passing source and payload as arguments.

Adjust.trackAdRevenue("source", "payload");

Alternatively, you can instantiate an AdjustAdRevenue object and call the setRevenue method to set the ad revenue amount.

var adRevenue = new AdjustAdRevenue("source");
adRevenue.setRevenue(6, "CAD");
Adjust.trackAdRevenue(adRevenue);

In SDK v5, you must create a new AdjustAdRevenue object with the source and record ad revenue by passing this object to the trackAdRevenue method.

var adRevenue = new AdjustAdRevenue("source");
adRevenue.setRevenue(6, "CAD");
Adjust.trackAdRevenue(adRevenue);

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.

var adRevenue = new AdjustAdRevenue(AdjustConfig.AdRevenueSourceAppLovinMAX);
var adRevenue = new AdjustAdRevenue("applovin_max_sdk");

Disable SKAdNetwork communication

In SDK v4, you can prevent the SDK from communicating with SKAdNetwork by calling the adjustConfig.deactivateSKAdNetworkHandling method.

adjustConfig.deactivateSKAdNetworkHandling();

In SDK v5, you need to call the disableSkanAttribution method on your adjustConfig instance to disable SKAdNetwork communication. The default state is true.

adjustConfig.disableSkanAttribution();

Listen for conversion value updates

In SDK v4, you can call the setSkad4ConversionValueUpdatedCallbackListener method on your adjustConfig to listen for conversion value updates. Before SKAN4, you could use the setConversionValueUpdatedCallbackListener method.

// pre-SKAN4 callback
adjustConfig.setConversionValueUpdatedCallbackListener(
   function (conversionValue) {
      console.log("Conversion value updated callback received");
      console.log("Conversion value: " + conversionValue.conversionValue);
   },
);

// SKAN4 callback
adjustConfig.setSkad4ConversionValueUpdatedCallbackListener(
   function (conversionValue) {
      console.log("Conversion value updated callback received");
      console.log("Conversion value: " + conversionValue.conversionValue);
   },
);

In SDK v5, you need to assign a callback function to the setSkanUpdatedCallback method of your adjustConfig object.

adjustConfig.setSkanUpdatedCallback(function (skanData) {
   console.log("Conversion value: " + skanData.conversionValue);
   console.log("Coarse value: " + skanData.coarseValue);
   console.log("Lock window: " + skanData.lockWindow);
   console.log("Error: " + skanData.error);
});

Update conversion values

In SDK v4, you can use one of these methods to send updated conversion values to Adjust:

Adjust.updateConversionValue(6);

Adjust.updateConversionValueWithErrorCallback(6, function (error) {
   // error is present in case it happened
});

Adjust.updateConversionValueWithSkad4ErrorCallback(
   6,
   "low",
   true,
   function (error) {
      // error is present in case it happened
   },
);

To update conversion values in SDK v5, use the updateSkanConversionValue method with the following arguments:

• conversionValue (Number): The updated conversion value
• coarseValue (string): The updated coarse conversion value
• lockWindow (boolean): Whether to send the postback before the conversion window ends

Adjust.updateSkanConversionValue(6, "low", true, function (error) {
   // error is present in case it happened
});

App Tracking Transparency authorization wrapper

In SDK v4, you can handle changes to a user’s ATT authorization status using the Adjust.requestTrackingAuthorizationWithCompletionHandler method.

Adjust.requestTrackingAuthorizationWithCompletionHandler(function (status) {
   print("[Adjust]: Authorization status update!");
   switch (status) {
      case 0:
         print(
            "[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusNotDetermined",
         );
         break;
      case 1:
         print(
            "[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusRestricted",
         );
         break;
      case 2:
         print(
            "[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusDenied",
         );
         break;
      case 3:
         print(
            "[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusAuthorized",
         );
         break;
   }
});

This has been renamed to Adjust.requestAppTrackingAuthorization in SDK v5 for clarity.

Adjust.requestAppTrackingAuthorization(function (status) {
   print("[Adjust]: Authorization status update!");
   switch (status) {
      case 0:
         print(
            "[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusNotDetermined",
         );
         break;
      case 1:
         print(
            "[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusRestricted",
         );
         break;
      case 2:
         print(
            "[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusDenied",
         );
         break;
      case 3:
         print(
            "[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusAuthorized",
         );
         break;
   }
});

Device ID getters

In SDK v4, if you call for a device ID that doesn’t exist on the device platform, the getter returns an empty string ("").

Adjust.getIdfa(function (idfa) {
   // Returns IDFA on iOS
   // Returns "" on Android
});

In SDK v5, calling for a device ID that doesn’t exist on the device platform has no effect. The callback function doesn’t execute.

Adjust.getIdfa(function (idfa) {
   // Returns IDFA on iOS
   // Does not execute on Android
});

Removed APIs

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 for 60 seconds after which it sends them.

adjustConfig.setEventBufferingEnabled(true);

This method has been removed in SDK v5.

Custom user agent string

SDK v4 supports setting a custom User Agent by passing a user string agent to thesetUserAgent method on your AdjustConfig instance.

adjustConfig.setUserAgent("custom-user-agent");

This method has been removed in SDK v5.

Set whether a device is known

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

adjustConfig.setDeviceKnown(true);

This method has been removed in SDK v5.

Delay SDK start

SDK v4 supports delaying the start of the SDK by calling the setDelayStart method on your AdjustConfig instance with a delay. You can set up this delay for up to 10 seconds.

adjustConfig.setDelayStart(10);

This method has been removed in SDK v5. The Adjust.sendFirstPackages method that interrupts this delay has also been removed.

Check for new ATT status

SDK v4 supports the Adjust.checkForNewAttStatus method. Calling this method would make the SDK check whether the ATT status had changed since the last SDK activity and inform Adjust’s servers of any changes.

Adjust.checkForNewAttStatus();

This method has been removed in SDK v5.

Final Android attribution

In SDK v4, you can call the setFinalAndroidAttributionEnabled method on your AdjustConfig instance with the value true to deliver final Android attribution.

adjustConfig.setFinalAndroidAttributionEnabled(true);

This setting has been removed in SDK v5 since now only the final attribution will be delivered through the attribution callback on the Android platform.

Set referrer

In SDK v4, you can call the setReferrer method to trigger an SDK click with a custom click ID when the SDK starts.

Adjust.setReferrer("referrer");

This method has been removed in SDK v5. Google has deprecated the INSTALL_REFERRER intent method of delivering referrer information for Google Play Services. If you currently use this method, migrate to the Google Play Referrer API.

Convert universal link

In SDK v4, you can call the convertUniversalLink method.

Adjust.convertUniversalLink(url, scheme, function (convertedLink) {
   console.log("Converted link = " + convertedLink);
});

This method has been removed in SDK v5.

AdjustEvent changes

In SDK v4, you can send a receipt to the adjustEvent.setReceipt method on your AdjustEvent instance for purchase verification.

adjustEvent.setReceipt("receipt");

This parameter has been removed in SDK v5 since it’s no longer needed for purchase verification.

Purchase verification

In SDK v4, you must instantiate an AdjustAppStorePurchase object with a receipt argument. This value is used for purchase verification.

var appStorePurchase = new AdjustAppStorePurchase(
   "receipt",
   "product-id",
   "transaction-id",
);

This property has been removed in SDK v5. If you’re using the AdjustAppStorePurchase class for purchase verification, you must remove this argument from your construction call.

var appStorePurchase = new AdjustAppStorePurchase(
   "product-id",
   "transaction-id",
);

Disable third party sharing globally

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

Adjust.disableThirdPartySharing();

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

var thirdPartySharing = new AdjustThirdPartySharing(false);
Adjust.trackThirdPartySharing(thirdPartySharing);