Adjust iOS Extension for Adobe Experience Platform SDK

This is the Adjust iOS Extension for Adobe Experience Platform SDK (AEP SDK). You can read more about Adjust™ at ADJUST Web Page.

Table of contents

Quick start

• Example app
• Add the Adjust Adobe Extension to your project
  • Cocoapods integration
  • Swift Package Manager integration
• Add iOS frameworks
• Integrate the Adobe Adjust Extension into your app
• Basic setup
• Attribution

Events tracking

• Track event
• Track revenue
• Callback parameters
• Partner parameters

Additional features

• Attribution callback
• Deferred deep linking callback
• Push token (uninstall tracking)
• Deep linking (reatribbution)

Quick start

Example application

There is an example application inside the AdjustAdobeExtensionApp directory. Please run pod install in this folder to build the example application dependencies and then open AdjustAdobeExtensionApp.xcworkspace to test the example application. Alternatively, you can open AdjustAdobeExtensionApp.xcodeproj and integrate an Adjust Adobe Extension using Swift Package Manager as explained here

Add the Adjust Adobe Extension to your project

Cocoapods integration

If you're using CocoaPods, add the following line to your Podfile:

pod 'AdjustAdobeExtension'

Swift Package Manager integration

If you are using Swift Package Manager, add Adjust Extension for Adobe Experience Platform SDK using the following Github repo link:

https://github.com/adjust/ios_adobe_extension.git

Add iOS frameworks

Adjust SDK is able to get additional information in case you link additional iOS frameworks to your app. Please, add following frameworks in case you want to enable Adjust SDK features based on their presence in your app and mark them as optional:

• AdSupport.framework - This framework is needed so that SDK can access to IDFA value and LAT information (prior to iOS 14) .
• AppTrackingTransparency.framework - This framework is needed in iOS 14 and later for SDK to be able to wrap user's tracking consent dialog and access to value of the user's consent to be tracked or not.
• AdServices.framework - For devices running iOS 14.3 or higher, this framework allows the SDK to automatically handle attribution for ASA campaigns. It is required when leveraging the Apple Ads Attribution API.
• StoreKit.framework - This framework is needed for access to SKAdNetwork framework and for Adjust SDK to handle communication with it automatically in iOS 14 or later.

Integrate the Adjust Adobe Extension into your app

Add the following import statement:

// Objective-C
#import <AdjustAdobeExtension/AdjustAdobeExtension.h>

// Swift
import AdjustAdobeExtension

Basic setup

First, configure Adjust SDK Extension in Adobe Experience Platform portal - provide an Adjust App Token (you can get it at Adjust dashboard) and choose whether to Share attribution data with Adobe using the toggle.

Then register the Adjust Adobe Extension like in the following code snippet.

• Replace {your_adobe_app_id} with your Unique identifier assigned to the app instance by Adobe Launch Portal.
• Set the {environment} to either sandbox or production mode:

ADJEnvironmentSandbox
ADJEnvironmentProduction

Important: Set the value to ADJEnvironmentSandbox if (and only if) you or someone else is testing your app. Make sure to set the environment to ADJEnvironmentProduction before you publish the app. Set it back to ADJEnvironmentSandbox if you start developing and testing it again.

We use this environment mode to distinguish between real traffic and test traffic from test devices. Keeping the environment updated according to your current status is very important!

Adjust SDK emits log messages according to Adobe AEPCore AEPLogLevel set by the user.

// Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [AEPMobileCore setLogLevel: AEPLogLevelTrace];
    const UIApplicationState appState = application.applicationState;

    // Adjust Adobe Extension configuration
    AdjustAdobeExtensionConfig *config = [AdjustAdobeExtensionConfig configWithEnvironment:{environment}];
    [AdjustAdobeExtension setConfiguration:config];

    // Adjust Adobe Extension registration
    [AEPMobileCore registerExtensions:@[AdjustAdobeExtension.class]
                           completion:^{
        [AEPMobileCore configureWithAppId: @"{your_adobe_app_id}"];

        if (appState != UIApplicationStateBackground) {
            // only start lifecycle if the application is not in the background
            [AEPMobileCore lifecycleStart:nil];
        }
    }];
    
    return YES;
}

// Swift
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    MobileCore.setLogLevel(LogLevel.trace)
    let appState = application.applicationState

    // Adjust Adobe Extension configuration
    if let config = AdjustAdobeExtensionConfig(environment: ADJEnvironmentSandbox) {
        AdjustAdobeExtension.setConfiguration(config)
    }

    // Adjust Adobe Extension registration
    MobileCore.registerExtensions([AdjustAdobeExtension.self]) {
        MobileCore.configureWith(appId: "{your_adobe_app_id}")
        if appState != .background {
            // Only start lifecycle if the application is not in the background
            MobileCore.lifecycleStart(additionalContextData: nil)
        }
    }
    return true
}

Attribution

The option to share attribution data with Adobe is in the Launch dashboard under the extensions configuration and it is on by default. Adjust tracks the action name Adjust Campaign Data Received with the following attribution information from Adjust:

