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. To do this, add the following dependency to your pubspec.yaml file:

dependencies:
   adjust_sdk: ^5.0.0

Update the initialization method

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

Adjust.start(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 bool value.

1
Adjust.setEnabled(false); // disable SDK
2
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.

1
Adjust.disable();
2
Adjust.enable();

Send information in background

In SDK v4, you can set the sendInBackground property on your adjustConfig instance to true to enable the SDK to send information to Adjust while your app is running in the background.

1
adjustConfig.sendInBackground = true;

In SDK v5, you need to set the isSendingInBackgroundEnabled property on your adjustConfig instance to true to enable the SDK to send information to Adjust while your app is running in the background.

1
adjustConfig.isSendingInBackgroundEnabled = true;

Preinstalled app measurement

In SDK v4, you can set the preinstallTrackingEnabled property on your adjustConfig instance to true to enable measuring preinstalled apps.

1
adjustConfig.preinstallTrackingEnabled = true;

In SDK v5, you need to set the isPreinstallTrackingEnabled property on your adjustConfig instance to true to enable measuring preinstalled apps.

1
adjustConfig.isPreinstallTrackingEnabled = true;

Disable AdServices information reading

In SDK v4, you can set the allowAdServicesInfoReading property on your adjustConfig instance to false to prevent the Adjust SDK from reading AdServices information.

1
adjustConfig.allowAdServicesInfoReading = false;

In SDK v5, you need to set the isAdServicesEnabled property on your adjustConfig instance to false to prevent the Adjust SDK from reading AdServices information.

1
adjustConfig.isAdServicesEnabled = false;

Disable IDFA reading

In SDK v4, you can set the allowIdfaReading property on your adjustConfig instance to false to prevent the Adjust SDK from reading the device’s IDFA.

1
adjustConfig.allowIdfaReading = false;

In SDK v5, you need to set the isIdfaReadingEnabled property on your adjustConfig instance to false to prevent the Adjust SDK from reading the device’s IDFA.

1
adjustConfig.isIdfaReadingEnabled = false;

Enable cost data in attribution

In SDK v4, you can set the needsCost property on your adjustConfig instance to true to enable cost data in the device’s attribution information.

1
adjustConfig.needsCost = true;

In SDK v5, you need to set the isCostDataInAttributionEnabled property on your adjustConfig instance to true to enable cost data in the device’s attribution information.

1
adjustConfig.isCostDataInAttributionEnabled = true;

Enable LinkMe

In SDK v4, you can set the linkMeEnabled property on your adjustConfig instance to true to enable Adjust LinkMe.

1
adjustConfig.linkMeEnabled = true;

In SDK v5, you need to set the isLinkMeEnabled property on your adjustConfig instance to true to enable Adjust LinkMe.

1
adjustConfig.isLinkMeEnabled = true;

Only read device IDs once

In SDK v4, you can set the readDeviceInfoOnceEnabled property on your adjustConfig instance to true to instruct the SDK to only read device IDs once.

1
adjustConfig.readDeviceInfoOnceEnabled = true;

In SDK v5, you need to set the isDeviceIdsReadingOnceEnabled property on your adjustConfig instance to true to instruct the SDK to only read device IDs once.

1
adjustConfig.isDeviceIdsReadingOnceEnabled = true;

Offline mode

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

1
Adjust.setOfflineMode(true);
2
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.

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

Session callback parameters

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

1
Adjust.addSessionCallbackParameter('key', 'value');
2
Adjust.removeSessionCallbackParameter('key');
3
Adjust.resetSessionCallbackParameters();

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

1
Adjust.addGlobalCallbackParameter('key', 'value');
2
Adjust.removeGlobalCallbackParameter('key');
3
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.

1
Adjust.addSessionPartnerParameter('key', 'value');
2
Adjust.removeSessionPartnerParameter('key');
3
Adjust.resetSessionPartnerParameters();

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

1
Adjust.addGlobalPartnerParameter('key', 'value');
2
Adjust.removeGlobalPartnerParameter('key');
3
Adjust.removeGlobalPartnerParameters();

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.

1
AdjustAppStoreSubscription subscription = new AdjustAppStoreSubscription(
2
   price,
3
   currency,
4
   transactionId,
5
   receipt);

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

1
AdjustAppStoreSubscription subscription = new AdjustAppStoreSubscription(
2
   price,
3
   currency,
4
   transactionId);

App Store Purchases

In SDK v4, you can set a new purchase by configuring an AdjustAppStorePurchase object. This object is initialized with three arguments: receipt, product ID and transaction ID.

1
AdjustAppStorePurchase purchase = new AdjustAppStorePurchase(receipt, productId, transactionId);

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

1
AdjustAppStorePurchase purchase = new AdjustAppStorePurchase(productId, transactionId);

Play Store Subscriptions

In SDK v4, you can record the date on which the user purchased a subscription by passing a timestamp to the setPurchaseTime method.

1
adjustPlayStoreSubscription.setPurchaseTime('purchase-time');

In SDK v5, you need to assign a timestamp to the purchaseTime property on the adjustPlayStoreSubscription instance to record the date on which the user purchased a subscription.

1
adjustPlayStoreSubscription.purchaseTime = 'purchase-time';

Reattribution using deep links

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

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

1
Adjust.processDeeplink(new AdjustDeeplink('url'));

Launch deferred deep links

In SDK v4, you can set the launchDeferredDeeplink property on your adjustConfig instance to true to enable the SDK to open deep links.

1
adjustConfig.launchDeferredDeeplink = true;

In SDK v5, you need to set the isDeferredDeeplinkOpeningEnabled property on your adjustConfig instance to true to enable the SDK to open deep links.

1
adjustConfig.isDeferredDeeplinkOpeningEnabled = true;

Deep link resolution

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

1
Adjust.processDeeplink('url').then((resolvedLink) {
2
    // resolvedLink is the unshortened link
3
};

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

1
Adjust.processAndResolveDeeplink(new AdjustDeeplink('url')).then((resolvedLink) {
2
    // resolvedLink is the unshortened link
3
};

COPPA compliance

In SDK v4, you can set the coppaCompliantEnabled property on your adjustConfig instance to true to enable COPPA compliance.

1
adjustConfig.coppaCompliantEnabled = true;

In SDK v5, you need to set the isCoppaComplianceEnabled property on your adjustConfig instance to a true to enable COPPA compliance.

1
adjustConfig.isCoppaComplianceEnabled = true;

Play Store Kids Apps

In SDK v4, you can mark an app as a Play Store Kids app setting the playStoreKidsAppEnabled property on your adjustConfig instance to true. This property is read during SDK initialization, which means that the value can’t be updated once the SDK is initialized.

1
adjustConfig.playStoreKidsAppEnabled = true;

In SDK v5, you need to set the isPlayStoreKidsComplianceEnabled property of your adjustConfig instance to true to enable compliance.

1
adjustConfig.isPlayStoreKidsComplianceEnabled = true;

Set data residency and URL strategy

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

1
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 (bool): 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 (bool): Whether the domain should be used for data residency.

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

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

Examples

adjustConfig.setUrlStrategy(['adjust.net.in', 'adjust.com'], true, false);

adjustConfig.setUrlStrategy(['adjust.world', 'adjust.com'], true, false);

adjustConfig.setUrlStrategy(['adjust.cn'], true, false);

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

adjustConfig.setUrlStrategy(['tr.adjust.com'], true, true);

adjustConfig.setUrlStrategy(['us.adjust.com'], true, true);

Record ad revenue

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

1
Adjust.trackAdRevenue('source', 'payload');

With an updated method in the SDK v4, you can create a new AdjustAdRevenue object with the source and record ad revenue by passing this object to the trackAdRevenueNew method.

1
AdjustAdRevenue adRevenue = new AdjustAdRevenue('source');
2
adRevenue.setRevenue(6, 'CAD');
3
Adjust.trackAdRevenueNew(adRevenue);

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

1
AdjustAdRevenue adRevenue = new AdjustAdRevenue('source');
2
adRevenue.setRevenue(6, 'CAD');
3
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.

AdjustAdRevenue adRevenue = new AdjustAdRevenue(AdjustConfig.AdRevenueSourceAppLovinMAX);
AdjustAdRevenue 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.

1
adjustConfig.deactivateSKAdNetworkHandling();

In SDK v5, you need to set the isSkanAttributionEnabled property on your adjustConfig instance to false to disable SKAdNetwork communication.

1
adjustConfig.isSkanAttributionEnabled = false;

Listen for conversion value updates

In SDK v4, you can use the skad4conversionValueUpdatedCallback property on your adjustConfig to listen for conversion value updates. Before SKAN4, you could use the conversionValueUpdatedCallback property.

1
// pre-SKAN4 callback
2
adjustConfig.conversionValueUpdatedCallback = (num? conversionValue) {
3
};
4

5

6
// SKAN4 callback
7
adjustConfig.skad4ConversionValueUpdatedCallback = (num? conversionValue, String? coarseValue, bool? lockWindow) {
8
};

In SDK v5, you need to assig a callback function to the skanUpdatedCallback property of your adjustConfig object.

1
config.skanUpdatedCallback = (Map<String, String> skanUpdateData) {
2
  print('[Adjust]: Received SKAN update information!');
3
  if (skanUpdateData["conversion_value"] != null) {
4
    print('[Adjust]: Conversion value: ' + skanUpdateData["conversion_value"]!);
5
  }
6
  if (skanUpdateData["coarse_value"] != null) {
7
    print('[Adjust]: Coarse value: ' + skanUpdateData["coarse_value"]!);
8
  }
9
  if (skanUpdateData["lock_window"] != null) {
10
    print('[Adjust]: Lock window: ' + skanUpdateData["lock_window"]!);
11
  }
12
  if (skanUpdateData["error"] != null) {
13
    print('[Adjust]: Error: ' + skanUpdateData["error"]!);
14
  }
15
};

Update conversion values

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

1
Adjust.updateConversionValue(6);
2

3
Adjust.updateConversionValueWithErrorCallback(6).then((error) {
4
    // error is present in case it happened
5
});
6

7
Adjust.updateConversionValueWithErrorCallbackSkad4(6, 'coarse-value', true).then((error) {
8
    // error is present in case it happened
9
});

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

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

1
Adjust.updateSkanConversionValue(6, 'coarse-value', true).then((error) {
2
    // error is present in case it happened
3
});

App Tracking Transparency authorization wrapper

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

1
Adjust.requestTrackingAuthorizationWithCompletionHandler().then((status) {
2
  print('[Adjust]: Authorization status update!');
3
  switch (status) {
4
    case 0:
5
      print(
6
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusNotDetermined');
7
      break;
8
    case 1:
9
      print(
10
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusRestricted');
11
      break;
12
    case 2:
13
      print(
14
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusDenied');
15
      break;
16
    case 3:
17
      print(
18
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusAuthorized');
19
      break;
20
  }
21
});

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

1
Adjust.requestAppTrackingAuthorization().then((status) {
2
  print('[Adjust]: Authorization status update!');
3
  switch (status) {
4
    case 0:
5
      print(
6
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusNotDetermined');
7
      break;
8
    case 1:
9
      print(
10
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusRestricted');
11
      break;
12
    case 2:
13
      print(
14
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusDenied');
15
      break;
16
    case 3:
17
      print(
18
          '[Adjust]: Authorization status update: ATTrackingManagerAuthorizationStatusAuthorized');
19
      break;
20
  }
21
});

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 to send at a later date.

1
adjustConfig.eventBufferingEnabled = true;

This setting has been removed in SDK v5.

Custom user agent string

SDK v4 supports setting a custom User Agent by assigning a user string agent to theuserAgent property on your adjustConfig instance.

1
adjustConfig.userAgent = 'custom-user-agent';

This setting has been removed in SDK v5.

Set whether a device is known

In SDK v4, you can set the isDeviceKnown property on your adjustConfig instance to manually inform the SDK whether a device is known.

1
adjustConfig.isDeviceKnown = true;

This setting has been removed in SDK v5.

Delay SDK start

SDK v4 supports delaying the start of the SDK by setting the delayStart property on your adjustConfig instance a delay. You can set up this delay for up to 10 seconds.

1
adjustConfig.delayStart = 10;

This setting has been removed in SDK v5 including the Adjust.checkForNewAttStatus method. Calling this method would make SDK stop the delay and continue with its work.

Final Android attribution

In SDK v4, you can set the finalAndroidAttributionEnabled property on your adjustConfig instance to true to deliver final Android attribution.

1
adjustConfig.finalAndroidAttributionEnabled = 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.

AdjustEvent changes

In SDK v4, you can send a receipt to the adjustEvent.receipt property on your adjustEvent for subscriptions and purchases.

1
adjustEvent.receipt = 'receipt';

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

Disable third party sharing globally

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

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

1
AdjustThirdPartySharing thirdPartySharing = new AdjustThirdPartySharing(false);
2
Adjust.trackThirdPartySharing(thirdPartySharing);

Set an App Secret

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

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

This setting has been removed in SDK v5.