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 remove the signature library from your app first.
-
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.sdkFetching plugin "com.adjust.sdk" via npmInstalling "com.adjust.sdk" for androidInstalling "com.adjust.sdk" for iosIonic
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.sdkUpdate 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); // v4Adjust.initSdk(adjustConfig); // v5Changed 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 SDKAdjust.setEnabled(true); // enable SDKIn SDK v5, this feature is split into separate commands for clarity.
- Call
Adjust.disableto disable the SDK. - Call
Adjust.enableto 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.switchToOfflineModeto set the SDK to offline mode. - Call
Adjust.switchBackToOnlineModeto set the SDK back to online mode.
Adjust.switchToOfflineMode(); // Put the SDK in offline modeAdjust.switchBackToOnlineMode(); // Put the SDK back in online modeSession 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. Iftrue, the SDK will prefix the domains with Adjust-specific subdomains. Iffalse, 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.
| v4 | v5 - main and fallback domain | v5 - use sub domains | v5 - is Data Residency |
|---|---|---|---|
AdjustConfig.DataResidencyEU | "eu.adjust.com" | true | true |
AdjustConfig.DataResidencyTR | "tr.adjust.com" | true | true |
AdjustConfig.DataResidencyUS | "us.adjust.com" | true | true |
AdjustConfig.UrlStrategyChina | "adjust.world", "adjust.com" | true | false |
AdjustConfig.UrlStrategyCn | "adjust.cn", "adjust.com" | true | false |
AdjustConfig.UrlStrategyCnOnly | "adjust.cn" | true | false |
AdjustConfig.UrlStrategyIndia | "adjust.net.in", "adjust.com" | true | false |
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");| v4 | v5 |
|---|---|
AdjustConfig.AdRevenueAppLovinMAX | "applovin_max_sdk" |
AdjustConfig.AdRevenueSourceAdMob | "admob_sdk" |
AdjustConfig.AdRevenueSourceIronSource | "ironsource_sdk" |
AdjustConfig.AdRevenueSourceAdMost | "admost_sdk" |
AdjustConfig.AdRevenueSourceUnity | "unity_sdk" |
AdjustConfig.AdRevenueSourceHeliumChartboost | "helium_chartboost_sdk" |
AdjustConfig.AdRevenueSourceAdx | "adx_sdk" |
AdjustConfig.AdRevenueSourcePublisher | "publisher_sdk" |
AdjustConfig.AdRevenueSourceTopOn | "topon_sdk" |
AdjustConfig.AdRevenueSourceMopub | No longer supported |
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 callbackadjustConfig.setConversionValueUpdatedCallbackListener( function (conversionValue) { console.log("Conversion value updated callback received"); console.log("Conversion value: " + conversionValue.conversionValue); },);
// SKAN4 callbackadjustConfig.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 valuecoarseValue(string): The updated coarse conversion valuelockWindow(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);