Merge pull request #26 from timkimadobe/edge-identity-ad-id

Implementation for Edge Identity ad ID + getUrlVariables features

Author: emdobrin

Documentation/README.md

@@ -9,3 +9,58 @@ Before using messaging feature in the sample app you need to follow the below st
 1. Setup [Journey Optimizer](https://aep-sdks.gitbook.io/docs/beta/adobe-journey-optimizer)
 1. Update the `LAUNCH_ENVIRONMENT_FILE_ID` constant value in `Sample-App/app/src/java/com/adobe/marketing/mobile/sampleapp/MainApp.Java` file with the config app id of the property. 
 For more information on how to get the config app id from launch check this [document](https://experienceleague.adobe.com/docs/launch/using/publish/environments/environments.html?lang=en#mobile-configuration) 
+
+
+# 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-sample-app-android/Sample-App/app/src/main/res/values](../Sample-App/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 4 pairs of special comment blocks (8 total matches) across two files:
+`EdgeIdentityTab.java` and `app/build.gradle`
+
+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

Documentation/assets/find-and-replace-all-example.png

@@ -12,13 +12,14 @@ This repository contains the Android sample app for the AEP SDK.
 
 ## Installation
 
-- Open Android Studio and select `Open an existing project`  from the main screen or click `File -> Open...` .
-- Import the Sample-App/settings.gradle file into Android Studio.
-- Run Android `app` on the emulator or on real device.
+1. Open Android Studio and select `Open an existing project`  from the main screen or click `File -> Open...` .
+2. Import the Sample-App/settings.gradle file into Android Studio.
+3. Set your `ENVIRONMENT_FILE_ID` in MainApp.java.
+4. Run Android `app` on the emulator or on real device.
 
 ## Documentation
-### Launch Edge Extensions Prerequisites
-App needs to be configured with the following edge extensions in Launch before it can be used: 
+### Edge Extensions Prerequisites
+The app needs to be configured with the following Edge extensions in the Data Collection UI before it can be used: 
 - [Edge](https://aep-sdks.gitbook.io/docs/foundation-extensions/experience-platform-extension)
 - [Edge Identity](https://aep-sdks.gitbook.io/docs/foundation-extensions/identity-for-edge-network)
 - [Consent](https://aep-sdks.gitbook.io/docs/foundation-extensions/consent-for-edge-network)
@@ -30,6 +31,9 @@ Follow the [documentation](https://aep-sdks.gitbook.io/docs/foundation-extension
 ### Messaging
 Follow the [documentation](Documentation/README.md) for using the messaging features.
 
+### Advertising Identifier
+Follow the [documentation](Documentation/README.md#advertising-identifier) for enabling advertising identifier features.
+
 ## Contributing
 
 Contributions are welcomed! Read the [Contributing Guide](./.github/CONTRIBUTING.md) for more information.

Documentation/assets/find-and-replace-shortcuts.png

@@ -2,22 +2,26 @@ apply plugin: 'com.android.application'
 apply plugin: 'com.google.gms.google-services'
 
 android {
-    compileSdkVersion 29
-    buildToolsVersion "29.0.2"
+    compileSdkVersion 31
     defaultConfig {
         applicationId "com.adobe.marketing.mobile.sampleapp"
         minSdkVersion 19
-        targetSdkVersion 29
+        targetSdkVersion 31
         versionCode 1
         versionName "1.0"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        multiDexEnabled true
     }
     buildTypes {
         release {
             minifyEnabled false
             proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
         }
     }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
 }
 
 dependencies {
@@ -45,4 +49,15 @@ dependencies {
     // Image loading
     implementation 'com.github.bumptech.glide:glide:4.12.0'
     annotationProcessor 'com.github.bumptech.glide:compiler:4.12.0'
+
+    // For complete instructions on how to enable ad ID features, please see ./Documentation/README.md#advertising-identifier
+    /* Ad ID implementation (pt. 1/4)
+    // GAID Advertising Tracking
+    implementation("com.google.android.gms:play-services-ads-lite:20.6.0")
+    implementation("com.google.guava:guava:31.1-android")
+    /* Ad ID implementation (pt. 1/4) */
+
+    // Multidex support
+    def multidex_version = "2.0.1"
+    implementation "androidx.multidex:multidex:$multidex_version"
 }

Documentation/assets/sync-project-gradle-example.png

@@ -24,7 +24,8 @@
         android:supportsRtl="true"
         android:theme="@style/AppTheme"
         tools:replace="android:icon,android:roundIcon">
-        <activity android:name=".MenuActivity">
+        <activity android:name=".MenuActivity"
+            android:exported="true">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
 
@@ -65,7 +66,10 @@
                 <action android:name="com.google.firebase.MESSAGING_EVENT" />
             </intent-filter>
         </service>
-
+        <!-- Google Ads -->
+        <meta-data
+            android:name="com.google.android.gms.ads.APPLICATION_ID"
+            android:value="@string/gms_ads_app_id"/>
     </application>
 
 </manifest>

README.md

@@ -24,15 +24,30 @@
 import com.adobe.marketing.mobile.edge.identity.Identity;
 import com.adobe.marketing.mobile.edge.identity.IdentityItem;
 import com.adobe.marketing.mobile.edge.identity.IdentityMap;
+
 import com.google.gson.Gson;
 import com.google.gson.GsonBuilder;
 
+// For complete instructions on how to enable ad ID features, please see ./Documentation/README.md#advertising-identifier
+/* Ad ID implementation (pt. 2/4)
+import android.os.Handler;
+import android.os.Looper;
+import com.adobe.marketing.mobile.MobileCore;
+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;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+/* Ad ID implementation (pt. 2/4) */
+
 /**
  * A simple {@link Fragment} subclass.
  * create an instance of this fragment.
  */
 public class EdgeIdentityTab extends Fragment implements NavigationAware {
     private static final String LOG_TAG = "EdgeIdentityTab";
+    private static final String ZERO_ADVERTISING_ID = "00000000-0000-0000-0000-000000000000";
 
     @Override
     public void onCreate(Bundle savedInstanceState) {
@@ -105,6 +120,75 @@ public void call(String ecid) {
                 });
             }
         });
+
+        // Default hint for how to enable ad ID features; overwritten by actual implementation when ad ID features are enabled.
+        Button btnUpdateAdId = getView().findViewById(R.id.btn_edge_identity_get_gaid);
+        btnUpdateAdId.setOnClickListener(new View.OnClickListener() {
+            @Override
+            public void onClick(final View v) {
+                Log.d(LOG_TAG,"For complete instructions on how to enable ad ID features, please see ./Documentation/README.md#advertising-identifier");
+            }
+        });
+        
+        // Edge Identity Advertising Identifier
+        /* Ad ID implementation (pt. 3/4)
+        btnUpdateAdId.setOnClickListener(new View.OnClickListener() {
+            @Override
+            public void onClick(final View v) {
+                getAdvertisingIdClientInfo(new AdobeCallback<AdvertisingIdClient.Info>() {
+                    @Override
+                    public void call(AdvertisingIdClient.Info info) {
+                        Handler handler = new Handler(Looper.getMainLooper());
+
+                        String adIdText = "Unable to get valid AdvertisingIdClient.Info";
+                        String trackingAuthorizationText = "See console for error logs";
+
+                        if (info != null) {
+                            if (info.isLimitAdTrackingEnabled()) {
+                                adIdText = "";
+                                trackingAuthorizationText = "Ad tracking disabled";
+                            } else {
+                                adIdText = info.getId();
+                                trackingAuthorizationText = "Ad tracking enabled";
+                            }
+                            // Update ad ID through MobileCore only when a valid Info instance is available
+                            // to fetch the latest state
+                            MobileCore.setAdvertisingIdentifier(adIdText);
+                        }
+
+                        final String finalAdId = adIdText;
+                        final String finalTrackingAuthorizationText = trackingAuthorizationText;
+                        handler.post(new Runnable() {
+                            @Override
+                            public void run() {
+                                TextView gaidTextView = getView().findViewById(R.id.label_edge_identity_gaid_placeholder);
+                                gaidTextView.setText(finalAdId);
+                                TextView adTrackingTextView = getView().findViewById(R.id.label_edge_identity_ad_tracking_enabled);
+                                adTrackingTextView.setText(finalTrackingAuthorizationText);
+                            }
+                        });
+                    }
+                });
+            }
+        });
+        /* Ad ID implementation (pt. 3/4) */
+
+        // getURLVariables API's
+        Button btnGetUrlVariables = getView().findViewById(R.id.btn_edge_identity_get_urlvariables);
+        btnGetUrlVariables.setOnClickListener(new View.OnClickListener() {
+            @Override
+            public void onClick(final View v) {
+
+                Identity.getUrlVariables(new AdobeCallback<String>() {
+                    @Override
+                    public void call(String urlVariablesString) {
+                        Log.i(LOG_TAG, String.format("Received URLVariables from API = %s", urlVariablesString));
+                        TextView getUrlVariablesTextView = getView().findViewById(R.id.label_edge_identity_get_urlvariables_placeholder);
+                        getUrlVariablesTextView.setText(urlVariablesString);
+                    }
+                });
+            }
+        });
     }
 
     @Override
@@ -136,4 +220,41 @@ public void run() {
             }
         });
     }
-}
+
+    /**
+     * Async method that retrieves the {@link AdvertisingIdClient.Info} (using Google's gms.ads SDK).
+     * Callers <strong>MUST</strong> verify that the result of the callback is not null before using any of its properties.
+     *
+     * @param callback receives the {@link AdvertisingIdClient.Info} if a valid value can be retrieved, {@code null} otherwise.
+     */
+    /* Ad ID implementation (pt. 4/4)
+    private void getAdvertisingIdClientInfo(final AdobeCallback<AdvertisingIdClient.Info> callback) {
+        if (callback == null) {
+            Log.d(LOG_TAG, "Unexpected null callback, provide a callback to retrieve AdvertisingIdClientInfo.");
+            return;
+        }
+        ExecutorService executor = Executors.newSingleThreadExecutor();
+        executor.execute(new Runnable() {
+            @Override
+            public void run() {
+                try {
+                    AdvertisingIdClient.Info idInfo = AdvertisingIdClient.getAdvertisingIdInfo(getContext());
+                    callback.call(idInfo);
+                    return;
+                } catch (GooglePlayServicesNotAvailableException e) {
+                    Log.w(LOG_TAG, "GooglePlayServicesNotAvailableException while retrieving the advertising identifier ${e.localizedMessage}");
+                } catch (GooglePlayServicesRepairableException e) {
+                    Log.w(LOG_TAG, "GooglePlayServicesRepairableException while retrieving the advertising identifier ${e.localizedMessage}");
+                } catch (IOException e) {
+                    Log.w(LOG_TAG, "IOException while retrieving the advertising identifier ${e.localizedMessage}");
+                }
+                callback.call(null);
+            }
+        });
+    }
+    /* Ad ID implementation (pt. 4/4) */
+
+}
+
+
+

