Update Android test app to use ad ID feature comment blocks

Documentation/README.md

@@ -0,0 +1,53 @@
+# Advertising identifier
+
+## Configuration
+To enable advertising identifier features in the sample app, follow these steps:
+1. Update the value for key `gms_ads_app_id` located in the `secrets.xml` at [aepsdk-edgeidentity-android/code/app/src/main/res/values](../code/app/src/main/res/values/secrets.xml) with a valid Google AdMob app ID.
+    - See Google's [quick start reference](https://developers.google.com/admob/android/quick-start) on how to get your AdMob app ID. See step 3 of the [Configure your app](https://developers.google.com/admob/android/quick-start#import_the_mobile_ads_sdk) section for a free public test app ID from Google.
+    - Any real key values in the `secrets.xml` file should **not** be committed to the repository.
+2. By default, the ad ID features are commented out in the sample app. To enable these features, uncomment the implemention code using [find and replace all](https://www.jetbrains.com/help/idea/finding-and-replacing-text-in-project.html#replace_search_string_in_project) to replace all instances of:
+```java
+/* Ad ID implementation
+```
+with:
+```java
+//* Ad ID implementation
+```
+Each code block has a pair of block comments wrapped around it to enable this behavior:
+```java
+/* Ad ID implementation (pt. 1/4)
+<commented implementation code...>
+/* Ad ID implementation (pt. 1/4) */
+```
+
+After replacement it will become:
+```java
+//* Ad ID implementation (pt. 1/4)
+<active implementation code!>
+//* Ad ID implementation (pt. 1/4) */
+```
+
+For convenience, these are the default find and replace shortcuts in Android Studio:  
+[<img src="./assets/find-and-replace-shortcuts.png" alt="Default shortcuts for find and replace" width="500"/>](./assets/find-and-replace-shortcuts.png)  
+
+The shortcut should open a window that looks like the following:
+[<img src="./assets/find-and-replace-all-example.png" alt="Example of find and replace" width="500"/>](./assets/find-and-replace-all-example.png)  
+There should be 5 pairs of special comment blocks (10 total matches) across two files:
+`app/build.gradle`, `CustomIdentityFragment.kt`, and `SharedViewModel.kt` 
+
+3. With the implementation code and gradle files uncommented with new dependencies, sync the project with the Gradle file changes using: File -> Sync Project with Gradle Files
+
+[<img src="./assets/sync-project-gradle-example.png" alt="Example of find and replace" width="500"/>](./assets/sync-project-gradle-example.png)  
+
+The app should now be properly configured to use advertising identifier features.
+
+To **disable** these features, follow these steps:
+1. [Find and replace](https://www.jetbrains.com/help/idea/finding-and-replacing-text-in-project.html#replace_search_string_in_project) all instances of:
+```java
+//* Ad ID implementation
+```
+with:
+```java
+/* Ad ID implementation
+```
+2. Sync Project with Gradle files using: File -> Sync Project with Gradle Files

code/app/build.gradle

@@ -63,8 +63,9 @@ dependencies {
     }
     implementation 'com.adobe.marketing.mobile:assurance:1+'
 
+    /* Ad ID implementation (pt. 1/5)
     implementation("com.google.android.gms:play-services-ads-lite:20.6.0")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.0")
-    implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.5.0-alpha06")
+    /* Ad ID implementation (pt. 1/5) */
     implementation("androidx.multidex:multidex:2.0.1")
 }

code/app/src/main/java/com/adobe/marketing/edge/identity/app/EdgeIdentityApplication.kt

@@ -21,7 +21,7 @@ import com.adobe.marketing.mobile.edge.identity.Identity
 
 class EdgeIdentityApplication : Application() {
     // TODO: Set up the preferred Environment File ID from your mobile property configured in Data Collection UI
-    private var ENVIRONMENT_FILE_ID: String = "yourAppId"
+    private var ENVIRONMENT_FILE_ID: String = ""
 
     override fun onCreate() {
         super.onCreate()

code/app/src/main/java/com/adobe/marketing/edge/identity/app/model/SharedViewModel.kt

@@ -11,17 +11,18 @@
 
 package com.adobe.marketing.edge.identity.app.model
 
-import android.content.Context
-import android.util.Log
 import androidx.lifecycle.LiveData
 import androidx.lifecycle.MutableLiveData
 import androidx.lifecycle.ViewModel
 import com.adobe.marketing.mobile.edge.identity.AuthenticatedState
+/* Ad ID implementation (pt. 2/5)
+import android.content.Context
+import android.util.Log
 import com.google.android.gms.ads.identifier.AdvertisingIdClient
 import com.google.android.gms.common.GooglePlayServicesNotAvailableException
 import com.google.android.gms.common.GooglePlayServicesRepairableException
 import java.io.IOException
-
+/* Ad ID implementation (pt. 2/5) */*/
 private const val LOG_TAG = "Shared_View_Model"
 
 class SharedViewModel : ViewModel() {
@@ -124,6 +125,7 @@ class SharedViewModel : ViewModel() {
         _authenticatedStateId.value = value
     }
 
+    /* Ad ID implementation (pt. 3/5)
     /**
      * Async method that retrieves the ad ID from the `AdvertisingIdClient` (from Google's gms.ads SDK).
      * Sanitizes ad ID disabled and exceptions to the empty string (`""`), for easy use with `MobileCore` ad ID APIs.
@@ -152,6 +154,7 @@ class SharedViewModel : ViewModel() {
         Log.d(LOG_TAG, "Returning ad ID value: $adID")
         return adID
     }
+    /* Ad ID implementation (pt. 3/5) */*/
 
     // Models for Multiple Identities View
 

code/app/src/main/java/com/adobe/marketing/edge/identity/app/ui/CustomIdentityFragment.kt

@@ -32,9 +32,11 @@ import com.adobe.marketing.mobile.edge.identity.AuthenticatedState
 import com.adobe.marketing.mobile.edge.identity.Identity
 import com.adobe.marketing.mobile.edge.identity.IdentityItem
 import com.adobe.marketing.mobile.edge.identity.IdentityMap
+/* Ad ID implementation (pt. 4/5)
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
+/* Ad ID implementation (pt. 4/5) */*/
 
 private const val LOG_TAG = "Custom_Identity_Fragment"
 private const val ZERO_ADVERTISING_ID = "00000000-0000-0000-0000-000000000000"
@@ -108,13 +110,21 @@ class CustomIdentityFragment : Fragment() {
             Identity.removeIdentity(item, namespace)
         }
 
+        // Advertising identifier features
+
         // Button for Set Ad ID behavior
         // Sets the advertising identifier set in the corresponding textfield using the MobileCore API
         root.findViewById<Button>(R.id.btn_set_ad_id).setOnClickListener {
             val adId: String? = sharedViewModel.adId.value
             MobileCore.setAdvertisingIdentifier(adId)
         }
 
+        // Default hint for how to enable ad ID features; overwritten by actual implementation when ad ID features are enabled.
+        root.findViewById<Button>(R.id.btn_get_gaid).setOnClickListener {
+            Log.d(LOG_TAG, "For complete instructions on how to enable ad ID features, please see ./Documentation/README.md#advertising-identifier")
+        }
+
+        /* Ad ID implementation (pt. 5/5)
         // For details on implementation tips and differences between Google Play Services Ads vs AndroidX Ads,
         // please see the project Documentation -> AEPEdgeIdentity.md : Android Test App -> Testing tips with Android advertising identifier
         root.findViewById<Button>(R.id.btn_get_gaid).setOnClickListener {
@@ -129,6 +139,12 @@ class CustomIdentityFragment : Fragment() {
                 }
             }
         }
+        /* Ad ID implementation (pt. 5/5) */*/
+
+        root.findViewById<Button>(R.id.btn_set_ad_id_empty_string).setOnClickListener {
+            Log.d(LOG_TAG, "Setting advertising identifier to: \"\"")
+            MobileCore.setAdvertisingIdentifier("")
+        }
 
         root.findViewById<Button>(R.id.btn_set_ad_id_null).setOnClickListener {
             Log.d(LOG_TAG, "Setting advertising identifier to: null")

code/app/src/main/res/layout/fragment_custom_identity.xml

@@ -200,6 +200,13 @@
         app:layout_constraintTop_toBottomOf="@id/layout_set_ad_id"
         tools:layout_editor_absoluteX="1dp">
 
+        <Button
+            android:id="@+id/btn_set_ad_id_empty_string"
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:layout_weight="1"
+            android:text="@string/btn_set_ad_id_empty_string" />
+
         <Button
             android:id="@+id/btn_set_ad_id_null"
             android:layout_width="wrap_content"

code/app/src/main/res/values/strings.xml

@@ -41,7 +41,8 @@
     <string name="btn_get_consents">Get Current Consents</string>
     <string name="btn_get_gaid">Update Ad ID With Current GAID</string>
     <string name="btn_set_ad_id">Set Ad ID</string>
-    <string name="btn_set_ad_id_all_zeros">Set Ad ID as all-zeros</string>
+    <string name="btn_set_ad_id_empty_string">Set Ad ID as Empty String</string>
+    <string name="btn_set_ad_id_all_zeros">Set Ad ID as All-Zeros</string>
     <string name="btn_set_ad_id_null">Set Ad ID as null</string>
 
     <!-- Labels -->