Update doc for v.2.0.0 and use Core MapUtils #89

cacheung · 2023-01-20T22:43:54Z

Rearrange the documentation folder files based on the documentation discussion in the meeting.
Update sample code in doc.
Use Core MapUtils for isNullOrEmpty in few places.

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

I have signed the Adobe Open Source CLA.
My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have added tests to cover my changes.
All new and existing tests passed.

Update implementation from 2+ to 2.0.0 Update sample code in doc.

codecov · 2023-01-20T22:52:06Z

Codecov Report

Merging #89 (7354c19) into dev-v2.0.0 (e12492d) will decrease coverage by 0.01%.
The diff coverage is 100.00%.

@@              Coverage Diff               @@
##           dev-v2.0.0      #89      +/-   ##
==============================================
- Coverage       93.37%   93.36%   -0.01%     
==============================================
  Files              12       12              
  Lines             679      678       -1     
  Branches          103      103              
==============================================
- Hits              634      633       -1     
  Misses             16       16              
  Partials           29       29

Flag	Coverage Δ
functional-tests	`67.55% <50.00%> (-0.93%)`	⬇️
unit-tests	`93.07% <100.00%> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
...om/adobe/marketing/mobile/edge/identity/Utils.java	`100.00% <ø> (ø)`
...be/marketing/mobile/edge/identity/IdentityMap.java	`97.54% <100.00%> (ø)`
.../marketing/mobile/edge/identity/IdentityState.java	`95.83% <100.00%> (ø)`

Update Readme

Use Core MapUtils for isNullOrEmpty

emdobrin · 2023-01-24T19:38:48Z

Documentation/api-reference.md

@@ -134,6 +134,9 @@ Identity.getUrlVariables(new AdobeCallback<String>() {

 Registers the Identity for Edge Network extension with the Mobile Core extension.

+> **Warning**
+> Deprecated as of 2.0.0. Use [MobileCore.registerExtensions API](https://github.com/adobe/aepsdk-core-android/blob/main/docs/Usage/MobileCore.md#registering-extensions-and-starting-the-sdk) instead.


let's remove this link to mobile core

Documentation/getting-started.md

Documentation/api-reference.md

Updatet documentation, make toc for Readme.md. Move advertising-identifier content to its own file.

Update getting-started.md

Remove setLogLevel in the sample code

Update Documentation

Fix typo in a link

cacheung · 2023-01-26T19:25:41Z

Documentation/getting-started.md

+3. In your mobile property, select **Extensions** tab.
+4. On the **Catalog** tab, locate or search for the **Identity** extension, and select **Install**.
+5. There are no configuration settings for **Identity**.
+6. Follow the [publishing process](https://developer.adobe.com/client-sdks/documentation/getting-started/create-a-mobile-property) to update SDK configuration.


Should we include this Adobe.io link?
In the developer.com, it just has "Follow the publishing process ...." with no link.

maybe remove it here too

Update descriptions for related projects

emdobrin · 2023-01-26T22:53:58Z

README.md

@@ -3,82 +3,28 @@

 ## About this project

-The Adobe Experience Platform Edge Identity is a mobile extension for the [Adobe Experience Platform SDK](https://github.com/Adobe-Marketing-Cloud/acp-sdks) and requires the `MobileCore` extension. This extension enables handling of user identity data from a mobile app when using the AEP Mobile SDK and the Edge Network extension.
+The Adobe Experience Platform Edge Identity is a mobile extension for the [Adobe Experience Platform SDK](https://developer.adobe.com/client-sdks/documentation) and requires the `MobileCore` extension. This extension enables handling of user identity data from a mobile app when using the AEP Mobile SDK and the Edge Network extension.


The Adobe Experience Platform Identity for Edge Network mobile extension enables identity management from your mobile app when using the Adobe Experience Platform Mobile SDK and the Edge Network extension.

emdobrin · 2023-01-26T23:00:57Z

README.md

@@ -93,7 +39,11 @@ make init

 | Project                                                      | Description                                                  |
 | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| [AEP SDK Sample App for Android](https://github.com/adobe/aepsdk-sample-app-android) | Contains Android sample app for the AEP SDK.                 |
+| [AEP Core Extensions](https://github.com/adobe/aepsdk-core-android) | The AEPCore represents the foundation of the Adobe Experience Platform SDK.                |


| Core extensions | The Mobile Core represents the foundation of the Adobe Experience Platform mobile SDK. |

| Edge Network extension | The Edge Network extension allows you to send data to the Adobe Edge Network from a mobile application. |

| Consent for Edge Network extension | The Consent ...

| Assurance extension (link should be https://github.com/adobe/aepsdk-assurance-android) | The Assurance extension enables validation workflows for your SDK implementation.

| AEP SDK sample app for Android | Contains the Android sample app for the AEP SDKs.

I like the removal of the AEP acronym from the extension names on the project column side; could we extend that to the sample app row as well? Maybe something like:
Adobe Experience Platform sample app for Android
or
Adobe Experience Platform Android sample app

And the description to something like (i think we can use Experience Platform here instead of Adobe Experience Platform since it was already mentioned prominently in the Project column side):
Contains a fully implemented Android sample app using the Experience Platform SDKs.

emdobrin · 2023-01-26T23:01:55Z

Documentation/troubleshooting-guide.md

@@ -0,0 +1,29 @@
+## Troubleshooting Guides
+
+### M1 issue


Development on M1 Macs

Documentation/README.md

Documentation/getting-started-test-app.md

emdobrin · 2023-01-26T23:12:59Z

Documentation/getting-started-test-app.md

+Configure a new Assurance session by setting the Base URL to `testapp://main` and launch Assurance in the demo app by running the following command in your terminal:
+
+```bash
+$ adb shell am start -W -a  android.intent.action.VIEW -d "testapp://main?adb_validation_sessionid=ADD_YOUR_SESSION_ID_HERE" com.adobe.marketing.mobile.testapp


looks like this test app does not have the scheme configured for deeplinks. e.g.:
https://github.com/adobe/aepsdk-edge-android/blob/dev-v2.0.0/code/app/src/main/AndroidManifest.xml#L40-L43

https://github.com/adobe/aepsdk-edge-android/blob/dev-v2.0.0/code/app/src/main/java/com/adobe/marketing/tester/MainActivity.java#L121-L128

Documentation/getting-started-test-app.md

Documentation/getting-started.md

emdobrin · 2023-01-26T23:22:32Z

Documentation/getting-started.md

+3. In your mobile property, select **Extensions** tab.
+4. On the **Catalog** tab, locate or search for the **Identity** extension, and select **Install**.
+5. There are no configuration settings for **Identity**.
+6. Follow the [publishing process](https://developer.adobe.com/client-sdks/documentation/getting-started/create-a-mobile-property) to update SDK configuration.


maybe remove it here too

addb · 2023-01-26T23:48:25Z

Documentation/api-reference.md


 > **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://aep-sdks.gitbook.io/docs/foundation-extensions/mobile-core/mobile-core-api-reference#resetidentities) 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/staging/Documentation/Usage/MobileCore.md) for more details.


Let's avoid full path and just provide the core repo url.

@emdobrin @kevinlind @cacheung @timkim I see URLs to faqs and core repos here, do you think we could have section in getting started and reference that section wherever we need links in our doc? Or should we move FAQs to repo docs as well?

Section with links

Privacy/GDPR

Core API Ref

EdgeIdentity FAQ

Personally, I feel a bit conflicted with only having a main table/area for all links and removing them from the text completely; on one hand, yes the burden of maintaining these links that have potential to break is reduced for us, but on the other hand, effectively the burden is transferred to users in the form of having to find that information themselves

I feel that it really reduces the 3rd party developer experience by making relevant and specific information much harder to find (for example, when mentioning an API, being unable to link to that specific API with the header deep link and having to dig through the entire core repo docs). I think this effect is exacerbated by the fact that new users who would most benefit from having this easily accessible information are most burdened because they have the least amount of understanding to know where to find information and how our extensions work.

For example, on this firebase tutorial page: https://firebase.google.com/docs/ios/installation-methods#cocoapods
under step 2, they have a link to supported products. Imagine if they threw us to the very top of the page with no context, it would be very confusing to understand that they meant the Available libraries section

Similarly, imagine if Javadocs or Apple Swift/ObjC docs didnt take you to the specific API within a huge class page, but always placed you at the top? This kind of degraded developer experience isnt a deal breaker but it adds to the overall experience and perception of the product

Sorry for the rant, and this is definitely not to target you but I think we could benefit from a different approach, maybe even creating a script/github action that is able to look through a repo's static links and replace them with the new value?

I vote for keeping
https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/Usage/MobileCore.md at least for [MobileCore.resetIdentities]. (I changed the branch to main now) If just going to the repo, user isn't going to find it right away. We can avoid the deep link though. This page isn't that big, user can scroll down and find it.

We can find a balance depends on the situation. For Privacy and GDPR, I don't think we should move it to this repo, so it is better to point it to the developer.com.

EdgeIdentity FAQ, good point, we should move it to this repo as well. I will copy that over.

I don't think we need to have a table with links.

I am of the believer of having links to each and every section. I was just trying to see if we have a way to simplify it as per discussion in the team guild meeting. But yes I do believe we should have all the API reference directly without any redirects. And even if it is a task to update, developers should be able to move across documentation without any friction.

timkimadobe

Thanks Calise! Made some suggestions for text changes, broadly covering:

Replacement of the AEP acronym with "Adobe Experience Platform" or "Experience Platform" (when proper context is available)
Aligning getting started java and kotlin examples
Fleshing out the getting started guide, particularly around setting up the mobile property for the test app
Misc. styling and other changes

Please let me know what you think!

timkimadobe · 2023-01-26T23:57:47Z

Documentation/getting-started.md


 ## Add the AEP Identity extension to your app

 ### Download and import the Identity extension

-> :information_source: The following instructions are for configuring an application using Adobe Experience Platform Edge mobile extensions. If an application will include both Edge Network and Adobe Solution extensions, both the Identity for Edge Network and Identity for Experience Cloud ID Service extensions are required. Find more details in the [Frequently Asked Questions](https://aep-sdks.gitbook.io/docs/foundation-extensions/identity-for-edge-network/identity-faq) page.
+> :information_source: The following instructions are for configuring an application using Adobe Experience Platform Edge mobile extensions. If an application will include both Edge Network and Adobe Solution extensions, both the Identity for Edge Network and Identity for Experience Cloud ID Service extensions are required. Find more details in the [Frequently Asked Questions](https://developer.adobe.com/client-sdks/documentation/identity-for-edge-network/faq) page.


Could we style this using the special github notice block?
ex:

Note
text.......

timkimadobe · 2023-01-27T00:00:28Z

Documentation/getting-started.md

+      // register Adobe extensions
+      MobileCore.registerExtensions(
+         Arrays.asList(Edge.EXTENSION, Identity.EXTENSION),
+         o -> Log.d("MobileApp", "Mobile SDK was initialized")


There are a few things I think we could update for the Java section:

The Java section is missing the variable defn for ENVIRONMENT_FILE_ID

Should we update this log statement to use the new Core Log service and to be more specific (also avoiding usage of the AEP acronym)
maybe we can update with a section like:

public class MobileApp extends Application { // Set up the preferred Environment File ID from your mobile property configured in Data Collection UI private final String ENVIRONMENT_FILE_ID = ""; @Override public void onCreate() { super.onCreate(); MobileCore.setApplication(this); MobileCore.configureWithAppID(ENVIRONMENT_FILE_ID); // Register Adobe Experience Platform SDK extensions MobileCore.registerExtensions( Arrays.asList(Edge.EXTENSION, Identity.EXTENSION), o -> Log.debug("MobileApp", "MobileApp", "Adobe Experience Platform Mobile SDK initialized.") ); } }

timkimadobe · 2023-01-27T00:18:34Z

Documentation/getting-started.md

+        MobileCore.registerExtensions(
+            listOf(Edge.EXTENSION, Identity.EXTENSION, Consent.EXTENSION)
+        ) {
+            MobileCore.configureWithAppID(ENVIRONMENT_FILE_ID)


Currently the Java and Kotlin examples dont follow the same code path or have the same logs; could we update either example to align with the other? for example, updating the kotlin example to something like:

class MobileApp : Application() { // Set up the preferred Environment File ID from your mobile property configured in Data Collection UI private var ENVIRONMENT_FILE_ID: String = "" override fun onCreate() { super.onCreate() MobileCore.setApplication(this) MobileCore.configureWithAppID(ENVIRONMENT_FILE_ID) // Register Adobe Experience Platform SDK extensions MobileCore.registerExtensions( listOf(Edge.EXTENSION, Identity.EXTENSION, Consent.EXTENSION) ) { Log.debug("MobileApp", "MobileApp", "Adobe Experience Platform Mobile SDK initialized.") } } }

timkimadobe · 2023-01-27T00:26:10Z

Documentation/getting-started-test-app.md

+$ adb shell am start -W -a  android.intent.action.VIEW -d "testapp://main?adb_validation_sessionid=ADD_YOUR_SESSION_ID_HERE" com.adobe.marketing.mobile.testapp
+```
+
+Note: replace ADD_YOUR_SESSION_ID_HERE with your Assurance session identifier.


