iOS Extension for Adobe Experience v3 (#1201)

src/content/docs/en/sdk/adobe-extension/ios/attribution.mdoc

@@ -0,0 +1,197 @@
+---
+title: Set up an attribution callback
+description: Set up an attribution callback to respond to attribution changes.
+sidebar-position: 2
+---
+
+When Adjust receives install data from the Adjust iOS Extension for Adobe Experience SDK, the device is attributed to the source of the install. This attribution information can change if the user is retargeted or interacts with another campaign.
+
+You can configure a callback function to respond to attribution changes. When Adjust receives new attribution information, it sends the data asynchronously back to the device. The callback function receives the device's attribution data as an argument.
+
+Read Adjust's [attribution data policies](https://github.com/adjust/sdks/blob/master/doc/attribution-data.md) for more information about attribution data.
+
+## Reference {% #reference %}
+
+To set a callback function to listen for attribution changes, call the `setAttributionChangedBlock` method of your `AdjustAdobeExtensionConfig` instance with the following argument:
+
+{% deflist %}
+`attributionChangedBlock`: `OnAttributionChangedListener`
+
+: A function that returns `void` and receives device attribution information as a serialized attribution object.
+{% /deflist %}
+
+## Tutorial: Create an attribution callback {% #tutorial %}
+
+To configure an attribution callback, you need to create a function and assign it to your `AdjustAdobeExtensionConfig` instance. In this tutorial, you'll build on the App Delegate from the [integration guide](/en/sdk/adobe-extension/ios/integration) and create a completion function that outputs the user's attribution information to logs as a string. The final result looks like this:
+
+{% tabs %}
+{% tab title="Swift" sync="swift" %}
+```swift
+// AppDelegate.swift
+import UIKit
+import AEPCore
+import AEPServices
+import AdjustAdobeExtension
+
+@main
+class AppDelegate: UIResponder, UIApplicationDelegate {
+
+   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+      MobileCore.setLogLevel(LogLevel.trace)
+      let appState = application.applicationState
+
+      if let config = AdjustAdobeExtensionConfig(environment: ADJEnvironmentSandbox) {
+        config.setAttributionChangedBlock({ attribution in
+            print("Adjust Attribution Callback received: [\(attribution.description)]")
+        })
+         AdjustAdobeExtension.setConfiguration(config)
+      }
+
+      MobileCore.registerExtensions([AdjustAdobeExtension.self]) {
+         MobileCore.configureWith(appId: "{your_adobe_app_id}")
+         if appState != .background {
+               MobileCore.lifecycleStart(additionalContextData: nil)
+         }
+      }
+      return true
+   }
+
+    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+        if let deeplink = ADJDeeplink(deeplink: url) {
+            Adjust.processDeeplink(deeplink)
+        }
+        return true
+    }
+
+    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
+        if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
+            if let incomingUrl = userActivity.webpageUrl {
+                if let deeplink = ADJDeeplink(deeplink: incomingUrl) {
+                    Adjust.processDeeplink(deeplink)
+                }
+            }
+        }
+        return true
+    }
+}
+```
+{% /tab %}
+
+{% tab title="Objective-C" sync="objc" %}
+```objc
+// AppDelegate.m
+#import "AppDelegate.h"
+@import AEPCore;
+@import AEPServices;
+#import <AdjustAdobeExtension/AdjustAdobeExtension.h>
+
+@implementation AppDelegate
+
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+    [AEPMobileCore setLogLevel: AEPLogLevelTrace];
+    const UIApplicationState appState = application.applicationState;
+
+    // Adjust Adobe Extension configuration
+    AdjustAdobeExtensionConfig *config = [AdjustAdobeExtensionConfig configWithEnvironment:ADJEnvironmentSandbox];
+    [config setAttributionChangedBlock:^(ADJAttribution * _Nullable attribution) {
+        NSLog(@"Adjust Attribution Callback received:[%@]", attribution.description);
+    }];
+    [AdjustAdobeExtension setConfiguration:config];
+
+    [AEPMobileCore registerExtensions:@[AdjustAdobeExtension.class]
+                           completion:^{
+        [AEPMobileCore configureWithAppId: @"{your_adobe_app_id}"];
+
+        if (appState != UIApplicationStateBackground) {
+            [AEPMobileCore lifecycleStart:nil];
+        }
+    }];
+
+    return YES;
+}
+
+- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
+   [Adjust processDeeplink: [[ADJDeeplink alloc] initWithDeeplink:url]];
+   return YES;
+}
+
+- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
+   if ([[userActivity activityType] isEqualToString:NSUserActivityTypeBrowsingWeb]) {
+     [Adjust proceessDeeplink:[[ADJDeeplink alloc] initWithDeeplink:[userActivity webpageURL]]];
+   }
+   return YES;
+}
+@end
+```
+{% /tab %}
+{% /tabs %}
+
+Here's what you need to do:
+
+1. Inside your App Delegate, find your `AdjustAdobeExtensionConfig` instantiation. On the next line, call the `setAttributionChangedBlock` method with a function block as an argument. This function block receives the attribution information.
+
+   {% tabs %}
+   {% tab title="Swift" sync="swift" %}
+   {% codeblock
+      title="AppDelegate.swift"
+      highlight="{range: 2}"
+      startLineNumber=13 %}
+   ```swift
+   if let config = AdjustAdobeExtensionConfig(environment: ADJEnvironmentSandbox) {
+       config.setAttributionChangedBlock({ attribution in })
+       AdjustAdobeExtension.setConfiguration(config)
+   }
+   ```
+   {% /codeblock %}
+   {% /tab %}
+
+   {% tab title="Objective-C" sync="objc" %}
+   {% codeblock
+      title="AppDelegate.m"
+      highlight="{range: 2}"
+      startLineNumber=14 %}
+   ```objc
+   AdjustAdobeExtensionConfig *config = [AdjustAdobeExtensionConfig configWithEnvironment:ADJEnvironmentSandbox];
+   [config setAttributionChangedBlock:^(ADJAttribution * _Nullable attribution) {}];
+   [AdjustAdobeExtension setConfiguration:config];
+   ```
+   {% /codeblock %}
+   {% /tab %}
+   {% /tabs %}
+
+1. Inside the function block, output the attribution description to the Xcode logger.
+
+   {% tabs %}
+   {% tab title="Swift" sync="swift" %}
+   {% codeblock
+      title="AppDelegate.swift"
+      highlight="{range: 3}"
+      startLineNumber=13 %}
+   ```swift
+   if let config = AdjustAdobeExtensionConfig(environment: ADJEnvironmentSandbox) {
+       config.setAttributionChangedBlock({ attribution in
+            print("Adjust Attribution Callback received: [\(attribution.description)]")
+       })
+       AdjustAdobeExtension.setConfiguration(config)
+   }
+   ```
+   {% /codeblock %}
+   {% /tab %}
+
+   {% tab title="Objective-C" sync="objc" %}
+   {% codeblock
+      title="AppDelegate.m"
+      highlight="{range: 2}"
+      startLineNumber=14 %}
+   ```objc
+   AdjustAdobeExtensionConfig *config = [AdjustAdobeExtensionConfig configWithEnvironment:ADJEnvironmentSandbox];
+   [config setAttributionChangedBlock:^(ADJAttribution * _Nullable attribution) {
+        NSLog(@"Adjust Attribution Callback received:[%@]", attribution.description);
+   }];
+   [AdjustAdobeExtension setConfiguration:config];
+   ```
+   {% /codeblock %}
+   {% /tab %}
+   {% /tabs %}
+
+That's it! When a user's attribution information changes, this callback function writes out the updated attribution information to the system log.