iOS Web bridge 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 uninstall this first.
2. If your app targets API versions lower than the following, you need to update your app before you can use SDK v5:
   • iOS: 12.0
   • tvOS: 12.0

Install the SDK

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

1. Remove any older versions of the SDK you currently have in your Podfile.

2. Add the following line to your Podfile:

   pod 'Adjust/AdjustWebBridge', :git => 'https://github.com/adjust/ios_sdk.git', :tag => 'v5.0.0'

3. Run pod install to install the dependencies.

Update the initialization method

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

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

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

New APIs

The following APIs have been added in SDK v5.

Disable IDFA reading

In SDK v5, you can prevent the Adjust SDK from reading the device ID for Advertisers (IDFA) by calling the disableIdfaReading method on your AdjustConfig instance.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.disableIdfaReading();

Disable deferred deep link opening

In SDK v5, you can prevent the SDK from opening deferred deep links by calling the disableDeferredDeeplinkOpening method of your AdjustConfig instance.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.disableDeferredDeepLinkOpening();

Disable SKAdNetwork attribution

In SDK v5, you can prevent the Adjust SDK from sending attribution information to Apple’s SKAdNetwork by calling the disableSkanAttributionHandling method of your AdjustConfig instance.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.disableSkanAttributionHandling();

SKAdNetwork update callback

In SDK v5, you can configure the Adjust SDK to execute a callback function when a user’s SKAdNetwork conversion value changes by calling the setSkanUpdatedCallback method of your AdjustConfig instance with a callback function.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2

3
adjustConfig.setSkanUpdatedCallback(function (skanData) {
4
   alert("SKAN: " + skanData.error);
5
});

Changed APIs

The following APIs have been changed in SDK v5.

Disable AdServices information reading

In SDK v4, you can call the setAllowAdServicesInfoReading method of your AdjustConfig instance with a false argument to prevent the Adjust SDK from reading AdServices information.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.setAllowAdServicesInfoReading(false);

In SDK v5, you need to call the disableAdServices method with no arguments to prevent the Adjust SDK from reading AdServices information.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.disableAdServices();

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

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

1
Adjust.setOfflineMode(false); // put SDK in offline mode
2
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.

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

Enable cost data in attribution

In SDK v4, you can enable the SDK to send cost data as part of a user’s attribution by calling the setNeedsCost method of your AdjustConfig instance with a boolean argument.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.setNeedsCost(true);

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

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.enableCostDataInAttribution();

Session callback parameters

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

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.

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.

1
const event = new AdjustEvent("event_token");
2
event.setOrderId("deduplication_id");
3
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.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2

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

6
const event = new AdjustEvent("event_token");
7
event.setDeduplicationId("deduplication_id");
8
Adjust.trackEvent(event);

COPPA compliance

In SDK v4, COPPA compliance is set by calling the setCoppaCompliantEnabled method on your AdjustConfig instance with a boolean argument.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.setCoppaCompliantEnabled(true);

In SDK v5, this method is renamed to enableCoppaCompliance for clarity. This new method accepts no arguments.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.enableCoppaCompliance();

Set data residency and URL strategy

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

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.setUrlStrategy(AdjustConfig.DataResidencyEU);

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.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
const domains = ["domain1", "domain2"];
3
const useSubdomains = true;
4
const isDataResidency = false;
5
adjustConfig.setUrlStrategy(domains, useSubdomains, isDataResidency);

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

Examples

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["adjust.net.in", "adjust.com"], true, false);

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["adjust.world", "adjust.com"], true, false);

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["adjust.cn"], true, false);

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["eu.adjust.com"], true, true);

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["tr.adjust.com"], true, true);

const adjustConfig = new AdjustConfig(this, appToken, environment);
adjustConfig.setUrlStrategy(["us.adjust.com"], true, true);

Request ATT authorization status

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

1
Adjust.requestTrackingAuthorizationWithCompletionHandler(function(status) {
2
  alert('Permission status\n' + status);
3
};

This has been renamed to requestAppTrackingAuthorizationWithCompletionHandler in SDK v5 for clarity.

1
Adjust.requestAppTrackingAuthorizationWithCompletionHandler(function(status) {
2
  alert('Permission status\n' + status);
3
};

Device ID getters

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

Adjust.getAdid(function (adid) {
   alert("Ad Id:\n" + adid);
});

Adjust.getAttribution(function (attribution) {
   alert(
      "Tracker token = " +
         attribution.trackerToken +
         "\n" +
         "Tracker name = " +
         attribution.trackerName +
         "\n" +
         "Network = " +
         attribution.network +
         "\n" +
         "Campaign = " +
         attribution.campaign +
         "\n" +
         "Adgroup = " +
         attribution.adgroup +
         "\n" +
         "Creative = " +
         attribution.creative +
         "\n" +
         "Click label = " +
         attribution.clickLabel,
   );
});

Adjust.getSdkVersion(function (sdkVersion) {
   alert("SDK version:\n" + sdkVersion);
});

Adjust.isEnabled(function (isEnabled) {
   alert("Is SDK enabled? " + isEnabled);
});

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
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
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 the setUserAgent method of your AdjustConfig instance with a user agent string.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
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 setDeviceKnown method of your AdjustConfig instance to manually inform the SDK whether a device is known.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
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 the setDelayStart method on your AdjustConfig instance with up to 120 seconds of delay. If the app is ready before the delay ends, information can be sent immediately by calling Adjust.sendFirstPackages.

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.setDelayStart(delay);
3

4
Adjust.sendFirstPackages();

Both of these methods have been removed in SDK v5.

Set push token

SDK v4 supports setting a device push token by calling Adjust.setDeviceToken with your push token.

1
Adjust.setDeviceToken(deviceToken);

This feature has been removed in SDK v5.

Reattribution using deep links

In SDK v4, you can pass a deep link URL to Adjust in the Web bridge by calling the Adjust.appWillOpenUrl() method.

1
Adjust.appWillOpenUrl(data, getApplicationContext());

This method has been removed in SDK v5.

Adjust LinkMe

In SDK v4, you can enable Adjust LinkMe using the Adjust Web bridge by calling the setLinkMeEnabled method of your AdjustConfig instance with a boolean argument.

1
setupWebViewJavascriptBridge(function (bridge) {
2
   var yourAppToken = yourAppToken;
3
   var environment = AdjustConfig.EnvironmentSandbox;
4
   var adjustConfig = new AdjustConfig(yourAppToken, environment);
5
   adjustConfig.setLinkMeEnabled(true);
6
});

This method has been removed in SDK v5.

Send ad revenue from a specific source

In SDK v4, you can send ad revenue from a specific source by passing a source and payload to the Adjust.trackAdRevenue() method.

1
Adjust.trackAdRevenue(source, payload);

This method has been removed in SDK v5.

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
const adjustThirdPartySharing = new AdjustThirdPartySharing(true);
2
Adjust.trackThirdPartySharing(adjustThirdPartySharing);

Check for ATT status

In SDK v4, you can check for changes to a user’s ATT status by calling the Adjust.checkForNewAttStatus method.

1
Adjust.checkForNewAttStatus();

This method has been removed in SDK v5.

Set an App Secret

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

1
const adjustConfig = new AdjustConfig(this, appToken, environment);
2
adjustConfig.setAppSecret(secretId, info1, info2, info3, info4);

This setting has been removed in SDK v5.