Could we add code styling to the ADD_YOUR_SESSION_ID_HERE?

timkimadobe · 2023-01-27T00:28:18Z

Documentation/getting-started-test-app.md

+**Data Collection mobile property prerequisites**
+
+The test app needs to be configured with the following edge extensions before it can be used:
+- Mobile Core (installed by default)


Should we add a link to the Core extension's repo?:

Mobile Core (installed by default)

timkimadobe · 2023-01-27T00:31:33Z

Documentation/getting-started-test-app.md

@@ -1,5 +1,31 @@
 # Getting started with the test app

+**Data Collection mobile property prerequisites**
+
+The test app needs to be configured with the following edge extensions before it can be used:


Could we flesh out the instructions for setting up the mobile property, maybe extending the explanation from the base getting-started.md's "Configure the Identity extension in Data Collection UI" section?

Just thinking from the perspective of someone who has no idea how to use our extensions this is kind of difficult to understand (where to navigate to, how to set up a mobile property correctly from start to finish, how to get the env file ID, why it's even needed), yet the env file ID from a properly configured mobile property is crucial for the app's proper functioning

I added Refer to getting started for how to get the ENVIRONMENT_FILE_ID.

timkimadobe · 2023-01-27T00:32:37Z

Documentation/getting-started.md

+3. In your mobile property, select **Extensions** tab.
+4. On the **Catalog** tab, locate or search for the **Identity** extension, and select **Install**.
+5. There are no configuration settings for **Identity**.
+6. Follow the [publishing process](https://developer.adobe.com/client-sdks/documentation/getting-started/create-a-mobile-property) to update SDK configuration.

 ## Add the AEP Identity extension to your app


Could we update this (and other AEP usages) to be:
Adobe Experience Platform

Incorporated the review comment part 1

Update getting-started page format.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update doc for v.2.0.0 and use Core MapUtils #89

Update doc for v.2.0.0 and use Core MapUtils #89

cacheung commented Jan 20, 2023 •

edited

Loading

codecov bot commented Jan 20, 2023 •

edited

Loading

emdobrin Jan 24, 2023

cacheung Jan 26, 2023

emdobrin Jan 26, 2023

emdobrin Jan 26, 2023

emdobrin Jan 26, 2023

timkimadobe Jan 26, 2023

emdobrin Jan 26, 2023

emdobrin Jan 26, 2023

emdobrin Jan 26, 2023

addb Jan 26, 2023 •

edited

Loading

timkimadobe Jan 27, 2023

cacheung Jan 27, 2023

addb Jan 27, 2023

timkimadobe left a comment

timkimadobe Jan 26, 2023

timkimadobe Jan 27, 2023

timkimadobe Jan 27, 2023

timkimadobe Jan 27, 2023

timkimadobe Jan 27, 2023

timkimadobe Jan 27, 2023

cacheung Jan 27, 2023

timkimadobe Jan 27, 2023

Update doc for v.2.0.0 and use Core MapUtils #89

Update doc for v.2.0.0 and use Core MapUtils #89

Conversation

cacheung commented Jan 20, 2023 • edited Loading

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Types of changes

Checklist:

codecov bot commented Jan 20, 2023 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

addb Jan 26, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timkimadobe left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cacheung commented Jan 20, 2023 •

edited

Loading

codecov bot commented Jan 20, 2023 •

edited

Loading

addb Jan 26, 2023 •

edited

Loading