API docs for setAdvertisingIdentifier (#72)

* Adds documentation for setAdvertisingIdentifier API * Fix typo - identifier
adobe · Jun 2, 2022 · 397ef78 · 397ef78
1 parent 3309c68
commit 397ef78
Showing 1 changed file with 147 additions and 0 deletions.
diff --git a/Documentation/api-reference.md b/Documentation/api-reference.md
@@ -0,0 +1,147 @@
+# Adobe Experience Platform Identity for Edge Network Extension - iOS
+
+## API reference
+
+| APIs                                           |
+| ---------------------------------------------- |
+| [setAdvertisingIdentifier](#setAdvertisingIdentifier)          |
+
+------
+
+### setAdvertisingIdentifier
+
+When this API is called with a valid advertising identifier, the Identity for Edge Network extension includes the advertising identifier in the XDM Identity Map using the _IDFA_ namespace. If the API is called with empty, nil or all-zeroes value, the IDFA is removed from the XDM Identity Map (if previously set).
+
+The IDFA is preserved between app upgrades, is saved and restored during the standard application backup process, and is removed at uninstall.
+
+> **Warning**
+> In order to enable the collection of current advertising tracking user's selection based on the provided advertising identifier, you need to install and register the [AEPEdgeConsent](https://aep-sdks.gitbook.io/docs/foundation-extensions/consent-for-edge-network) extension and update the [AEPEdge](https://aep-sdks.gitbook.io/docs/foundation-extensions/experience-platform-extension) dependency to minimum 1.4.1.
+
+> **Warning**
+> Starting iOS 14+, applications must use the [App Tracking Transparency](https://developer.apple.com/documentation/apptrackingtransparency) framework to request user authorization before using the Identifier for Advertising (IDFA). To access IDFA and handle it correctly in your mobile application, see the [Apple developer documentation about IDFA](https://developer.apple.com/documentation/adsupport/asidentifiermanager).
+
+#### Swift
+
+##### Syntax
+```swift
+@objc(setAdvertisingIdentifier:)
+public static func setAdvertisingIdentifier(_ identifier: String?)
+```
+- _identifier_ is a string that provides developers with a simple, standard system to continue to track the Ads through their apps.
+##### Example
+```swift
+import AdSupport
+import AppTrackingTransparency
+...
+
+func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+    ...
+    if #available(iOS 14, *) {
+       setAdvertisingIdentifierUsingTrackingManager()
+    } else {
+       // Fallback on earlier versions
+       setAdvertisingIdentifierUsingIdentifierManager()
+    }
+
+}
+
+func setAdvertisingIdentifierUsingIdentifierManager() {
+    var idfa:String = "";
+        if (ASIdentifierManager.shared().isAdvertisingTrackingEnabled) {
+            idfa = ASIdentifierManager.shared().advertisingIdentifier.uuidString;
+        } else {
+            Log.debug(label: "AppDelegateExample",
+                      "Advertising Tracking is disabled by the user, cannot process the advertising identifier.");
+        }
+        MobileCore.setAdvertisingIdentifier(idfa);
+}
+
+@available(iOS 14, *)
+func setAdvertisingIdentifierUsingTrackingManager() {
+    ATTrackingManager.requestTrackingAuthorization { (status) in
+        var idfa: String = "";
+
+        switch (status) {
+        case .authorized:
+            idfa = ASIdentifierManager.shared().advertisingIdentifier.uuidString
+        case .denied:
+            Log.debug(label: "AppDelegateExample",
+                      "Advertising Tracking is denied by the user, cannot process the advertising identifier.")
+        case .notDetermined:
+            Log.debug(label: "AppDelegateExample",
+                      "Advertising Tracking is not determined, cannot process the advertising identifier.")
+        case .restricted:
+            Log.debug(label: "AppDelegateExample",
+                      "Advertising Tracking is restricted by the user, cannot process the advertising identifier.")
+        }
+
+        MobileCore.setAdvertisingIdentifier(idfa)
+    }
+}
+```
+
+#### Objective-C
+
+##### Syntax
+```objectivec
++ (void) setAdvertisingIdentifier: (NSString * _Nullable identifier);
+```
+
+##### Example
+```objectivec
+#import <AdSupport/ASIdentifierManager.h>
+#import <AppTrackingTransparency/ATTrackingManager.h>
+...
+
+- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
+-   ...
+-   
+    if (@available(iOS 14, *)) {
+        [self setAdvertisingIdentifierUsingTrackingManager];
+    } else {
+        // fallback to earlier versions
+        [self setAdvertisingIdentifierUsingIdentifierManager];
+    }
+
+}
+
+- (void) setAdvertisingIdentifierUsingIdentifierManager {
+    // setup the advertising identifier
+    NSString *idfa = nil;
+    if ([[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled]) {
+        idfa = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
+    } else {
+        [AEPLog debugWithLabel:@"AppDelegateExample"
+                       message:@"Advertising Tracking is disabled by the user, cannot process the advertising identifier"];
+    }
+    [AEPMobileCore setAdvertisingIdentifier:idfa];
+
+}
+
+- (void) setAdvertisingIdentifierUsingTrackingManager API_AVAILABLE(ios(14)) {
+    [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:
+    ^(ATTrackingManagerAuthorizationStatus status){
+        NSString *idfa = nil;
+        switch(status) {
+            case ATTrackingManagerAuthorizationStatusAuthorized:
+                idfa = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
+                break;
+            case ATTrackingManagerAuthorizationStatusDenied:
+                [AEPLog debugWithLabel:@"AppDelegateExample"
+                               message:@"Advertising Tracking is denied by the user, cannot process the advertising identifier"];
+                break;
+            case ATTrackingManagerAuthorizationStatusNotDetermined:
+                [AEPLog debugWithLabel:@"AppDelegateExample"
+                               message:@"Advertising Tracking is not determined, cannot process the advertising identifier"];
+                break;
+            case ATTrackingManagerAuthorizationStatusRestricted:
+                [AEPLog debugWithLabel:@"AppDelegateExample"
+                               message:@"Advertising Tracking is restricted by the user, cannot process the advertising identifier"];
+                break;
+        }
+
+        [AEPMobileCore setAdvertisingIdentifier:idfa];
+    }];
+}
+```
+------