Sample-App/app/build.gradle

@@ -29,11 +29,13 @@
 import android.util.Log;
 
 import androidx.annotation.NonNull;
+import androidx.multidex.MultiDex;
 
 public class MainApp extends Application {
 
     private static final String LOG_TAG = "MainApp";
-    private static final String LAUNCH_ENVIRONMENT_FILE_ID = "";
+    // TODO: Set up the preferred Environment File ID from your mobile property configured in Data Collection UI
+    private static final String ENVIRONMENT_FILE_ID = "";
     private static Context context;
 
     public static Context getAppContext() {
@@ -49,7 +51,7 @@ public void onCreate() {
         MobileCore.setLogLevel(LoggingMode.VERBOSE);
         MobileCore.setSmallIconResourceID(R.mipmap.ic_launcher_round);
         MobileCore.setLargeIconResourceID(R.mipmap.ic_launcher_round);
-        MobileCore.configureWithAppID(LAUNCH_ENVIRONMENT_FILE_ID);
+        MobileCore.configureWithAppID(ENVIRONMENT_FILE_ID);
 
         try {
             UserProfile.registerExtension();
@@ -93,4 +95,10 @@ public void onComplete(@NonNull Task<String> task) {
             Log.e(LOG_TAG, "IllegalArgumentException - Check if google-services.json is added and is correctly configured. \nError message: " + e.getLocalizedMessage());
         }
     }
+
+    @Override
+    protected void attachBaseContext(Context base) {
+        super.attachBaseContext(base);
+        MultiDex.install(this);
+    }
 }