Merge pull request adobe#30 from adobe/documentation

Assurance 3.x - Installation and Migration Docs

Documentation/MIGRATION.md

@@ -0,0 +1,102 @@
+# Migration from AEPAssurance 1.x to AEPAssurance 3.x
+
+## Who should migrate to AEPAssurance 3.x
+
+---
+
+If you are in the process of migration or already migrated to AEPCore from ACPCore then you must use AEPAssurance 3.x.x in your application. For more information see [Migrate to Swift SDK](https://aep-sdks.gitbook.io/docs/resources/migrate-to-swift).
+
+The following table shows the SDK Core's compatibility with AEPAssurance:
+
+| SDK Core | Assurance Version | Pod Installation | Manual Install |
+| ----------- | -------- | ---------- | ------- |
+| ACPCore | AEPAssurance 1.x | pod 'AEPAssurance', '~> 1.0' | [Available Here](https://github.com/Adobe-Marketing-Cloud/acp-sdks/tree/master/iOS/AEPAssurance)|
+| AEPCore | AEPAssurance 3.x | pod 'AEPAssurance', '~> 3.0' | [Follow this command](../#binaries) |
+
+---
+
+## Primary class name
+
+---
+
+The class name containing public APIs is different depending on which SDK and language combination being used.
+
+| SDK Version | Language | Class Name | Example |
+| ----------- | -------- | ---------- | ------- |
+| AEPAssurance 1.x | Objective-C | `AEPAssurance` | `[AEPAssurance startSession:url];`|
+| AEPAssurance 1.x | Swift | `AEPAssurance` | `AEPAssurance.startSession(url)`|
+| AEPAssurance 3.x | Objective-C | `AEPMobileAssurance` | `[AEPMobileAssurance startSessionWithUrl:url];` |
+| AEPAssurance 3.x | Swift | `Assurance` | `Assurance.startSession(url)` |
+
+## Public APIs
+
+---
+
+### extensionVersion
+
+**AEPAssurance 1.x (Objective-C)**
+
+```objc
++ (nonnull NSString*) extensionVersion;
+```
+
+**AEPAssurance 3.x  (Objective-C)**
+
+```objc
++ (nonnull NSString*) extensionVersion;
+```
+
+**AEPAssurance 3.x (Swift)**
+
+```swift
+static var extensionVersion: String
+```
+
+---
+
+### registerExtension
+
+**AEPAssurance 1.x (Objective-C)**
+
+```objc
++ (bool) registerExtension;
+```
+
+**AEPAssurance 3.x  (Objective-C)**
+
+Not Available. Please see the [migration steps documentation (Objective C)](MIGRATIONObjC.md) to learn how to register AEPAssurance with AEPCore.
+
+**AEPAssurance 3.x (Swift)**
+
+Not Available. Please see the [migration steps documentation (Swift)](MIGRATIONSWIFT.md) to learn how to register AEPAssurance with AEPCore.
+
+---
+
+### startSession
+
+**AEPAssurance 1.x (Objective-C)**
+
+```objc
++ (void) startSession: (NSURL* _Nonnull) url;
+```
+
+**AEPAssurance 3.x  (Objective-C)**
+
+```objc
++ (void) startSessionWithUrl:(NSURL* _Nonnull) url;
+```
+
+**AEPAssurance 3.x (Swift)**
+
+```swift
+static func startSession(url: URL?)
+```
+
+
+
+## Migration Steps
+
+Click a link below for step by step migration guide to AEPAssurance 3.x.
+
+- [Migration steps for Swift Application](MIGRATIONSWIFT.md)
+- [Migration steps for ObjectiveC Application](MIGRATIONObjC.md)

Documentation/MIGRATIONObjC.md

@@ -0,0 +1,60 @@
+# AEPAssurance 3.x migration steps for Objective-C Apps
+
+##  1.a. Update Podfile
+
+Open the `Podfile` of your application and make the following changes.
+
+```diff
+- pod 'ACPCore'
+- pod `AEPAssurance`, '~> 1.0'
+
++ pod 'AEPCore'
++ pod `AEPAssurance`, '~> 3.0'
+```
+
+Then run `pod install` and build the project, now the project will be using the latest AEPCore and AEPAssurance SDK.
+
+##  1.b. Manual Install
+Please ignore this section if you are using CocoaPods or Swift Package Manager to manage dependencies.
+- Remove the existing `AEPAssurance.xcframework` from your project.
+- Create and Install the latest `AEPAssurance.xcframework` by following [this command](../#binaries).
+
+## 2. Registration of Assurance Extension
+
+The following changes should be made in your AppDelegate's `didFinishLaunchingWithOptions` method.
+
+```diff
+- [AEPAssurance registerExtension];
+- [ACPCore start:^{
+-       [ACPCore configureWithAppId:@"Your_AppID"];
+-  }];
++
++ @import AEPAssurance;
++ @import AEPCore;
++ ...
++
++  NSArray* extensionsToRegister = @[AEPMobileAssurance.class];
++  [AEPMobileCore registerExtensions:extensionsToRegister completion:^{
++     [AEPMobileCore configureWithAppId: @"Your_AppID"];
++  }];
++
+```
+
+## 3. Migrate startSession API
+
+Make the following change to all occurrences of Assurance's startSession API call in your application. Here is an example :
+```diff
+ - (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
+      NSURL *url = URLContexts.allObjects.firstObject.URL;
+      // validate the url
+-    [AEPAssurance startSession:url];
++    [AEPMobileAssurance startSessionWithUrl:url];
+}
+```
+
+## 4. Extension Version API
+ The API to retrieve the version of Assurance extension should be changed as below.
+ ```diff
+- NSString* version = [AEPAssurance extensionVersion];
++ NSString* version = AEPMobileAssurance.extensionVersion;
+ ```

Documentation/MIGRATIONSWIFT.md

@@ -0,0 +1,60 @@
+# AEPAssurance 3.x migration steps for Swift Apps
+
+##  1.a. Update Podfile
+Open the `Podfile` of your application and make the following changes.
+
+```diff
+- pod 'ACPCore'
+- pod `AEPAssurance`, '~> 1.0'
+
++ pod 'AEPCore'
++ pod `AEPAssurance`, '~> 3.0'
+```
+
+Then run `pod install` and build the project, now the project will be using the latest AEPCore and AEPAssurance SDK.
+
+##  1.b. Manual Install
+Please ignore this section if you are using CocoaPods or Swift Package Manager to manage dependencies.
+- Remove the existing `AEPAssurance.xcframework` from your project.
+- Create and Install the latest `AEPAssurance.xcframework` by following [this command](../#binaries).
+
+## 2. Registration of Assurance Extension
+
+Make the following changes in your AppDelegate's `didFinishLaunchingWithOptions` method. If you are working with an Objective-C application, follow this [document](../MIGRATIONObjC.md).
+
+```diff
+- AEPAssurance.registerExtension()
+- ACPCore.start {
+-    ACPCore.configure(withAppId: "Your_AppID")
+- }
++
++ import AEPAssurance
++ import AEPCore
++ ...
++
++  let extensions =  [
++                      Assurance.self     /// Also include the other installed extensions to this array
++                    ]
++  MobileCore.registerExtensions(extensions, {
++    MobileCore.configureWith(appId: "your_AppID")
++ })
++
+```
+
+## 3. Migrate startSession API
+
+Make the following change to all occurrences of Assurance's startSession API call in your application. Here is an example :
+```diff
+func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {  
+     guard let urlContexts = URLContexts.first else { return }
+-    AEPAssurance.startSession(urlContexts.url)
++    Assurance.startSession(url: urlContexts.url)
+}
+```
+
+## 4. Extension Version API
+ The API to retrieve the version of Assurance extension should be changed as below.
+ ```diff
+- let version = AEPAssurance.extensionVersion()
++ let version = Assurance.extensionVersion
+ ```

Documentation/README.md

@@ -0,0 +1,8 @@
+# AEPAssurance Documentation
+
+Click a link below to learn more.
+
+- [Usage](USAGE.md)
+- [Migration from AEPAssurance(1.x)](MIGRATION.md)
+- [Migration from AEPAssurance(1.x) (For ObjC Apps)](MIGRATIONObjC.md)
+

Documentation/USAGE.md

@@ -0,0 +1,101 @@
+# AEPAssurance Public APIs
+
+This document contains usage information for the public functions and classes in `AEPAssurance`.
+
+---
+
+## extensionVersion
+
+Returns the current version of the AEP Assurance extension.
+
+##### Swift
+
+**Signature**
+```swift
+static var extensionVersion: String
+```
+
+**Example Usage**
+```swift
+let assuranceVersion = Assurance.extensionVersion
+```
+
+##### Objective-C
+
+**Signature**
+```objc
++ (nonnull NSString*) extensionVersion;
+```
+
+**Example Usage**
+```objc
+NSString *assuranceVersion = AEPMobileAssurance.extensionVersion;
+```
+
+---
+
+## startSession
+
+Call the startSession API with a assurance session deeplink URL to connect to a session. When called, SDK displays a PIN authentication overlay to begin a session connection.
+
+
+##### Swift
+
+**Signature**
+```swift
+static func startSession(url: URL?)
+```
+
+**Example Usage**
+```swift
+func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool {
+    Assurance.startSession(url: url)
+    return true
+}
+```
+
+For SceneDelegate based applications
+
+```swift
+func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
+    if let deepLinkURL = connectionOptions.urlContexts.first?.url {
+        Assurance.startSession(url: deepLinkURL)
+    }
+}
+
+func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
+    // This method is called when the app in background is opened with a deep link.
+    // https://developer.apple.com/documentation/uikit/uiscenedelegate/3238059-scene
+    if let deepLinkURL = URLContexts.first?.url {
+        Assurance.startSession(url: deepLinkURL)
+    }
+}
+```
+
+##### Objective-C
+
+**Signature**
+```objc
++ (void) startSessionWithUrl: (NSURL* _Nonnull) url;
+```
+
+**Example Usage**
+```objc
+- (BOOL)application:(UIApplication *)app openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
+    [AEPMobileAssurance startSessionWithUrl:url];
+    return true;
+}
+```
+
+For SceneDelegate based applications
+
+```objc
+- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
+    NSURL *deepLinkURL = connectionOptions.URLContexts.allObjects.firstObject.URL;
+    [AEPMobileAssurance startSessionWithUrl:deepLinkURL];
+}
+
+- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
+    [AEPMobileAssurance startSessionWithUrl:URLContexts.allObjects.firstObject.URL];
+}
+```