adjust-icon

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 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 beta 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:

    Podfile
    pod 'Adjust', :git => 'https://github.com/adjust/ios_sdk.git', :branch => 'v5'
  3. Run pod install to install the dependencies.

Update the initialization method

Changed in v5

In SDK v4, the SDK is initialized by configuring an ADJConfig object and passing it to the [Adjust appDidLaunch] method.

In SDK v5, this method has been renamed to [Adjust initSdk].

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.

Changed APIs

Changed in v5

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.

  • Call [Adjust setEnabled:NO] to disable the SDK.
  • Call [Adjust setEnabled:YES] to enable the 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.

Send information in background

In SDK v4, you can call the [ADJConfig setSendInBackground] method with a true argument to enable the SDK to send information to Adjust while your app is running in the background.

In SDK v5, you need to call the [ADJConfig enableSendingInBackground] method with no arguments to enable the SDK to send information to Adjust while your app is running in the background.

Disable AdServices information reading

In SDK v4, you can call the [ADJConfig setAllowAdServicesInfoReading] method with a false argument to prevent the Adjust SDK from reading AdServices information.

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

Disable IDFA reading

In SDK v4, you can call the [ADJConfig setAllowIdfaReading] method with a false argument to prevent the Adjust SDK from reading the device’s IDFA.

In SDK v5, you need to call the disableIdfaReading method with no arguments to prevent the Adjust SDK from reading the device’s IDFA.

Enable cost data in attribution

In SDK v4, you can enable cost data in the device’s attribution information by calling the [ADJConfig setNeedsCost] method with a true argument.

In SDK v5, you need to call the [ADJConfig enableCostDataInAttribution] method with no arguments.

Enable LinkMe

In SDK v4, you can enable Adjust LinkMe by calling the [ADJConfig setLinkMeEnabled] method with a true argument.

In SDK v5, you need to call the [ADJConfig enableLinkMe] method with no arguments.

Only read device IDs once

In SDK v4, you can instruct the SDK to only read device identifiers one time upon startup by calling the [ADJConfig setReadDeviceInfoOnceEnabled] method with a true argument.

In SDK v5, you need to call the [ADJConfig enableDeviceIdsReadingOnce] method with no arguments.

Offline mode

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

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.

Push tokens

In SDK v4, you can set your push tokens using the [Adjust setDeviceToken] method.

This method has been renamed to [Adjust setPushToken] in SDK v5.

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.

In SDK v5, session parameters are renamed to global parameters. Instead of assigning the key and value as positional arguments, SDK v5 uses the forKey instance method to assign values to keys.

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.

In SDK v5, session partner parameters are renamed to global partner parameters. Instead of assigning the key and value as positional arguments, SDK v5 uses the forKey instance method to assign values to keys.

Send subscription information

In SDK v4, you can use the ADJSubscription class to create a payload of subscription information to send to Adjust.

This class has been renamed to ADJAppStoreSubscription in SDK v5 for clarity.

Event deduplication

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

In SDK v5, the feature is decoupled from transaction 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.

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 [Adjust adidWithCompletionHandler] getter method.

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

In SDK v5, this has been renamed to [Adjust processDeeplink] for clarity.

Deferred deep linking callback

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

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

COPPA compliance

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

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

Send ad revenue from a specific source

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

v4v5
ADJAdRevenueSourceAppLovinMAX"applovin_max_sdk"
ADJAdRevenueSourceAdMob"admob_sdk"
ADJAdRevenueSourceIronSource"ironsource_sdk"
ADJAdRevenueSourceAdMost"admost_sdk"
ADJAdRevenueSourceUnity"unity_sdk"
ADJAdRevenueSourceHeliumChartboost"helium_chartboost_sdk"
ADJAdRevenueSourceADX"adx_sdk"
ADJAdRevenueSourcePublisher"publisher_sdk"
ADJAdRevenueSourceTradplus"tradplus_sdk"
ADJAdRevenueSourceTopOn"topon_sdk"
ADJAdRevenueSourceMopub"mopub"

Set data residency and URL strategy

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

[adjustConfig setUrlStrategy:ADJDataResidencyEU];

In SDK v5, you need to pass your chosen domain or domains as an array. You can 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.
NSArray *domain = [];
[adjustConfig setUrlStrategy:domain useSubdomains:YES
isDataResidency:YES];

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

v4v5 - main and fallback domainv5 - use sub domainsv5 - is Data Residency
ADJDataResidencyEU"eu.adjust.com"truetrue
ADJDataResidencyTR"tr.adjust.com"truetrue
ADJDataResidencyUS"us.adjust.com"truetrue
ADJUrlStrategyChina"adjust.world", "adjust.com"truefalse
ADJUrlStrategyCn"adjust.cn", "adjust.com"truefalse
ADJUrlStrategyCnOnly"adjust.cn"truefalse
ADJUrlStrategyIndia"adjust.net.in", "adjust.com"truefalse

Examples

Disable SKAdNetwork communication

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

In SDK v5, this method has been renamed to [ADJConfig disableSkanAttribution] for clarity.

Update conversion values

In SDK v4, you can use the updateConversionValue method to send updated conversion values to Adjust. This method wraps Apple’s deprecated updateConversionValue method and has been removed in SDK v5.

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

  • conversionValue (NSInteger): The updated conversion value
  • coarseValue (NSString): The updated coarse conversion value
  • lockWindow (BOOL): Whether to send the postback before the conversion window ends

App Tracking Transparency authorization wrapper

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

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

Get device information

In SDK v4, all device information getter methods run synchronously. In SDK v5, these methods have been changed to run asynchronously. You can add a callback function to handle the information when the asynchronous process completes

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.

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.

This setting has been removed in SDK v5.

Set whether a device is known

In SDK v4, you can call the [AdjustConfig setIsDeviceKnown]; method to manually inform the SDK whether a device is known.

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 10 seconds of delay.

This setting 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.

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

Check for authorization status change

In SDK v4, you can use the [Adjust checkForNewAttStatus] method to prompt the SDK to read a user’s ATT status and forward the information to Adjust’s servers.

This method has been removed in SDK v5.

Listen for conversion value updates

In SDK v4, you can use the adjustConversionValueUpdated method to listen for SKAdNetwork updates.

In SDK v5, these two methods have been replaced by a single adjustSkanUpdatedWithConversionData method which returns an untyped dictionary. The following keys are currently supported:

  • conversion_value: The updated conversion value.
  • coarse_value: The updated coarse conversion value
  • lock_window: Whether to send the postback before the conversion window ends
  • error: Any error message returned by the update.

Set an app secret

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

This setting has been removed in SDK v5.

Removed plugins

Removed in v5

The following plugins have been removed in SDK v5:

  • Criteo
  • Trademob
  • Sociomantic