• Adjust Network
• Adjust Campaign
• Adjust AdGroup
• Adjust Creative

Events tracking

Track event

You can use Adobe [AEPMobileCore trackAction:] API for event tracking. Suppose you want to track every tap on a button. To do so, you'll create a new event token in your Adjust dashboard. Let's say that the event token is abc123. In your button's press handling method, add the following lines to track the click:

// Objective-C
NSMutableDictionary * dataDict = [NSMutableDictionary dictionary];
[dataDict setValue:@"abc123" forKey:ADJAdobeAdjustEventToken];
[AEPMobileCore trackAction:ADJAdobeAdjustActionTrackEvent data:dataDict];

// Swift
var dataDict: Dictionary = [String : String](https://raw.github.com/adjust/ios_adobe_extension/main/)
dataDict[ADJAdobeAdjustEventToken] = "abc123"
MobileCore.track(action: ADJAdobeAdjustActionTrackEvent, data: dataDict)

Track revenue

If your users can generate revenue by tapping on advertisements or making in-app purchases, you can track those revenues too with events. Let's say a tap is worth one Euro cent. You can track the revenue event like this:

// Objective-C
NSMutableDictionary * dataDict = [NSMutableDictionary dictionary];
[dataDict setValue:@"abc123" forKey:ADJAdobeAdjustEventToken];
[dataDict setValue:@"0.01" forKey:ADJAdobeAdjustEventRevenue];
[dataDict setValue:@"EUR" forKey:ADJAdobeAdjustEventCurrency];
[AEPMobileCore trackAction:ADJAdobeAdjustActionTrackEvent data:dataDict];

// Swift
var dataDict: Dictionary = [String : String](https://raw.github.com/adjust/ios_adobe_extension/main/)
dataDict[ADJAdobeAdjustEventToken] = "abc123"
dataDict[ADJAdobeAdjustEventRevenue] = "0.01"
dataDict[ADJAdobeAdjustEventCurrency] = "EUR"
MobileCore.track(action: ADJAdobeAdjustActionTrackEvent, data: dataDict)

Callback parameters

You can register a callback URL for your events in your dashboard. We will send a GET request to that URL whenever the event is tracked. You can add callback parameters to that event by adding them as key value pair to the context data map before tracking it. We will then append these parameters to your callback URL.

For example, suppose you have registered the URL https://www.mydomain.com/callback then track an event like this:

// Objective-C
NSMutableDictionary * dataDict = [NSMutableDictionary dictionary];
[dataDict setValue:@"abc123" forKey:ADJAdobeAdjustEventToken];
[dataDict setValue:@"value1" forKey:[ADJAdobeAdjustEventCallbackParamPrefix stringByAppendingString:@"key1"]];
[dataDict setValue:@"value2" forKey:[ADJAdobeAdjustEventCallbackParamPrefix stringByAppendingString:@"key2"]];
[AEPMobileCore trackAction:ADJAdobeAdjustActionTrackEvent data:dataDict];

// Swift
var dataDict: Dictionary = [String : String](https://raw.github.com/adjust/ios_adobe_extension/main/)
dataDict[ADJAdobeAdjustEventToken] = "abc123"
dataDict[ADJAdobeAdjustEventCallbackParamPrefix.appending("key1")] = "value1"
dataDict[ADJAdobeAdjustEventCallbackParamPrefix.appending("key2")] = "value2"
MobileCore.track(action: ADJAdobeAdjustActionTrackEvent, data: dataDict)

In that case we would track the event and send a request to:

http://www.mydomain.com/callback?key1=value1&key2=value2

It should be mentioned that we support a variety of placeholders like {idfa} that can be used as parameter values. In the resulting callback this placeholder would be replaced with the ID for Advertisers of the current device. Also note that we don't store any of your custom parameters, but only append them to your callbacks, thus without a callback they will not be saved nor sent to you.

You can read more about using URL callbacks, including a full list of available values, in our callbacks guide.

Partner parameters

You can also add parameters to be transmitted to network partners, which have been activated in your Adjust dashboard.

You can add partner parameters to that event by adding them as key value pair to the context data map before tracking it.

// Objective-C
NSMutableDictionary * dataDict = [NSMutableDictionary dictionary];
[dataDict setValue:@"abc123" forKey:ADJAdobeAdjustEventToken];
[dataDict setValue:@"value1" forKey:[ADJAdobeAdjustEventPartnerParamPrefix stringByAppendingString:@"key1"]];
[dataDict setValue:@"value2" forKey:[ADJAdobeAdjustEventPartnerParamPrefix stringByAppendingString:@"key2"]];
[AEPMobileCore trackAction:ADJAdobeAdjustActionTrackEvent data:dataDict];

// Swift
var dataDict: Dictionary = [String : String](https://raw.github.com/adjust/ios_adobe_extension/main/)
dataDict[ADJAdobeAdjustEventToken] = "abc123"
dataDict[ADJAdobeAdjustEventPartnerParamPrefix.appending("key1")] = "value1"
dataDict[ADJAdobeAdjustEventPartnerParamPrefix.appending("key2")] = "value2"
MobileCore.track(action: ADJAdobeAdjustActionTrackEvent, data: dataDict)

You can read more about special partners and these integrations in our guide to special partners.

Additional features

Once you have integrated the Adjust iOS Extension for Adobe Experience Platform SDK into your project, you can take advantage of the following features:

Attribution callback

You can register a callback code block to be notified on tracker attribution changes. Due to the different sources we consider for attribution, we cannot provide this information synchronously.

Please see our attribution data policies for more information.

With the extension config instance, add the attribution callback code block to the Adjust extension before you register it (together with other Adobe extensions you possibly use) in Adobe Experience Platform Core SDK:

// Objective-C
AdjustAdobeExtensionConfig *config = [AdjustAdobeExtensionConfig configWithEnvironment:ADJEnvironmentSandbox];
[config setAttributionChangedBlock:^(ADJAttribution * _Nullable attribution) {
    // Attribution response received
}];
[AdjustAdobeExtension setConfiguration:config];

[AEPMobileCore registerExtensions:@[AdjustAdobeExtension.class]
                       completion:^{
    // Extensions registration completion handler implementation
    // ...
}];

// Swift
if let config = AdjustAdobeExtensionConfig(environment: ADJEnvironmentSandbox) {
    config.setAttributionChangedBlock({ attribution in
        // Attribution response received
    })
    AdjustAdobeExtension.setConfiguration(config)
}

MobileCore.registerExtensions([AdjustAdobeExtension.self]) {
    // Extensions registration completion handler implementation
    // ...
}

The code block is called after the SDK receives the final attribution data. Within the block body, you'll have an access to the attribution parameter.

Deferred deep linking callback

The Adjust SDK opens the deferred deep link by default. There is no extra configuration needed. But if you wish to control whether the Adjust SDK will open the deferred deep link or not, you can do it with an appropriate callback code block in the config object.

With the extension config instance, add the deferred deep linking callback block to the Adjust extension before you register it (together with other Adobe extensions you possibly use) in Adobe Experience Platform Core SDK:

// Objective-C
AdjustAdobeExtensionConfig *config = [AdjustAdobeExtensionConfig configWithEnvironment:ADJEnvironmentSandbox];
[config setDeeplinkResponseBlock:^BOOL(NSURL * _Nullable deeplink) {
    // Deep link response received
    // Apply your logic to determine whether the Adjust SDK should try to open the deep link
    return YES;
    // or
    // return NO;
}];
[AdjustAdobeExtension setConfiguration:config];

[AEPMobileCore registerExtensions:@[AdjustAdobeExtension.class]
                       completion:^{
    // Extension registration completion handler implementation
    // ...
}];

// Swift
if let config = AdjustAdobeExtensionConfig(environment: ADJEnvironmentSandbox) {
    config.setDeeplinkResponseBlock { deepLink in
        // Deep link response received
        // Apply your logic to determine whether the Adjust SDK should try to open the deep link
        return true;
        // or
        // return false;
    }
    AdjustAdobeExtension.setConfiguration(config)
}

MobileCore.registerExtensions([AdjustAdobeExtension.self]) {
    // Extension registration completion handler implementation
    // ...
}

After the Adjust SDK receives the deep link information from our backend, the SDK will deliver you its content via the callback block and expect the boolean return value from you. This return value represents your decision on whether the Adjust SDK should open the deep link or not.

Push token (uninstall tracking)

Push tokens are used for Audience Builder and client callbacks; they are also required for uninstall and reinstall tracking.

To send us the APNs push notification token, add the following call to Adjust once you have obtained your token (or whenever its value changes):

// Objective-C
NSMutableDictionary * dataDict = [NSMutableDictionary dictionary];
[dataDict setValue:@"{your_app_push_token}" forKey:ADJAdobeAdjustPushToken];
[AEPMobileCore trackAction:ADJAdobeAdjustActionSetPushToken data:dataDict];

// Swift
var dataDict = [String:String](https://raw.github.com/adjust/ios_adobe_extension/main/);
dataDict = [ADJAdobeAdjustPushToken:"{your_app_push_token}"]
MobileCore.track(action: ADJAdobeAdjustActionSetPushToken, data: dataDict)

Deep linking (reattribution)

Deep links are URLs that direct users to a specific page in your app without any additional navigation. You can use them throughout your marketing funnel to improve user acquisition, engagement, and retention. You can also re-engage your users via deep links which can potentially change their attribution. In order for Adjust to be able to properly reattribute your users via deep links, you need to make sure to pass the deep link to Adjust Adobe extension like desrcribed below (for scheme based deep links and universal links):

// Objective-C

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    return [AdjustAdobeExtension application:app openURL:url options:options];
}

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
    return [AdjustAdobeExtension application:application continueUserActivity:userActivity];
}

// Swift

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    return AdjustAdobeExtension.application(app, open: url, options: options)
}

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    return AdjustAdobeExtension.application(application, continue: userActivity)
}