Incorporated the review comment part 1

adobe · Jan 27, 2023 · 1ecf12d · 1ecf12d
1 parent 39c921e
commit 1ecf12d
Show file tree

Hide file tree

Showing 9 changed files with 223 additions and 101 deletions.
diff --git a/Documentation/README.md b/Documentation/README.md
@@ -3,5 +3,6 @@
 ## Contents
 - [Getting started](getting-started.md)
 - [API reference](api-reference.md)
-- [Getting started test app](getting-started-test-app.md)
-- [Troubleshooting guides](troubleshooting-guide.md)
+- [Getting started with the test app](getting-started-test-app.md)
+- [Troubleshooting guide](troubleshooting-guide.md)
+- [Frequently asked questions](./frequently-asked-questions.md)
diff --git a/Documentation/advertising-identifier.md b/Documentation/advertising-identifier.md
diff --git a/Documentation/api-reference.md b/Documentation/api-reference.md
@@ -138,7 +138,7 @@ Registers the Identity for Edge Network extension with the Mobile Core extension
 > Deprecated as of 2.0.0. Use the [MobileCore.registerExtensions API](https://github.com/adobe/aepsdk-core-android) instead.
 
 > **Note**
-> If your use-case covers both Edge Network and Adobe Experience Cloud Solutions extensions, you need to register Identity for Edge Network and Identity for Experience Cloud Identity Service from Mobile Core extensions. For more details, see the [frequently asked questions](https://developer.adobe.com/client-sdks/documentation/identity-for-edge-network/faq).
+> If your use-case covers both Edge Network and Adobe Experience Cloud Solutions extensions, you need to register Identity for Edge Network and Identity for Experience Cloud Identity Service from Mobile Core extensions. For more details, see the [frequently asked questions](./frequently-asked-questions.md).
 
 #### Java
 
@@ -200,7 +200,7 @@ This API is not recommended for:
 * Removing a previously synced advertising identifier after the advertising tracking settings were changed by the user; use the [`setAdvertisingIdentifier`](#setadvertisingidentifier) API instead.
 
 > **Warning**
->The Identity for Edge Network extension does not read the Mobile SDK's privacy status, and therefore setting the SDK's privacy status to opt-out will not automatically clear the identities from the Identity for Edge Network extension. See [`MobileCore.resetIdentities`](https://github.com/adobe/aepsdk-core-android/blob/staging/Documentation/Usage/MobileCore.md) for more details.
+>The Identity for Edge Network extension does not read the Mobile SDK's privacy status, and therefore setting the SDK's privacy status to opt-out will not automatically clear the identities from the Identity for Edge Network extension. See [`MobileCore.resetIdentities`](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/Usage/MobileCore.md) for more details.
 
 ------
 
@@ -380,7 +380,7 @@ Defines a map containing a set of end user identities, keyed on either namespace
 
 The format of the IdentityMap class is defined by the [XDM Identity Map Schema](https://github.com/adobe/xdm/blob/master/docs/reference/mixins/shared/identitymap.schema.md).
 
-For more information, please read an overview of the [AEP Identity Service](https://experienceleague.adobe.com/docs/experience-platform/identity/home.html).
+For more information, please read an overview of the [Adobe Experience Platform Identity Service](https://experienceleague.adobe.com/docs/experience-platform/identity/home.html).
 
 ```text
 "identityMap" : {

diff --git a/Documentation/frequently-asked-questions.md b/Documentation/frequently-asked-questions.md
@@ -0,0 +1,121 @@
+## Frequently asked questions
+
+### Q: I am using AEP Edge and Adobe Solutions extensions, which Identity Extension should I install and register?
+
+A: Both
+
+When using both Adobe Experience Platform Edge and Adobe Solutions extensions, both Identity for Edge Network and Identity for Experience Cloud ID Service extensions can be registered with the Mobile SDK at the same time.
+
+**Note** 
+The following instructions are for configuring an application using both Edge Network and Adobe Solutions mobile extensions. If an application will include only Adobe Experience Platform Edge extensions, follow the instructions here.
+
+Download and import the Identity and Identity for Edge Network extensions
+#### Java
+
+1. Add the Mobile Core and Edge extensions to your project using the app's Gradle file.
+
+   ```java
+    implementation 'com.adobe.marketing.mobile:core:2.+'
+    implementation 'com.adobe.marketing.mobile:identity:2.+'
+    implementation 'com.adobe.marketing.mobile:edge:2.+'
+    implementation 'com.adobe.marketing.mobile:edgeidentity:2.+'
+   ```
+> **Warning**
+> Using dynamic dependency versions is not recommended for production apps. Refer to this [page](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/GradleDependencies.md) for managing gradle dependencies.
+
+2. Import the Mobile Core and Edge extensions in your application class.
+
+    ```java
+    import com.adobe.marketing.mobile.*;
+    ```
+
+Register the Identity and Identity for Edge Network extensions with Mobile Core
+
+### Q: Will an existing Experience Cloud ID (ECID) migrate to the Identity for Edge Network extension?
+
+A: Yes.
+
+If the application previously installed the Identity for Experience Cloud ID Service extension and upgrades to the Identity for Edge Network extension, the existing ECID value is migrated to the Identity for Edge Network extension on first launch of the application.
+
+Note, however, if the Mobile SDK's privacy status was set to `optedOut` at the time the application is upgraded, the Identity for Experience Cloud ID Service extension will not have an ECID, as it was cleared. In this case, the Identity for Edge Network extension will generate a new ECID.
+
+### Q: What is the Experience Cloud ID (ECID) used by the SDK when using both AEP Edge extensions and Adobe Solutions extensions?
+
+A: The Identity for Edge Network extension and the Identity for Experience Cloud ID Service extension each manage their own ECID. However, the two ECIDs are synced as part of the XDM IdentityMap.
+
+At first launch of the application after upgrading to the Identity for Edge Network extension, the existing ECID from the Identity for Experience Cloud ID Service extension is migrated to the Identity for Edge Network extension. In this case both extensions will have the same ECID value.
+
+The [resetIdentities](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/Usage/MobileCore.md) API regenerates a new ECID used by the Identity for Edge Network extension. This API call does not change the ECID used by the Identity for Experience Cloud ID Service extension. After calling this API, the ECID used by each identity extension will be different.
+
+Changing the privacy status to optedOut will clear the ECID value used by the Identity for Experience Cloud ID Service extension. Changing the privacy status back to optedIn will generate a new ECID used by the Identity for Experience Cloud ID Service extension. Privacy status changes do not change the ECID used by the Identity for Edge Network extension. Changing the privacy status will cause the ECID used by each identity extension to be different.
+
+When each identity extension has a different ECID, the Identity for Edge Network extension will include the Identity for Experience Cloud ID Service ECID in its [IdentityMap](api-reference.md), and so the Adobe Experience Platform Identity Service will link the the two ECIDs in the customer's Identity Graph.
+
+The following example shows an IdentityMap containing the ECIDs from both Identity for Edge Network extension and Identity for Experience Cloud ID Service extension. The ECID from the Identity for Edge Network extension is always listed first in the list of ECIDs.
+
+```json
+  "identityMap" : {
+      "ECID" : [
+        {
+          "id" : "73586628797489658169123381027155647197",
+          "authenticatedState" : "ambiguous",
+          "primary" : false
+        },
+        {
+          "id" : "81117527655405132265917409409236407340",
+          "authenticatedState" : "ambiguous",
+          "primary" : false
+        }
+      ]
+    }
+```
+### Q: I set privacy status to opted out, why do I see an ECID value when calling Identity.getExperienceCloudId()?
+
+A: The Identity for Edge Network extension does not change its ECID based on privacy status changes.
+
+**Note** 
+The Identity for Edge Network extension and the Identity for Experience Cloud ID Service extension each manage their own ECID value and are generated independently of each other.
+
+The Identity for Edge Network extension does not clear its stored identities or regenerate the ECID due to privacy status changes. Instead, use the [MobileCore.resetIdentities](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/Usage/MobileCore.md) API. Note this API does not clear the ECID but instead generates a new ECID.
+
+Each identity extension has its own API to retrieve their respective ECIDs as well. Use [Identity.getExperienceCloudId](https://github.com/adobe/aepsdk-edge-android/blob/main/Documentation/api-reference.md) to get the Identity for Edge Network extension's ECID, and [Identity.getExperienceCloudId](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/Usage/Identity.md) to get the Identity for Experience Cloud ID Service extension's ECID.
+
+### Q: How can I get all the identifiers used by the SDK when using both AEP Edge extensions and Adobe Solutions extensions?
+
+A: Use both `getSdkIdentities` and `getIdentities`.
+To get the identifiers used by the Adobe Solutions extensions, call [getSdkIdentities](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/Usage/MobileCore.md).
+To get the identifiers used by the AEP Edge extensions, call [getIdentities](api-reference.md).
+
+### Q: How can I clear all the identifiers from the SDK when using both AEP Edge extensions and Adobe Solutions extensions?
+
+A: Set privacy status to `optedOut` and call `resetIdentities`.
+
+To clear the identifiers used by the Adobe Solutions extensions, call [setPrivacyStatus](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/Usage/MobileCore.md) and set the privacy status to optedOut.
+
+To clear the identifiers used by the AEP Edge extensions, call [resetIdentities](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/Usage/MobileCore.md)
+
+### Q: What steps are needed to generate a new Experience Cloud ID (ECID) for a user when using both AEP Edge extensions and Adobe Solutions extensions?
+
+A: Both identity extensions' ECID must be regenerated in sequence to avoid linking the old and new ECIDs in Adobe Experience Platform.
+
+When using Real-time Customer Profile and Identity Service, the ECIDs from both identity extensions are linked together in the customer's Identity Graph. Care must be taken when regenerating new ECIDs such that the old and new ECIDs are not linked within the same Identity Graph.
+
+Perform the following API calls to regenerate the ECIDs in sequence:
+1. Set [privacy status](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/Usage/MobileCore.md) to `optedOut` to clear the ECID from the AEP Identity direct service extension.
+2. Call [resetIdentities](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/Usage/MobileCore.md) to regenerate a new ECID in the Identity for Edge Network extension.
+3. Call [getExperienceCloudId](api-reference.md) on the Identity for Edge Network extension. This ensures the new ECID is generated before continuing.
+4. Set privacy status `to optedIn` to generate a new ECID in the AEP Identity direct service extension.
+
+After completing the above steps, each identity extension will have its own, different, ECID. The new ECIDs will get linked under a new Identity Graph for the customer.
+
+```java
+MobileCore.setPrivacyStatus(MobilePrivacyStatus.OPT_OUT);
+MobileCore.resetIdentities();
+com.adobe.marketing.mobile.edge.identity.Identity.getExperienceCloudId(new AdobeCallback<String>() {
+    @Override
+    public void call(String s) {
+        // ignore
+    }
+});
+MobileCore.setPrivacyStatus(MobilePrivacyStatus.OPT_IN);
+```