From f26005842900e4da3e33f89ccc110ffcba429288 Mon Sep 17 00:00:00 2001
From: Arjun Bhadra <arjun.d.bhadra@gmail.com>
Date: Fri, 13 May 2022 14:43:08 -0700
Subject: [PATCH 1/4] [MOB-15817] Add getUrlVariables public API (#59)

* [MOB-15817] Implemented getUrlVariables public API

* [MOB-15817] Added unit tests for getUrlVariable implementation logic

* [MOB-15817] Updated sample app with getUrlVariable public API

* [MOB-1917] Clear config

* [MOB-15817] Format fixes

* [MOB-15817] Fix javadoc

* [MOB-15817] minor bug fix and test fixes

* [MOB-15817] Add more tests

* [MOB-15817] Add tests, make minor fixes and review fixes

* [MOB-15817] Fix test and added a test to improve coverage

* [MOB-15817] Minor refactoring based on reviews

* [MOB-15817] More tests, minor refactoring and review fixes

* [MOB-15817] Review fixes

* [MOB-15817] Fix method java doc description

* [MOB-15817] Used java.net.URLEncoder instead of custom implementation. Added few tests. Also added review fixes.

* [MOB-15817] Added more tests for URL encoder

* [MOB-15817] Cleanup urlEncode helper and tests
---
 .../identity/app/model/SharedViewModel.kt     |   7 +
 .../identity/app/ui/GetIdentityFragment.kt    |  23 ++
 .../main/res/layout/fragment_get_identity.xml |  25 ++
 code/app/src/main/res/values/strings.xml      |   1 +
 .../identity/IdentityFunctionalTestUtil.java  |  13 ++
 .../edge/identity/IdentityPublicAPITest.java  |  24 ++
 .../mobile/edge/identity/EventUtils.java      |  57 +++++
 .../mobile/edge/identity/Identity.java        |  87 +++++++
 .../edge/identity/IdentityConstants.java      |  27 +++
 .../edge/identity/IdentityExtension.java      | 105 ++++++++-
 .../edge/identity/IdentityProperties.java     |   2 +-
 .../mobile/edge/identity/URLUtils.java        |  92 ++++++++
 .../marketing/mobile/edge/identity/Utils.java |  13 +-
 .../edge/identity/IdentityTestUtil.java       |  20 ++
 .../mobile/edge/identity/EventUtilsTests.java | 168 ++++++++++++++
 .../edge/identity/IdentityExtensionTests.java | 219 ++++++++++++++++++
 .../edge/identity/IdentityStateTests.java     |  12 +
 .../mobile/edge/identity/IdentityTests.java   | 195 ++++++++++++++++
 ...tenerEdgeIdentityRequestIdentityTests.java |  27 +++
 .../mobile/edge/identity/URLUtilsTests.java   |  37 +++
 20 files changed, 1150 insertions(+), 4 deletions(-)
 create mode 100644 code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/URLUtils.java
 create mode 100644 code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/EventUtilsTests.java
 create mode 100644 code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/URLUtilsTests.java

diff --git a/code/app/src/main/java/com/adobe/marketing/edge/identity/app/model/SharedViewModel.kt b/code/app/src/main/java/com/adobe/marketing/edge/identity/app/model/SharedViewModel.kt
index 77cac6d4..223c89ba 100644
--- a/code/app/src/main/java/com/adobe/marketing/edge/identity/app/model/SharedViewModel.kt
+++ b/code/app/src/main/java/com/adobe/marketing/edge/identity/app/model/SharedViewModel.kt
@@ -32,6 +32,9 @@ class SharedViewModel : ViewModel() {
     private val _ecidLegacyText = MutableLiveData<String>("")
     val ecidLegacyText: LiveData<String> = _ecidLegacyText
 
+    private val _urlVariablesText = MutableLiveData<String>("")
+    val urlVariablesText: LiveData<String> = _urlVariablesText
+
     private val _identitiesText = MutableLiveData<String>("")
     val identitiesText: LiveData<String> = _identitiesText
 
@@ -43,6 +46,10 @@ class SharedViewModel : ViewModel() {
         _ecidLegacyText.value = value
     }
 
+    fun setUrlVariablesValue(value: String) {
+        _urlVariablesText.value = value
+    }
+
     fun setIdentitiesValue(value: String) {
         _identitiesText.value = value
     }
diff --git a/code/app/src/main/java/com/adobe/marketing/edge/identity/app/ui/GetIdentityFragment.kt b/code/app/src/main/java/com/adobe/marketing/edge/identity/app/ui/GetIdentityFragment.kt
index 7198f7f0..90ff01f3 100644
--- a/code/app/src/main/java/com/adobe/marketing/edge/identity/app/ui/GetIdentityFragment.kt
+++ b/code/app/src/main/java/com/adobe/marketing/edge/identity/app/ui/GetIdentityFragment.kt
@@ -54,6 +54,14 @@ class GetIdentityFragment : Fragment() {
             }
         )
 
+        val urlVariablesTextView = root.findViewById<TextView>(R.id.text_url_variables)
+        sharedViewModel.urlVariablesText.observe(
+            viewLifecycleOwner,
+            Observer {
+                urlVariablesTextView.text = it
+            }
+        )
+
         val identitiesTextView = root.findViewById<TextView>(R.id.text_identities)
         sharedViewModel.identitiesText.observe(
             viewLifecycleOwner,
@@ -85,6 +93,21 @@ class GetIdentityFragment : Fragment() {
             sharedViewModel.setEcidLegacyValue(if (resultSecondary != null) "legacy: $resultSecondary" else "")
         }
 
+        root.findViewById<Button>(R.id.btn_get_url_variables).setOnClickListener {
+            val latch = CountDownLatch(2)
+            var resultUrlVariables: String? = null
+
+            com.adobe.marketing.mobile.edge.identity.Identity.getUrlVariables { urlVariables ->
+                Log.d("Home", "Got UrlVariables String: $urlVariables")
+                resultUrlVariables = urlVariables
+                latch.countDown()
+            }
+
+            latch.await(1, TimeUnit.SECONDS)
+
+            sharedViewModel.setUrlVariablesValue(if (resultUrlVariables != null) "urlVariablesString: $resultUrlVariables" else "urlVariablesString: not found")
+        }
+
         root.findViewById<Button>(R.id.btn_get_identities).setOnClickListener {
             val latch = CountDownLatch(1)
             var result: String? = null
diff --git a/code/app/src/main/res/layout/fragment_get_identity.xml b/code/app/src/main/res/layout/fragment_get_identity.xml
index cc17d05b..899a8e55 100644
--- a/code/app/src/main/res/layout/fragment_get_identity.xml
+++ b/code/app/src/main/res/layout/fragment_get_identity.xml
@@ -58,6 +58,28 @@
 
         </LinearLayout>
 
+        <Button
+            android:id="@+id/btn_get_url_variables"
+            android:layout_width="wrap_content"
+            android:layout_height="wrap_content"
+            android:text="@string/btn_get_url_variables"
+            android:layout_gravity="center"
+            android:layout_marginTop="18dp"
+            />
+
+            <TextView
+                android:id="@+id/text_url_variables"
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:layout_marginEnd="8dp"
+                android:layout_marginStart="8dp"
+                android:layout_marginTop="8dp"
+                android:textAlignment="center"
+                android:textSize="12sp"
+                android:layout_gravity="center"
+                android:scrollbars="vertical"
+                android:background="@drawable/border"
+                />
 
         <Button
             android:id="@+id/btn_reset_identities"
@@ -65,6 +87,9 @@
             android:layout_height="wrap_content"
             android:text="@string/btn_reset_identities"
             android:layout_gravity="center"
+            android:layout_marginTop="18dp"
+            android:backgroundTint="@android:color/holo_red_light"
+            android:textColor="@android:color/white"
             />
 
         <Button
diff --git a/code/app/src/main/res/values/strings.xml b/code/app/src/main/res/values/strings.xml
index 5bedbf7a..09ae4a26 100644
--- a/code/app/src/main/res/values/strings.xml
+++ b/code/app/src/main/res/values/strings.xml
@@ -12,6 +12,7 @@
     <string name="menu_custom_identity">Set Custom Identity</string>
     <string name="menu_multiple_identity">Test Multiple Identities</string>
     <string name="btn_get_ecid">Get ECID</string>
+    <string name="btn_get_url_variables">Get URL Variables</string>
     <string name="btn_get_identities">Get Identities</string>
     <string name="btn_reset_identities">Reset Identities</string>
     <string name="label_identifier">Identifier: </string>
diff --git a/code/edgeidentity/src/androidTest/java/com/adobe/marketing/mobile/edge/identity/IdentityFunctionalTestUtil.java b/code/edgeidentity/src/androidTest/java/com/adobe/marketing/mobile/edge/identity/IdentityFunctionalTestUtil.java
index 14788f0d..40e8465f 100644
--- a/code/edgeidentity/src/androidTest/java/com/adobe/marketing/mobile/edge/identity/IdentityFunctionalTestUtil.java
+++ b/code/edgeidentity/src/androidTest/java/com/adobe/marketing/mobile/edge/identity/IdentityFunctionalTestUtil.java
@@ -110,6 +110,19 @@ public void call(Object o) {
 		resetTestExpectations();
 	}
 
+	/**
+	 * Updates configuration shared state with an orgId
+	 */
+	static void setupConfiguration() throws Exception {
+		HashMap<String, Object> config = new HashMap<String, Object>() {
+			{
+				put("experienceCloud.org", "testOrg@AdobeOrg");
+			}
+		};
+		MobileCore.updateConfiguration(config);
+		TestHelper.waitForThreads(2000);
+	}
+
 	/**
 	 * Set the ECID in persistence for Identity Direct extension.
 	 */
diff --git a/code/edgeidentity/src/androidTest/java/com/adobe/marketing/mobile/edge/identity/IdentityPublicAPITest.java b/code/edgeidentity/src/androidTest/java/com/adobe/marketing/mobile/edge/identity/IdentityPublicAPITest.java
index 06fefc50..bc187a84 100644
--- a/code/edgeidentity/src/androidTest/java/com/adobe/marketing/mobile/edge/identity/IdentityPublicAPITest.java
+++ b/code/edgeidentity/src/androidTest/java/com/adobe/marketing/mobile/edge/identity/IdentityPublicAPITest.java
@@ -13,6 +13,7 @@
 
 import static com.adobe.marketing.mobile.TestHelper.*;
 import static com.adobe.marketing.mobile.edge.identity.IdentityFunctionalTestUtil.registerEdgeIdentityExtension;
+import static com.adobe.marketing.mobile.edge.identity.IdentityFunctionalTestUtil.setupConfiguration;
 import static com.adobe.marketing.mobile.edge.identity.IdentityTestUtil.*;
 import static org.junit.Assert.*;
 
@@ -282,6 +283,29 @@ public void testGetExperienceCloudId_nullCallback() {
 		}
 	}
 
+	// --------------------------------------------------------------------------------------------
+	// Tests for getUrlVariables API
+	// --------------------------------------------------------------------------------------------
+
+	@Test
+	public void testGetUrlVariables() throws Exception {
+		// test
+		setupConfiguration();
+		String urlVariables = getUrlVariablesSync();
+
+		assertNotNull(urlVariables);
+	}
+
+	@Test
+	public void testGetUrlVariables_nullCallback() {
+		// test
+		try {
+			Identity.getUrlVariables(null); // should not crash
+		} catch (Exception e) {
+			fail();
+		}
+	}
+
 	// --------------------------------------------------------------------------------------------
 	// Tests for getIdentities API
 	// --------------------------------------------------------------------------------------------
diff --git a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/EventUtils.java b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/EventUtils.java
index 0302783d..26329b9c 100644
--- a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/EventUtils.java
+++ b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/EventUtils.java
@@ -65,6 +65,33 @@ static boolean isRequestIdentityEvent(final Event event) {
 		);
 	}
 
+	/**
+	 * Reads the url variables flag from the event data, returns false if not present
+	 * Note: This API needs to be used with isRequestIdentityEvent API to determine the correct event type and event source
+	 * @param event the event to verify
+	 * @return true if urlVariables key is present in the event data and has a value of true
+	 */
+	static boolean isGetUrlVariablesRequestEvent(final Event event) {
+		if (event == null || event.getEventData() == null) {
+			return false;
+		}
+		boolean getUrlVariablesFlag = false;
+
+		try {
+			Object urlVariablesFlagObject = event.getEventData().get(IdentityConstants.EventDataKeys.URL_VARIABLES);
+			getUrlVariablesFlag = urlVariablesFlagObject != null && (boolean) urlVariablesFlagObject;
+		} catch (ClassCastException e) {
+			MobileCore.log(
+				LoggingMode.WARNING,
+				LOG_TAG,
+				"EventUtils - Failed to read urlvariables value, expected boolean: " + e.getLocalizedMessage()
+			);
+			return false;
+		}
+
+		return getUrlVariablesFlag;
+	}
+
 	/**
 	 * Checks if the provided {@code event} is of type {@link IdentityConstants.EventType#GENERIC_IDENTITY} and source {@link IdentityConstants.EventSource#REQUEST_RESET}
 	 *
@@ -127,4 +154,34 @@ static ECID getECID(final Map<String, Object> identityDirectSharedState) {
 
 		return legacyEcid;
 	}
+
+	/**
+	 * Extracts the Experience Cloud Org Id from the Configuration shared state
+	 *
+	 * @param configurationSharedState the configuration shared state data
+	 * @return the Experience Cloud Org Id or null if not found or unable to parse the payload
+	 */
+	static String getOrgId(final Map<String, Object> configurationSharedState) {
+		String orgId = null;
+
+		if (configurationSharedState == null) {
+			return orgId;
+		}
+
+		try {
+			orgId =
+				(String) configurationSharedState.get(
+					IdentityConstants.SharedState.Configuration.EXPERIENCE_CLOUD_ORGID
+				);
+		} catch (ClassCastException e) {
+			MobileCore.log(
+				LoggingMode.DEBUG,
+				LOG_TAG,
+				"EventUtils - Failed to extract Experience ORG ID from Configuration shared state, expected String: " +
+				e.getLocalizedMessage()
+			);
+		}
+
+		return orgId;
+	}
 }
diff --git a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/Identity.java b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/Identity.java
index 85de72e9..5c22bbdb 100644
--- a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/Identity.java
+++ b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/Identity.java
@@ -21,7 +21,9 @@
 import com.adobe.marketing.mobile.ExtensionErrorCallback;
 import com.adobe.marketing.mobile.LoggingMode;
 import com.adobe.marketing.mobile.MobileCore;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 
 /**
  * Defines the public APIs for the AEP Edge Identity extension.
@@ -136,6 +138,91 @@ public void call(Event responseEvent) {
 		);
 	}
 
+	/**
+	 * Returns the identifiers in URL query parameter format for consumption in hybrid mobile applications.
+	 * There is no leading &amp; or ? punctuation as the caller is responsible for placing the variables in their resulting URL in the correct locations.
+	 * If an error occurs while retrieving the URL variables, the AdobeCallbackWithError is called with a null value and AdobeError instance.
+	 * If AdobeCallback is provided then callback is not called in case of error.
+	 * Otherwise, the encoded string is returned, for ex: "adobe_mc=TS%3DTIMESTAMP_VALUE%7CMCMID%3DYOUR_ECID%7CMCORGID%3D9YOUR_EXPERIENCE_CLOUD_ID"
+	 * The {@code adobe_mc} attribute is an URL encoded list that contains:
+	 *	<ul>
+	 *		<li>TS: a timestamp taken when the request was made</li>
+	 * 		<li>MCID: Experience Cloud ID (ECID)</li>
+	 * 		<li>MCORGID: Experience Cloud Org ID</li>
+	 * 	</ul>
+	 *
+	 * @param callback {@link AdobeCallback} of {@code String} invoked with a value containing the identifiers in query parameter format.
+	 *     	           If an {@link AdobeCallbackWithError} is provided, an {@link AdobeError} can be returned in the
+	 *	               eventuality of any error that occurred while getting the identifiers query string
+	 */
+	public static void getUrlVariables(final AdobeCallback<String> callback) {
+		if (callback == null) {
+			MobileCore.log(
+				LoggingMode.DEBUG,
+				LOG_TAG,
+				"Identity - Unexpected null callback, provide a callback to retrieve current visitor identifiers (URLVariables) query string."
+			);
+			return;
+		}
+
+		final Event event = new Event.Builder(
+			IdentityConstants.EventNames.IDENTITY_REQUEST_URL_VARIABLES,
+			IdentityConstants.EventType.EDGE_IDENTITY,
+			IdentityConstants.EventSource.REQUEST_IDENTITY
+		)
+			.setEventData(
+				new HashMap<String, Object>() {
+					{
+						put(IdentityConstants.EventDataKeys.URL_VARIABLES, true);
+					}
+				}
+			)
+			.build();
+
+		final ExtensionErrorCallback<ExtensionError> errorCallback = new ExtensionErrorCallback<ExtensionError>() {
+			@Override
+			public void error(final ExtensionError extensionError) {
+				returnError(callback, extensionError);
+				MobileCore.log(
+					LoggingMode.DEBUG,
+					LOG_TAG,
+					String.format(
+						"Identity - Failed to dispatch %s event: Error : %s.",
+						IdentityConstants.EventNames.IDENTITY_REQUEST_URL_VARIABLES,
+						extensionError.getErrorName()
+					)
+				);
+			}
+		};
+
+		MobileCore.dispatchEventWithResponseCallback(
+			event,
+			new AdobeCallback<Event>() {
+				@Override
+				public void call(Event responseEvent) {
+					if (responseEvent == null || responseEvent.getEventData() == null) {
+						returnError(callback, AdobeError.UNEXPECTED_ERROR);
+						return;
+					}
+
+					final Map<String, Object> data = responseEvent.getEventData();
+					try {
+						String urlVariableString = (String) data.get(IdentityConstants.EventDataKeys.URL_VARIABLES);
+						if (urlVariableString == null) {
+							returnError(callback, AdobeError.UNEXPECTED_ERROR);
+							return;
+						}
+						callback.call(urlVariableString);
+					} catch (ClassCastException e) {
+						returnError(callback, AdobeError.UNEXPECTED_ERROR);
+						return;
+					}
+				}
+			},
+			errorCallback
+		);
+	}
+
 	/**
 	 * Updates the currently known {@link IdentityMap} within the SDK.
 	 * The Identity extension will merge the received identifiers with the previously saved one in an additive manner,
diff --git a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityConstants.java b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityConstants.java
index b6bc6640..b6991681 100644
--- a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityConstants.java
+++ b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityConstants.java
@@ -42,10 +42,19 @@ final class EventType {
 		private EventType() {}
 	}
 
+	final class EventDataKeys {
+
+		static final String URL_VARIABLES = "urlvariables";
+
+		private EventDataKeys() {}
+	}
+
 	final class EventNames {
 
 		static final String IDENTITY_REQUEST_IDENTITY_ECID = "Edge Identity Request ECID";
+		static final String IDENTITY_REQUEST_URL_VARIABLES = "Edge Identity Request URL Variables";
 		static final String IDENTITY_RESPONSE_CONTENT_ONE_TIME = "Edge Identity Response Content One Time";
+		static final String IDENTITY_RESPONSE_URL_VARIABLES = "Edge Identity Response URL Variables";
 		static final String UPDATE_IDENTITIES = "Edge Identity Update Identities";
 		static final String REMOVE_IDENTITIES = "Edge Identity Remove Identities";
 		static final String REQUEST_IDENTITIES = "Edge Identity Request Identities";
@@ -66,6 +75,14 @@ final class Hub {
 			private Hub() {}
 		}
 
+		final class Configuration {
+
+			static final String NAME = "com.adobe.module.configuration";
+			static final String EXPERIENCE_CLOUD_ORGID = "experienceCloud.org";
+
+			private Configuration() {}
+		}
+
 		final class IdentityDirect {
 
 			static final String NAME = "com.adobe.module.identity";
@@ -106,5 +123,15 @@ final class DataStoreKey {
 		private DataStoreKey() {}
 	}
 
+	final class UrlKeys {
+
+		static final String TS = "TS";
+		static final String EXPERIENCE_CLOUD_ORG_ID = "MCORGID";
+		static final String EXPERIENCE_CLOUD_ID = "MCMID";
+		static final String PAYLOAD = "adobe_mc";
+
+		private UrlKeys() {}
+	}
+
 	private IdentityConstants() {}
 }
diff --git a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityExtension.java b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityExtension.java
index 0a0b2ded..39d62104 100644
--- a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityExtension.java
+++ b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityExtension.java
@@ -20,6 +20,7 @@
 import com.adobe.marketing.mobile.ExtensionErrorCallback;
 import com.adobe.marketing.mobile.LoggingMode;
 import com.adobe.marketing.mobile.MobileCore;
+import java.util.HashMap;
 import java.util.Map;
 import java.util.concurrent.ConcurrentLinkedQueue;
 import java.util.concurrent.ExecutorService;
@@ -160,7 +161,11 @@ void processCachedEvents() {
 			final Event event = cachedEvents.peek();
 
 			if (EventUtils.isRequestIdentityEvent(event)) {
-				handleIdentityRequest(event);
+				if (EventUtils.isGetUrlVariablesRequestEvent(event)) {
+					handleUrlVariablesRequest(event);
+				} else {
+					handleIdentityRequest(event);
+				}
 			} else if (EventUtils.isUpdateIdentityEvent(event)) {
 				handleUpdateIdentities(event);
 			} else if (EventUtils.isRemoveIdentityEvent(event)) {
@@ -236,6 +241,101 @@ public void error(ExtensionError extensionError) {
 		return state.bootupIfReady(callback);
 	}
 
+	/**
+	 * Handles events requesting for formatted and encoded identifiers url for hybrid apps.
+	 *
+	 * @param event the identity request {@link Event}
+	 */
+	void handleUrlVariablesRequest(final Event event) {
+		String urlVariablesString = null;
+
+		final Map<String, Object> configurationState = getSharedState(
+			IdentityConstants.SharedState.Configuration.NAME,
+			event
+		);
+
+		final String orgId = EventUtils.getOrgId(configurationState);
+
+		if (Utils.isNullOrEmpty(orgId)) {
+			handleUrlVariableResponse(
+				event,
+				urlVariablesString,
+				"IdentityExtension - Cannot process getUrlVariables request Identity event, Experience Cloud Org ID not found in configuration."
+			);
+			return;
+		}
+
+		ECID ecid = state.getIdentityProperties().getECID();
+		final String ecidString = ecid != null ? ecid.toString() : null;
+
+		if (Utils.isNullOrEmpty(ecidString)) {
+			handleUrlVariableResponse(
+				event,
+				urlVariablesString,
+				"IdentityExtension - Cannot process getUrlVariables request Identity event, ECID not found."
+			);
+			return;
+		}
+
+		urlVariablesString =
+			URLUtils.generateURLVariablesPayload(String.valueOf(Utils.getUnixTimeInSeconds()), ecidString, orgId);
+
+		handleUrlVariableResponse(event, urlVariablesString);
+	}
+
+	/**
+	 * Handles response event after processing the url variables request.
+	 *
+	 * @param event the identity request {@link Event}
+	 * @param urlVariables {@link String} representing the urlVariables encoded string
+	 */
+	private void handleUrlVariableResponse(final Event event, final String urlVariables) {
+		handleUrlVariableResponse(event, urlVariables, null);
+	}
+
+	/**
+	 * Handles response event after processing the url variables request.
+	 *
+	 * @param event the identity request {@link Event}
+	 * @param urlVariables {@link String} representing the urlVariables encoded string
+	 * @param errorMsg {@link String} representing error encountered while generating the urlVariables string
+	 */
+	private void handleUrlVariableResponse(final Event event, final String urlVariables, final String errorMsg) {
+		Event responseEvent = new Event.Builder(
+			IdentityConstants.EventNames.IDENTITY_RESPONSE_URL_VARIABLES,
+			IdentityConstants.EventType.EDGE_IDENTITY,
+			IdentityConstants.EventSource.RESPONSE_IDENTITY
+		)
+			.setEventData(
+				new HashMap<String, Object>() {
+					{
+						put(IdentityConstants.EventDataKeys.URL_VARIABLES, urlVariables);
+					}
+				}
+			)
+			.build();
+
+		ExtensionErrorCallback<ExtensionError> errorCallback = new ExtensionErrorCallback<ExtensionError>() {
+			@Override
+			public void error(ExtensionError extensionError) {
+				MobileCore.log(
+					LoggingMode.DEBUG,
+					LOG_TAG,
+					"IdentityExtension - Failed to dispatch Edge Identity response event for event " +
+					event.getUniqueIdentifier() +
+					" with error " +
+					extensionError.getErrorName()
+				);
+			}
+		};
+
+		if (Utils.isNullOrEmpty(urlVariables) && !Utils.isNullOrEmpty(errorMsg)) {
+			MobileCore.log(LoggingMode.WARNING, LOG_TAG, errorMsg);
+		}
+
+		MobileCore.dispatchResponseEvent(responseEvent, event, errorCallback);
+	}
+
 	/**
 	 * Handles update identity requests to add/update customer identifiers.
 	 *
@@ -435,7 +535,8 @@ public void error(final ExtensionError extensionError) {
 					LoggingMode.DEBUG,
 					LOG_TAG,
 					String.format(
-						"IdentityExtension - Failed getting direct Identity shared state. Error : %s.",
+						"IdentityExtension - Failed getting %s shared state. Error : %s.",
+						stateOwner,
 						extensionError.getErrorName()
 					)
 				);
diff --git a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityProperties.java b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityProperties.java
index 6cbafec8..d93ca430 100644
--- a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityProperties.java
+++ b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/IdentityProperties.java
@@ -62,7 +62,7 @@ void setECID(final ECID newEcid) {
 			identityMap.removeItem(previousECIDItem, IdentityConstants.Namespaces.ECID);
 		}
 
-		// if primary ecid is null, clear off all the existing ECID's
+		// if primary ECID is null, clear off all the existing ECID's
 		if (newEcid == null) {
 			setECIDSecondary(null);
 			identityMap.clearItemsForNamespace(IdentityConstants.Namespaces.ECID);
diff --git a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/URLUtils.java b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/URLUtils.java
new file mode 100644
index 00000000..2a62a87b
--- /dev/null
+++ b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/URLUtils.java
@@ -0,0 +1,92 @@
+/*
+  Copyright 2022 Adobe. All rights reserved.
+  This file is licensed to you under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License. You may obtain a copy
+  of the License at http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing, software distributed under
+  the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+  OF ANY KIND, either express or implied. See the License for the specific language
+  governing permissions and limitations under the License.
+*/
+
+package com.adobe.marketing.mobile.edge.identity;
+
+import com.adobe.marketing.mobile.LoggingMode;
+import com.adobe.marketing.mobile.MobileCore;
+import java.io.UnsupportedEncodingException;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+
+class URLUtils {
+
+	static final String LOG_TAG = "URLUtils";
+
+	/**
+	 * Helper function to generate url variables in format acceptable by the AEP web SDKs
+	 *
+	 * @param ts timestamp {@link String} denoting time when url variables request was made
+	 * @param ecid Experience Cloud identifier {@link String} generated by the SDK
+	 * @param orgId Experience Cloud Org identifier {@link String} set in the configuration
+	 * @return {@link String} formatted with the visitor id payload
+	 */
+	static String generateURLVariablesPayload(final String ts, final String ecid, final String orgId) {
+		final StringBuilder urlFragment = new StringBuilder();
+
+		// construct the adobe_mc string
+		try {
+			// append timestamp
+			String theIdString = appendKVPToVisitorIdString(null, IdentityConstants.UrlKeys.TS, ts);
+
+			// append ecid
+			theIdString = appendKVPToVisitorIdString(theIdString, IdentityConstants.UrlKeys.EXPERIENCE_CLOUD_ID, ecid);
+
+			// add Experience Cloud Org ID
+			theIdString =
+				appendKVPToVisitorIdString(theIdString, IdentityConstants.UrlKeys.EXPERIENCE_CLOUD_ORG_ID, orgId);
+
+			// after the adobe_mc string is created, encode the idString before adding it to the url
+			urlFragment.append(IdentityConstants.UrlKeys.PAYLOAD);
+			urlFragment.append("=");
+
+			if (Utils.isNullOrEmpty(theIdString)) {
+				// No need to encode
+				urlFragment.append("null");
+			} else {
+				urlFragment.append(URLEncoder.encode(theIdString, StandardCharsets.UTF_8.toString()));
+			}
+		} catch (UnsupportedEncodingException e) {
+			MobileCore.log(LoggingMode.DEBUG, LOG_TAG, String.format("Failed to encode urlVariable string: %s", e));
+		}
+		return urlFragment.toString();
+	}
+
+	/**
+	 * Takes in a key-value pair and appends it to the source string
+	 * <p>
+	 * This method <b>does not</b> URL encode the provided {@code value} on the resulting string.
+	 * If encoding is needed, make sure that the values are encoded before being passed into this function.
+	 *
+	 * @param originalString {@link String} to append the key and value to
+	 * @param key key to append
+	 * @param value value to append
+	 *
+	 * @return a new string with the key and value appended, or {@code originalString}
+	 *         if {@code key} or {@code value} are null or empty
+	 */
+	static String appendKVPToVisitorIdString(final String originalString, final String key, final String value) {
+		// quickly return original string if key or value are empty
+		if (Utils.isNullOrEmpty(key) || Utils.isNullOrEmpty(value)) {
+			return originalString;
+		}
+
+		// get the value for the new variable
+		final String newUrlVariable = String.format("%s=%s", key, value);
+
+		// if the original string is not empty, we need to append a pipe before we return
+		if (Utils.isNullOrEmpty(originalString)) {
+			return newUrlVariable;
+		} else {
+			return String.format("%s|%s", originalString, newUrlVariable);
+		}
+	}
+}
diff --git a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/Utils.java b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/Utils.java
index 1f108a5c..8e077acb 100644
--- a/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/Utils.java
+++ b/code/edgeidentity/src/main/java/com/adobe/marketing/mobile/edge/identity/Utils.java
@@ -26,6 +26,8 @@
 
 class Utils {
 
+	private static final long MILLISECONDS_PER_SECOND = 1000L;
+
 	private Utils() {}
 
 	static boolean isNullOrEmpty(final String str) {
@@ -183,7 +185,7 @@ static Map<String, Object> deepCopy(final Map<String, Object> map) {
 	 *
 	 * @param listOfMaps to be copied
 	 * @return {@link List} containing a deep copy of all the elements in {@code listOfMaps}
-	 * @see {@link #deepCopy(Map)}
+	 * @see #deepCopy(Map)
 	 */
 	static List<Map<String, Object>> deepCopy(final List<Map<String, Object>> listOfMaps) {
 		if (listOfMaps == null) {
@@ -198,4 +200,13 @@ static List<Map<String, Object>> deepCopy(final List<Map<String, Object>> listOf
 
 		return deepCopy;
 	}
+
+	/**
+	 * Gets current unix timestamp in seconds.
+	 *
+	 * @return {code long} current timestamp
+	 */
+	static long getUnixTimeInSeconds() {
+		return System.currentTimeMillis() / MILLISECONDS_PER_SECOND;
+	}
 }
diff --git a/code/edgeidentity/src/sharedTestUtils/java/com/adobe/marketing/mobile/edge/identity/IdentityTestUtil.java b/code/edgeidentity/src/sharedTestUtils/java/com/adobe/marketing/mobile/edge/identity/IdentityTestUtil.java
index 192190e0..ee8f58e2 100644
--- a/code/edgeidentity/src/sharedTestUtils/java/com/adobe/marketing/mobile/edge/identity/IdentityTestUtil.java
+++ b/code/edgeidentity/src/sharedTestUtils/java/com/adobe/marketing/mobile/edge/identity/IdentityTestUtil.java
@@ -348,6 +348,26 @@ public void call(final String ecid) {
 		}
 	}
 
+	static String getUrlVariablesSync() {
+		try {
+			final HashMap<String, String> getUrlVariablesResponse = new HashMap<>();
+			final ADBCountDownLatch latch = new ADBCountDownLatch(1);
+			Identity.getUrlVariables(
+				new AdobeCallback<String>() {
+					@Override
+					public void call(final String urlVariables) {
+						getUrlVariablesResponse.put(IdentityTestConstants.GetIdentitiesHelper.VALUE, urlVariables);
+						latch.countDown();
+					}
+				}
+			);
+			latch.await(2000, TimeUnit.MILLISECONDS);
+			return getUrlVariablesResponse.get(IdentityTestConstants.GetIdentitiesHelper.VALUE);
+		} catch (Exception exp) {
+			return null;
+		}
+	}
+
 	static IdentityMap CreateIdentityMap(final String namespace, final String id) {
 		return CreateIdentityMap(namespace, id, AuthenticatedState.AMBIGUOUS, false);
 	}
diff --git a/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/EventUtilsTests.java b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/EventUtilsTests.java
new file mode 100644
index 00000000..950dbf76
--- /dev/null
+++ b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/EventUtilsTests.java
@@ -0,0 +1,168 @@
+/*
+  Copyright 2021 Adobe. All rights reserved.
+  This file is licensed to you under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License. You may obtain a copy
+  of the License at http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing, software distributed under
+  the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+  OF ANY KIND, either express or implied. See the License for the specific language
+  governing permissions and limitations under the License.
+*/
+
+package com.adobe.marketing.mobile.edge.identity;
+
+import static junit.framework.TestCase.assertFalse;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+
+import com.adobe.marketing.mobile.Event;
+import java.util.HashMap;
+import org.junit.Test;
+
+public class EventUtilsTests {
+
+	@Test
+	public void test_isRequestIdentityEventForGetUrlVariable_nullEvent_returnsFalse() {
+		assertFalse(EventUtils.isGetUrlVariablesRequestEvent(null));
+	}
+
+	@Test
+	public void test_isRequestIdentityEventForGetUrlVariable_eventContainsUrlVariablesKey_validBooleanValue_returnsSetBooleanValue() {
+		Event event = new Event.Builder(
+			IdentityConstants.EventNames.IDENTITY_REQUEST_URL_VARIABLES,
+			IdentityConstants.EventType.EDGE_IDENTITY,
+			IdentityConstants.EventSource.REQUEST_IDENTITY
+		)
+			.setEventData(
+				new HashMap<String, Object>() {
+					{
+						put(IdentityConstants.EventDataKeys.URL_VARIABLES, true);
+					}
+				}
+			)
+			.build();
+
+		assertTrue(EventUtils.isGetUrlVariablesRequestEvent(event));
+
+		// eventType is not edgeIdentity and eventSource is not requestIdentity
+		event =
+			new Event.Builder(
+				IdentityConstants.EventNames.IDENTITY_REQUEST_URL_VARIABLES,
+				IdentityConstants.EventType.EDGE_IDENTITY,
+				IdentityConstants.EventSource.REQUEST_IDENTITY
+			)
+				.setEventData(
+					new HashMap<String, Object>() {
+						{
+							put(IdentityConstants.EventDataKeys.URL_VARIABLES, false);
+						}
+					}
+				)
+				.build();
+
+		assertFalse(EventUtils.isGetUrlVariablesRequestEvent(event));
+	}
+
+	@Test
+	public void test_isRequestIdentityEventForGetUrlVariable_eventTypeNotEdgeIdentity_eventSourceNotIdentityRequest_eventContainsUrlVariablesKey_validBooleanValue_returnsSetBooleanValue() {
+		// eventType is not edgeIdentity and eventSource is not requestIdentity
+		Event event = new Event.Builder(
+			IdentityConstants.EventNames.IDENTITY_REQUEST_URL_VARIABLES,
+			IdentityConstants.EventType.IDENTITY,
+			IdentityConstants.EventSource.REQUEST_RESET
+		)
+			.setEventData(
+				new HashMap<String, Object>() {
+					{
+						put(IdentityConstants.EventDataKeys.URL_VARIABLES, true);
+					}
+				}
+			)
+			.build();
+
+		assertTrue(EventUtils.isGetUrlVariablesRequestEvent(event));
+
+		// eventType is not edgeIdentity and eventSource is not requestIdentity
+		event =
+			new Event.Builder(
+				IdentityConstants.EventNames.IDENTITY_REQUEST_URL_VARIABLES,
+				IdentityConstants.EventType.IDENTITY,
+				IdentityConstants.EventSource.REQUEST_IDENTITY
+			)
+				.setEventData(
+					new HashMap<String, Object>() {
+						{
+							put(IdentityConstants.EventDataKeys.URL_VARIABLES, true);
+						}
+					}
+				)
+				.build();
+
+		assertTrue(EventUtils.isGetUrlVariablesRequestEvent(event));
+	}
+
+	@Test
+	public void test_RequestIdentityEventForGetUrlVariable_eventContainsUrlVariablesKey_invalidValue_returnsFalse() {
+		Event event = new Event.Builder(
+			IdentityConstants.EventNames.IDENTITY_REQUEST_URL_VARIABLES,
+			IdentityConstants.EventType.EDGE_IDENTITY,
+			IdentityConstants.EventSource.REQUEST_IDENTITY
+		)
+			.setEventData(
+				new HashMap<String, Object>() {
+					{
+						put(IdentityConstants.EventDataKeys.URL_VARIABLES, "true");
+					}
+				}
+			)
+			.build();
+
+		assertFalse(EventUtils.isGetUrlVariablesRequestEvent(event));
+
+		// eventType is not edgeIdentity and eventSource is not requestIdentity
+		event =
+			new Event.Builder(
+				IdentityConstants.EventNames.IDENTITY_REQUEST_URL_VARIABLES,
+				IdentityConstants.EventType.EDGE_IDENTITY,
+				IdentityConstants.EventSource.REQUEST_IDENTITY
+			)
+				.setEventData(
+					new HashMap<String, Object>() {
+						{
+							put(IdentityConstants.EventDataKeys.URL_VARIABLES, 123);
+						}
+					}
+				)
+				.build();
+
+		assertFalse(EventUtils.isGetUrlVariablesRequestEvent(event));
+	}
+
+	@Test
+	public void test_getOrgID_validString_returnsString() {
+		assertEquals(
+			"org-id",
+			EventUtils.getOrgId(
+				new HashMap<String, Object>() {
+					{
+						put("experienceCloud.org", "org-id");
+					}
+				}
+			)
+		);
+	}
+
+	@Test
+	public void test_getOrgID_invalidValue_returnsNull() {
+		assertNull(
+			EventUtils.getOrgId(
+				new HashMap<String, Object>() {
+					{
+						put("experienceCloud.org", true);
+					}
+				}
+			)
+		);
+	}
+}
diff --git a/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityExtensionTests.java b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityExtensionTests.java
index 42dad796..9eb11092 100644
--- a/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityExtensionTests.java
+++ b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityExtensionTests.java
@@ -15,6 +15,7 @@
 import static com.adobe.marketing.mobile.edge.identity.IdentityTestUtil.buildUpdateIdentityRequest;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
 import static org.junit.Assert.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyString;
@@ -471,6 +472,177 @@ public void test_handleHubSharedState_doesNotShareStateIfLegacyECIDDoesNotChange
 			.setXDMSharedEventState(sharedStateCaptor.capture(), eq(event), any(ExtensionErrorCallback.class));
 	}
 
+	// ========================================================================================
+	// handleUrlVariablesRequest
+	// ========================================================================================
+
+	@Test
+	public void test_handleUrlVariablesRequest_nullEvent_shouldNotThrow() {
+		// test
+		extension.handleUrlVariablesRequest(null);
+	}
+
+	@Test
+	public void test_handleUrlVariablesRequest_whenConfigAndECIDNotPresent_returnsNull() {
+		// setup
+		Event event = new Event.Builder(
+			"Test event",
+			IdentityConstants.EventType.EDGE_IDENTITY,
+			IdentityConstants.EventSource.REQUEST_IDENTITY
+		)
+			.setEventData(
+				new HashMap<String, Object>() {
+					{
+						put("urlvariables", true);
+					}
+				}
+			)
+			.build();
+		final ArgumentCaptor<Event> responseEventCaptor = ArgumentCaptor.forClass(Event.class);
+
+		// test
+		extension.handleUrlVariablesRequest(event);
+
+		// verify
+		PowerMockito.verifyStatic(MobileCore.class, Mockito.times(1));
+		MobileCore.dispatchResponseEvent(
+			responseEventCaptor.capture(),
+			any(Event.class),
+			any(ExtensionErrorCallback.class)
+		);
+
+		Event urlVariablesResponseEvent = responseEventCaptor.getAllValues().get(0);
+		final Map<String, Object> data = urlVariablesResponseEvent.getEventData();
+		assertTrue(data.containsKey("urlvariables"));
+		String urlvariables = (String) data.get("urlvariables");
+
+		assertNull(urlvariables);
+	}
+
+	@Test
+	public void test_handleUrlVariablesRequest_whenOrgIdAndECIDPresent_returnsValidUrlVariablesString() {
+		// setup
+		ECID testECID = new ECID();
+		extension.state.getIdentityProperties().setECID(testECID);
+		setConfigurationSharedState("test-org-id@AdobeOrg");
+
+		Event event = new Event.Builder(
+			"Test event",
+			IdentityConstants.EventType.EDGE_IDENTITY,
+			IdentityConstants.EventSource.REQUEST_IDENTITY
+		)
+			.setEventData(
+				new HashMap<String, Object>() {
+					{
+						put("urlvariables", true);
+					}
+				}
+			)
+			.build();
+		final ArgumentCaptor<Event> responseEventCaptor = ArgumentCaptor.forClass(Event.class);
+
+		// test
+		extension.handleUrlVariablesRequest(event);
+
+		// verify
+		PowerMockito.verifyStatic(MobileCore.class, Mockito.times(1));
+		MobileCore.dispatchResponseEvent(
+			responseEventCaptor.capture(),
+			any(Event.class),
+			any(ExtensionErrorCallback.class)
+		);
+
+		Event urlVariablesResponseEvent = responseEventCaptor.getAllValues().get(0);
+		final Map<String, Object> data = urlVariablesResponseEvent.getEventData();
+		String urlvariables = (String) data.get("urlvariables");
+
+		String expectedUrlVariableTSString = "adobe_mc=TS%3";
+		String expectedUrlVariableIdentifiersString = "%7CMCMID%3D" + testECID + "%7CMCORGID%3Dtest-org-id%40AdobeOrg";
+
+		assertNotNull(urlvariables);
+		assertTrue(urlvariables.contains("adobe_mc="));
+		assertTrue(urlvariables.contains(expectedUrlVariableTSString));
+		assertTrue(urlvariables.contains(expectedUrlVariableIdentifiersString));
+	}
+
+	@Test
+	public void test_handleUrlVariablesRequest_whenOrgIdMissing_returnsValidNull() {
+		// setup
+		ECID testECID = new ECID();
+		extension.state.getIdentityProperties().setECID(testECID);
+
+		Event event = new Event.Builder(
+			"Test event",
+			IdentityConstants.EventType.EDGE_IDENTITY,
+			IdentityConstants.EventSource.REQUEST_IDENTITY
+		)
+			.setEventData(
+				new HashMap<String, Object>() {
+					{
+						put("urlvariables", true);
+					}
+				}
+			)
+			.build();
+		final ArgumentCaptor<Event> responseEventCaptor = ArgumentCaptor.forClass(Event.class);
+
+		// test
+		extension.handleUrlVariablesRequest(event);
+
+		// verify
+		PowerMockito.verifyStatic(MobileCore.class, Mockito.times(1));
+		MobileCore.dispatchResponseEvent(
+			responseEventCaptor.capture(),
+			any(Event.class),
+			any(ExtensionErrorCallback.class)
+		);
+
+		Event urlVariablesResponseEvent = responseEventCaptor.getAllValues().get(0);
+		final Map<String, Object> data = urlVariablesResponseEvent.getEventData();
+		String urlvariables = (String) data.get("urlvariables");
+
+		assertNull(urlvariables);
+	}
+
+	@Test
+	public void test_handleUrlVariablesRequest_whenECIDMissing_returnsValidNull() {
+		// setup
+		extension.state.getIdentityProperties().setECID(null);
+		setConfigurationSharedState("test-org-id@AdobeOrg");
+
+		Event event = new Event.Builder(
+			"Test event",
+			IdentityConstants.EventType.EDGE_IDENTITY,
+			IdentityConstants.EventSource.REQUEST_IDENTITY
+		)
+			.setEventData(
+				new HashMap<String, Object>() {
+					{
+						put("urlvariables", true);
+					}
+				}
+			)
+			.build();
+		final ArgumentCaptor<Event> responseEventCaptor = ArgumentCaptor.forClass(Event.class);
+
+		// test
+		extension.handleUrlVariablesRequest(event);
+
+		// verify
+		PowerMockito.verifyStatic(MobileCore.class, Mockito.times(1));
+		MobileCore.dispatchResponseEvent(
+			responseEventCaptor.capture(),
+			any(Event.class),
+			any(ExtensionErrorCallback.class)
+		);
+
+		Event urlVariablesResponseEvent = responseEventCaptor.getAllValues().get(0);
+		final Map<String, Object> data = urlVariablesResponseEvent.getEventData();
+		String urlvariables = (String) data.get("urlvariables");
+
+		assertNull(urlvariables);
+	}
+
 	// ========================================================================================
 	// handleUpdateIdentities
 	// ========================================================================================
@@ -586,6 +758,21 @@ public void test_processCachedEvents_returnsWhenNotBooted() {
 			.setXDMSharedEventState(any(Map.class), any(Event.class), any(ExtensionErrorCallback.class));
 	}
 
+	@Test
+	public void test_processAddEvent_nullEvent_returns() {
+		Map<String, Object> identityXDM = createXDMIdentityMap(new TestItem("space", "moon"));
+		MockIdentityState mockIdentityState = new MockIdentityState(new IdentityProperties(identityXDM));
+		extension.state = mockIdentityState;
+		mockIdentityState.hasBooted = true;
+
+		// test
+		extension.processAddEvent(null);
+
+		// verify
+		verify(mockExtensionApi, times(0))
+			.setXDMSharedEventState(any(Map.class), any(Event.class), any(ExtensionErrorCallback.class));
+	}
+
 	@Test
 	public void test_processCachedEvents_processesWhenBooted() {
 		Map<String, Object> identityXDM = createXDMIdentityMap(new TestItem("space", "moon"));
@@ -596,6 +783,21 @@ public void test_processCachedEvents_processesWhenBooted() {
 		// test
 		extension.processAddEvent(buildUpdateIdentityRequest(identityXDM));
 		extension.processAddEvent(buildRemoveIdentityRequest(identityXDM));
+		extension.processAddEvent(
+			new Event.Builder(
+				"Test event",
+				IdentityConstants.EventType.EDGE_IDENTITY,
+				IdentityConstants.EventSource.REQUEST_IDENTITY
+			)
+				.setEventData(
+					new HashMap<String, Object>() {
+						{
+							put("urlVariables", true);
+						}
+					}
+				)
+				.build()
+		);
 		extension.processAddEvent(
 			new Event.Builder(
 				"Test event",
@@ -648,4 +850,21 @@ private void setIdentityDirectSharedState(final String ecid) {
 				}
 			);
 	}
+
+	private void setConfigurationSharedState(final String orgId) {
+		when(
+			mockExtensionApi.getSharedEventState(
+				eq("com.adobe.module.configuration"),
+				any(Event.class),
+				any(ExtensionErrorCallback.class)
+			)
+		)
+			.thenReturn(
+				new HashMap<String, Object>() {
+					{
+						put("experienceCloud.org", orgId);
+					}
+				}
+			);
+	}
 }
diff --git a/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityStateTests.java b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityStateTests.java
index 0c028d0c..c425de6c 100644
--- a/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityStateTests.java
+++ b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityStateTests.java
@@ -18,6 +18,7 @@
 import static org.junit.Assert.assertNotEquals;
 import static org.junit.Assert.assertNotNull;
 import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.times;
@@ -95,6 +96,17 @@ public boolean setXDMSharedEventState(Map<String, Object> state, Event event) {
 			};
 	}
 
+	@Test
+	public void testHasBooted() {
+		IdentityState state = new IdentityState(new IdentityProperties());
+
+		// test
+		assertFalse(state.hasBooted());
+
+		state.bootupIfReady(mockSharedStateCallback);
+		assertTrue(state.hasBooted());
+	}
+
 	@Test
 	public void testBootupIfReady_GeneratesECID() {
 		// setup
diff --git a/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityTests.java b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityTests.java
index d27f9e5c..281bf0ef 100644
--- a/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityTests.java
+++ b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/IdentityTests.java
@@ -16,6 +16,7 @@
 import static org.junit.Assert.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 
+import android.util.Log;
 import com.adobe.marketing.mobile.AdobeCallback;
 import com.adobe.marketing.mobile.AdobeCallbackWithError;
 import com.adobe.marketing.mobile.AdobeError;
@@ -26,6 +27,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.TimeUnit;
 import org.json.JSONObject;
 import org.junit.Before;
 import org.junit.Test;
@@ -269,6 +271,189 @@ public void call(Object o) {}
 		assertEquals(AdobeError.UNEXPECTED_ERROR, errorCapture.get(KEY_CAPTUREDERRORCALLBACK));
 	}
 
+	// ========================================================================================
+	// getUrlVariables API
+	// ========================================================================================
+	@Test
+	public void testGetUrlVariables() throws InterruptedException {
+		// setup
+		final ArgumentCaptor<Event> eventCaptor = ArgumentCaptor.forClass(Event.class);
+		final ArgumentCaptor<AdobeCallback> adobeCallbackCaptor = ArgumentCaptor.forClass(AdobeCallback.class);
+		final ArgumentCaptor<ExtensionErrorCallback> extensionErrorCallbackCaptor = ArgumentCaptor.forClass(
+			ExtensionErrorCallback.class
+		);
+		final List<String> callbackReturnValues = new ArrayList<>();
+		final ADBCountDownLatch latch = new ADBCountDownLatch(1);
+		// test
+		Identity.getUrlVariables(
+			new AdobeCallback<String>() {
+				@Override
+				public void call(String s) {
+					callbackReturnValues.add(s);
+					latch.countDown();
+				}
+			}
+		);
+		latch.await(2000, TimeUnit.MILLISECONDS);
+		// verify
+		PowerMockito.verifyStatic(MobileCore.class, Mockito.times(1));
+		MobileCore.dispatchEventWithResponseCallback(
+			eventCaptor.capture(),
+			adobeCallbackCaptor.capture(),
+			extensionErrorCallbackCaptor.capture()
+		);
+
+		// verify the dispatched event details
+		Event dispatchedEvent = eventCaptor.getValue();
+		assertEquals(IdentityConstants.EventNames.IDENTITY_REQUEST_URL_VARIABLES, dispatchedEvent.getName());
+		assertEquals(IdentityConstants.EventType.EDGE_IDENTITY.toLowerCase(), dispatchedEvent.getType());
+		assertEquals(IdentityConstants.EventSource.REQUEST_IDENTITY.toLowerCase(), dispatchedEvent.getSource());
+		assertTrue(dispatchedEvent.getEventData().containsKey("urlvariables"));
+		assertTrue((boolean) dispatchedEvent.getEventData().get("urlvariables"));
+
+		// verify callback responses
+		Map<String, Object> urlVariablesResponse = new HashMap<>();
+		urlVariablesResponse.put("urlvariables", "test-url-variable-string");
+
+		adobeCallbackCaptor.getValue().call(buildUrlVariablesResponseEvent(urlVariablesResponse));
+		assertEquals("test-url-variable-string", callbackReturnValues.get(0));
+		// TODO - enable when ExtensionError creation is available
+		// should not crash on calling the callback
+		//extensionErrorCallback.error(ExtensionError.UNEXPECTED_ERROR);
+	}
+
+	@Test
+	public void testGetUrlVariables_nullCallback() {
+		// test
+		Identity.getExperienceCloudId(null);
+
+		// verify
+		PowerMockito.verifyStatic(MobileCore.class, Mockito.times(0));
+		MobileCore.dispatchEventWithResponseCallback(
+			any(Event.class),
+			any(AdobeCallback.class),
+			any(ExtensionErrorCallback.class)
+		);
+	}
+
+	@Test
+	public void testGetUrlVariables_nullResponseEvent() {
+		// setup
+		final String KEY_IS_ERRORCALLBACK_CALLED = "errorCallBackCalled";
+		final String KEY_CAPTUREDERRORCALLBACK = "capturedErrorCallback";
+		final Map<String, Object> errorCapture = new HashMap<>();
+		final ArgumentCaptor<AdobeCallback> adobeCallbackCaptor = ArgumentCaptor.forClass(AdobeCallback.class);
+		final AdobeCallbackWithError callbackWithError = new AdobeCallbackWithError() {
+			@Override
+			public void fail(AdobeError adobeError) {
+				errorCapture.put(KEY_IS_ERRORCALLBACK_CALLED, true);
+				errorCapture.put(KEY_CAPTUREDERRORCALLBACK, adobeError);
+			}
+
+			@Override
+			public void call(Object o) {}
+		};
+
+		// test
+		Identity.getUrlVariables(callbackWithError);
+
+		// verify if the event is dispatched
+		PowerMockito.verifyStatic(MobileCore.class, Mockito.times(1));
+		MobileCore.dispatchEventWithResponseCallback(
+			any(Event.class),
+			adobeCallbackCaptor.capture(),
+			any(ExtensionErrorCallback.class)
+		);
+
+		// set response event to null
+		adobeCallbackCaptor.getValue().call(null);
+
+		// verify
+		assertTrue((boolean) errorCapture.get(KEY_IS_ERRORCALLBACK_CALLED));
+		assertEquals(AdobeError.UNEXPECTED_ERROR, errorCapture.get(KEY_CAPTUREDERRORCALLBACK));
+	}
+
+	@Test
+	public void testGetUrlVariables_invalidEventData() {
+		// setup
+		final String KEY_IS_ERRORCALLBACK_CALLED = "errorCallBackCalled";
+		final String KEY_CAPTUREDERRORCALLBACK = "capturedErrorCallback";
+		final Map<String, Object> errorCapture = new HashMap<>();
+		final ArgumentCaptor<AdobeCallback> adobeCallbackCaptor = ArgumentCaptor.forClass(AdobeCallback.class);
+		final AdobeCallbackWithError callbackWithError = new AdobeCallbackWithError() {
+			@Override
+			public void fail(AdobeError adobeError) {
+				errorCapture.put(KEY_IS_ERRORCALLBACK_CALLED, true);
+				errorCapture.put(KEY_CAPTUREDERRORCALLBACK, adobeError);
+			}
+
+			@Override
+			public void call(Object o) {}
+		};
+
+		// test
+		Identity.getUrlVariables(callbackWithError);
+
+		// verify if the event is dispatched
+		PowerMockito.verifyStatic(MobileCore.class, Mockito.times(1));
+		MobileCore.dispatchEventWithResponseCallback(
+			any(Event.class),
+			adobeCallbackCaptor.capture(),
+			any(ExtensionErrorCallback.class)
+		);
+
+		// set response event data to not have urlvariables key
+		Map<String, Object> eventData = new HashMap<>();
+		eventData.put("someKey", "someValue");
+		eventData.put("urlvariables", true);
+		adobeCallbackCaptor.getValue().call(buildUrlVariablesResponseEvent(eventData));
+
+		// verify
+		assertTrue((boolean) errorCapture.get(KEY_IS_ERRORCALLBACK_CALLED));
+		assertEquals(AdobeError.UNEXPECTED_ERROR, errorCapture.get(KEY_CAPTUREDERRORCALLBACK));
+	}
+
+	@Test
+	public void testGetUrlVariables_NullUrlVariablesStringInResponseData() {
+		// setup
+		final String KEY_IS_ERRORCALLBACK_CALLED = "errorCallBackCalled";
+		final String KEY_CAPTUREDERRORCALLBACK = "capturedErrorCallback";
+		final Map<String, Object> errorCapture = new HashMap<>();
+		final ArgumentCaptor<AdobeCallback> adobeCallbackCaptor = ArgumentCaptor.forClass(AdobeCallback.class);
+		final AdobeCallbackWithError callbackWithError = new AdobeCallbackWithError() {
+			@Override
+			public void fail(AdobeError adobeError) {
+				errorCapture.put(KEY_IS_ERRORCALLBACK_CALLED, true);
+				errorCapture.put(KEY_CAPTUREDERRORCALLBACK, adobeError);
+			}
+
+			@Override
+			public void call(Object o) {
+				Log.d("test", "test");
+			}
+		};
+
+		// test
+		Identity.getUrlVariables(callbackWithError);
+
+		// verify if the event is dispatched
+		PowerMockito.verifyStatic(MobileCore.class, Mockito.times(1));
+		MobileCore.dispatchEventWithResponseCallback(
+			any(Event.class),
+			adobeCallbackCaptor.capture(),
+			any(ExtensionErrorCallback.class)
+		);
+
+		// set response event to have urlvariables map to null value
+		Map<String, Object> nullUrlVariablesData = new HashMap<>();
+		nullUrlVariablesData.put("urlvariables", null);
+		adobeCallbackCaptor.getValue().call(buildUrlVariablesResponseEvent(nullUrlVariablesData));
+
+		// verify
+		assertTrue((boolean) errorCapture.get(KEY_IS_ERRORCALLBACK_CALLED));
+		assertEquals(AdobeError.UNEXPECTED_ERROR, errorCapture.get(KEY_CAPTUREDERRORCALLBACK));
+	}
+
 	// ========================================================================================
 	// updateIdentities API
 	// ========================================================================================
@@ -581,4 +766,14 @@ private Event buildIdentityResponseEvent(final Map<String, Object> eventData) {
 			.setEventData(eventData)
 			.build();
 	}
+
+	private Event buildUrlVariablesResponseEvent(final Map<String, Object> eventData) {
+		return new Event.Builder(
+			IdentityConstants.EventNames.IDENTITY_REQUEST_URL_VARIABLES,
+			IdentityConstants.EventType.EDGE_IDENTITY,
+			IdentityConstants.EventSource.RESPONSE_IDENTITY
+		)
+			.setEventData(eventData)
+			.build();
+	}
 }
diff --git a/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/ListenerEdgeIdentityRequestIdentityTests.java b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/ListenerEdgeIdentityRequestIdentityTests.java
index 9c3911e2..91f32e66 100644
--- a/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/ListenerEdgeIdentityRequestIdentityTests.java
+++ b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/ListenerEdgeIdentityRequestIdentityTests.java
@@ -19,6 +19,7 @@
 
 import com.adobe.marketing.mobile.Event;
 import com.adobe.marketing.mobile.MobileCore;
+import java.util.HashMap;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
 import java.util.concurrent.TimeUnit;
@@ -70,6 +71,32 @@ public void testHear() throws Exception {
 		verify(mockIdentityExtension, times(1)).processAddEvent(event);
 	}
 
+	@Test
+	public void testHear_urlVariables() throws Exception {
+		// setup
+		Event event = new Event.Builder(
+			"Request Identity",
+			IdentityConstants.EventType.IDENTITY,
+			IdentityConstants.EventSource.REQUEST_IDENTITY
+		)
+			.setEventData(
+				new HashMap<String, Object>() {
+					{
+						put(IdentityConstants.EventDataKeys.URL_VARIABLES, true);
+					}
+				}
+			)
+			.build();
+		doReturn(mockIdentityExtension).when(listener).getIdentityExtension();
+
+		// test
+		listener.hear(event);
+
+		// verify
+		testExecutor.awaitTermination(100, TimeUnit.MILLISECONDS);
+		verify(mockIdentityExtension, times(1)).processAddEvent(event);
+	}
+
 	@Test
 	public void testHear_WhenParentExtensionNull() throws Exception {
 		// setup
diff --git a/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/URLUtilsTests.java b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/URLUtilsTests.java
new file mode 100644
index 00000000..fc4337d7
--- /dev/null
+++ b/code/edgeidentity/src/test/java/com/adobe/marketing/mobile/edge/identity/URLUtilsTests.java
@@ -0,0 +1,37 @@
+/*
+  Copyright 2022 Adobe. All rights reserved.
+  This file is licensed to you under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License. You may obtain a copy
+  of the License at http://www.apache.org/licenses/LICENSE-2.0
+  Unless required by applicable law or agreed to in writing, software distributed under
+  the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+  OF ANY KIND, either express or implied. See the License for the specific language
+  governing permissions and limitations under the License.
+*/
+
+package com.adobe.marketing.mobile.edge.identity;
+
+import static org.junit.Assert.assertEquals;
+
+import org.junit.Test;
+
+public class URLUtilsTests {
+
+	@Test
+	public void test_generateURLVariablesPayload_emptyValuesPassed_returnsStringWithURLPrefixOnly() {
+		String actual = URLUtils.generateURLVariablesPayload("", "", "");
+		assertEquals("adobe_mc=null", actual);
+	}
+
+	@Test
+	public void test_generateURLVariablesPayload_nullValuesPassed_returnsStringWithURLPrefixOnly() {
+		String actual = URLUtils.generateURLVariablesPayload(null, null, null);
+		assertEquals("adobe_mc=null", actual);
+	}
+
+	@Test
+	public void test_generateURLVariablesPayload_validStringValuesPassed_returnsStringWith_TS_ECID_ORGID() {
+		String actual = URLUtils.generateURLVariablesPayload("TEST_TS", "TEST_ECID", "Adobe-Test@OrgId");
+		assertEquals("adobe_mc=TS%3DTEST_TS%7CMCMID%3DTEST_ECID%7CMCORGID%3DAdobe-Test%40OrgId", actual);
+	}
+}

From 6932a2dd91a55f6a20f58a5416aab715e66387ec Mon Sep 17 00:00:00 2001
From: Arjun Bhadra <arjun.d.bhadra@gmail.com>
Date: Wed, 18 May 2022 12:12:42 -0700
Subject: [PATCH 2/4] [MOB-15818] Added documentation directory with getting
 started guide and api reference pages (#61)

* [MOB-15818] Added documentation directory with getting started guide and api reference pages

* [MOB-15818] Review fixes
---
 Documentation/api-reference.md   | 336 +++++++++++++++++++++++++++++++
 Documentation/getting-started.md |  60 ++++++
 2 files changed, 396 insertions(+)
 create mode 100644 Documentation/api-reference.md
 create mode 100644 Documentation/getting-started.md

diff --git a/Documentation/api-reference.md b/Documentation/api-reference.md
new file mode 100644
index 00000000..e98b7acb
--- /dev/null
+++ b/Documentation/api-reference.md
@@ -0,0 +1,336 @@
+# Adobe Experience Platform Identity for Edge Network Extension - Android
+
+## Prerequisites
+
+Refer to the [Getting Started Guide](getting-started.md)
+
+## API reference
+
+| APIs                                           |
+| ---------------------------------------------- |
+| [extensionVersion](#extensionVersion)          |
+| [getExperienceCloudId](#getExperienceCloudId)  |
+| [getIdentities](#getIdentities)                |
+| [getUrlVariables](#getUrlVariables)            |
+| [registerExtension](#registerExtension)        |
+| [removeIdentity](#removeIdentity)              |
+| [resetIdentities](#resetIdentities)            |
+| [updateIdentities](#updateIdentities)          |
+
+------
+
+### extensionVersion
+
+The extensionVersion() API returns the version of the Identity for Edge Network extension.
+
+#### Java
+
+##### Syntax
+```java
+public static String extensionVersion()
+```
+
+##### Example
+```java
+String extensionVersion = Identity.extensionVersion();
+```
+------
+
+### getExperienceCloudId
+
+This API retrieves the Experience Cloud ID (ECID) that was generated when the app was initially launched. This ID is preserved between app upgrades, is saved and restored during the standard application backup process, and is removed at uninstall.
+
+> The ECID value is returned via the `AdobeCallback`. When `AdobeCallbackWithError` is provided to this API, the timeout value is 500ms. If the operation times out or an unexpected error occurs, the `fail` method is called with the appropriate `AdobeError`.
+
+#### Java
+
+##### Syntax
+```java
+public static void getExperienceCloudId(final AdobeCallback<String> callback);
+```
+
+* _callback_ is invoked after the ECID is available. The callback may be invoked on a different thread.
+
+##### Example
+```java
+Identity.getExperienceCloudId(new AdobeCallback<String>() {    
+    @Override    
+    public void call(String id) {        
+         //Handle the ID returned here    
+    }
+});
+```
+
+------
+
+### getIdentities
+
+Get all the identities in the Identity for Edge Network extension, including customer identifiers which were previously added.
+
+> When `AdobeCallbackWithError` is provided, and you are fetching the identities from the Mobile SDK, the timeout value is 500ms. If the operation times out or an unexpected error occurs, the `fail` method is called with the appropriate `AdobeError`.
+
+#### Java
+
+##### Syntax
+```java
+public static void getIdentities(final AdobeCallback<IdentityMap> callback);
+```
+* _callback_ is invoked after the identities are available. The return format is an instance of [IdentityMap](api-reference.md#identitymap). The callback may be invoked on a different thread.
+
+##### Example
+```java
+Identity.getIdentities(new AdobeCallback<IdentityMap>() {    
+    @Override    
+    public void call(IdentityMap identityMap) {        
+         //Handle the IdentityMap returned here    
+    }
+});
+```
+
+------
+
+### getUrlVariables
+> :information_source: This API is available with version 1.1.0 and above.
+
+This API returns the identifiers in URL query parameter format for consumption in **hybrid mobile applications**. There is no leading & or ? punctuation as the caller is responsible for placing the variables in their resulting URL in the correct locations. If an error occurs while retrieving the URL variables, the callback handler will be called with a null value. Otherwise, the encoded string is returned, for example: `"adobe_mc=TS%3DTIMESTAMP_VALUE%7CMCMID%3DYOUR_ECID%7CMCORGID%3D9YOUR_EXPERIENCE_CLOUD_ID"`
+
+* The `adobe_mc` attribute is an URL encoded list that contains:
+  * `MCMID` - Experience Cloud ID \(ECID\)
+  * `MCORGID` - Experience Cloud Org ID
+  * `TS` - A timestamp taken when this request was made
+
+> :memo: When `AdobeCallbackWithError` is provided, and you are fetching the url variables from the Mobile SDK, the timeout value is 500ms. If the operation times out or an unexpected error occurs, the `fail` method is called with the appropriate `AdobeError`.
+
+#### Java
+
+##### Syntax
+```java
+public static void getUrlVariables(final AdobeCallback<String> callback);
+```
+* _callback_ has an NSString value that contains the visitor identifiers as a query string after the service request is complete.
+
+##### Example
+```java
+Identity.getUrlVariables(new AdobeCallback<String>() {    
+    @Override    
+    public void call(String urlVariablesString) {        
+        //handle the URL query parameter string here
+        //For example, open the URL in a webView  
+        WebView webView;
+        webView = (WebView)findViewById(R.id.your_webview); // initialize with your webView
+        webview.loadUrl("https://example.com?" + urlVariablesString);
+    }
+});
+```
+
+------
+
+### registerExtension
+
+Registers the Identity for Edge Network extension with the Mobile Core extension.
+
+> :information_source: 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://aep-sdks.gitbook.io/docs/foundation-extensions/identity-for-edge-network/identity-faq#q-i-am-using-aep-edge-and-adobe-solutions-extensions-which-identity-extension-should-i-install-and-register).
+
+#### Java
+
+##### Syntax
+```java
+public static void registerExtension()
+```
+
+##### Example
+```java
+import com.adobe.marketing.mobile.edge.identity.Identity
+
+...
+Identity.registerExtension();
+```
+
+------
+
+### removeIdentity
+
+Remove the identity from the stored client-side [IdentityMap](#identitymap). The Identity extension will stop sending the identifier to the Edge Network. Using this API does not remove the identifier from the server-side User Profile Graph or Identity Graph.
+
+Identities with an empty _id_ or _namespace_ are not allowed and are ignored.
+
+Removing identities using a reserved namespace is not allowed using this API. The reserved namespaces are:
+
+* ECID
+* IDFA
+* GAID
+
+#### Java
+
+##### Syntax
+```java
+public static void removeIdentity(final IdentityItem item, final String namespace);
+```
+
+##### Example
+```java
+IdentityItem item = new IdentityItem("user@example.com");
+Identity.removeIdentity(item, "Email");
+```
+
+------
+
+### resetIdentities
+
+Clears all identities stored in the Identity extension and generates a new Experience Cloud ID (ECID). Using this API does not remove the identifiers from the server-side User Profile Graph or Identity Graph.
+
+This is a destructive action, since once an ECID is removed it cannot be reused. The new ECID generated by this API can increase metrics like unique visitors when a new user profile is created.
+
+Some example use cases for this API are:
+* During debugging, to see how new ECIDs (and other identifiers paired with it) behave with existing rules and metrics.
+* A last-resort reset for when an ECID should no longer be used.
+
+This API is not recommended for:
+* Resetting a user's consent and privacy settings; see [Privacy and GDPR](https://aep-sdks.gitbook.io/docs/resources/privacy-and-gdpr).
+* Removing existing custom identifiers; use the [`removeIdentity`](#removeidentity) API instead.
+* Removing a previously synced advertising identifier after the advertising tracking settings were changed by the user; use the [`setAdvertisingIdentifier`](https://aep-sdks.gitbook.io/docs/foundation-extensions/mobile-core/identity/identity-api-reference#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://aep-sdks.gitbook.io/docs/foundation-extensions/mobile-core/mobile-core-api-reference#resetidentities) for more details.
+
+------
+
+### updateIdentities
+
+Update the currently known identities within the SDK. The Identity extension will merge the received identifiers with the previously saved ones in an additive manner, no identities are removed from this API.
+
+Identities with an empty _id_ or _namespace_ are not allowed and are ignored.
+
+Updating identities using a reserved namespace is not allowed using this API. The reserved namespaces are:
+
+* ECID
+* IDFA
+* GAID
+
+#### Java
+
+##### Syntax
+```java
+public static void updateIdentities(final IdentityMap identityMap);
+```
+
+##### Example
+```java
+IdentityItem item = new IdentityItem("user@example.com");
+IdentityMap identityMap = new IdentityMap();
+identityMap.addItem(item, "Email")
+Identity.updateIdentities(identityMap);
+```
+
+------
+
+## Public Classes
+
+### IdentityMap
+
+Defines a map containing a set of end user identities, keyed on either namespace integration code or the namespace ID of the identity. The values of the map are an array, meaning that more than one identity of each namespace may be carried.
+
+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).
+
+```text
+"identityMap" : {
+    "Email" : [
+      {
+        "id" : "user@example.com",
+        "authenticatedState" : "authenticated",
+        "primary" : false
+      }
+    ],
+    "Phone" : [
+      {
+        "id" : "1234567890",
+        "authenticatedState" : "ambiguous",
+        "primary" : false
+      },
+      {
+        "id" : "5557891234",
+        "authenticatedState" : "ambiguous",
+        "primary" : false
+      }
+    ],
+    "ECID" : [
+      {
+        "id" : "44809014977647551167356491107014304096",
+        "authenticatedState" : "ambiguous",
+        "primary" : true
+      }
+    ]
+  }
+```
+
+**Example**
+
+```java
+// Construct
+IdentityMap identityMap = new IdentityMap();
+
+// Add an item
+IdentityItem item = new IdentityItem("user@example.com");
+identityMap.addItem(item, "Email");
+
+// Remove an item
+IdentityItem item = new IdentityItem("user@example.com");
+identityMap.removeItem(item, "Email");
+
+// Get a list of items for a given namespace
+List<IdentityItem> items = identityMap.getIdentityItemsForNamespace("Email");
+
+// Get a list of all namespaces used in current IdentityMap
+List<String> namespaces = identityMap.getNamespaces();
+
+// Check if IdentityMap has no identities
+boolean hasNotIdentities = identityMap.isEmpty();
+```
+
+------
+
+### IdentityItem
+
+Defines an identity to be included in an [IdentityMap](#identitymap).
+
+The format of the IdentityItem class is defined by the [XDM Identity Item Schema](https://github.com/adobe/xdm/blob/master/docs/reference/datatypes/identityitem.schema.md).
+
+**Example**
+
+```java
+// Construct
+IdentityItem item = new IdentityItem("identifier");
+
+IdentityItem item = new IdentityItem("identifier", AuthenticatedState.AUTHENTICATED, false);
+
+
+// Getters
+String id = item.getId();
+
+AuthenticatedState state = item.getAuthenticatedState();
+
+boolean primary = item.isPrimary();
+```
+
+------
+
+### AuthenticatedState
+
+Defines the state an [Identity Item](api-reference.md#identityitem) is authenticated for.
+
+The possible authenticated states are:
+
+* Ambiguous - the state is ambiguous or not defined
+* Authenticated - the user is identified by a login or similar action
+* LoggedOut - the user was identified by a login action at a previous time, but is not logged in now
+
+**Syntax**
+
+```java
+public enum AuthenticatedState {
+    AMBIGUOUS("ambiguous"),
+    AUTHENTICATED("authenticated"),
+    LOGGED_OUT("loggedOut");
+}
+```
diff --git a/Documentation/getting-started.md b/Documentation/getting-started.md
new file mode 100644
index 00000000..c3aace0f
--- /dev/null
+++ b/Documentation/getting-started.md
@@ -0,0 +1,60 @@
+## Getting started
+
+The Adobe Experience Platform Identity for Edge Network extension has the following peer dependency, which must be installed prior to installing the identity extension:
+- [Mobile Core](https://aep-sdks.gitbook.io/docs/foundation-extensions/mobile-core)
+
+## 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.
+
+
+### 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:1.+'
+   implementation 'com.adobe.marketing.mobile:edge:1.+'
+   implementation 'com.adobe.marketing.mobile:edgeidentity:1.+'
+   ```
+
+2. Import the Mobile Core and Edge extensions in your Application class.
+
+   ```java
+    import com.adobe.marketing.mobile.MobileCore;
+    import com.adobe.marketing.mobile.Edge;
+    import com.adobe.marketing.mobile.edge.identity.Identity;
+   ```
+
+3. Register the Identity for Edge Extension with MobileCore:
+
+### Java
+
+```java
+public class MobileApp extends Application {
+
+    @Override
+    public void onCreate() {
+      super.onCreate();
+      MobileCore.setApplication(this);
+      try {
+        Edge.registerExtension();
+        Identity.registerExtension();
+        // register other extensions
+        MobileCore.start(new AdobeCallback () {
+            @Override
+            public void call(Object o) {
+                MobileCore.configureWithAppID("yourAppId");
+            }
+        });      
+
+      } catch (Exception e) {
+        ...
+      }
+
+
+    }
+}
+```

From ae66b883001a3a3626e7fc8f80a36771f5476e70 Mon Sep 17 00:00:00 2001
From: Arjun Bhadra <abhadra@adobe.com>
Date: Mon, 6 Jun 2022 18:29:31 -0700
Subject: [PATCH 3/4] Minor changes to setAdvertisingIdentifier API reference
 documentation

---
 Documentation/api-reference.md | 28 ++++++++++++++++++++--------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/Documentation/api-reference.md b/Documentation/api-reference.md
index c1c8aee0..de0f017b 100644
--- a/Documentation/api-reference.md
+++ b/Documentation/api-reference.md
@@ -216,6 +216,17 @@ public static void setAdvertisingIdentifier(final String advertisingIdentifier);
 - _advertisingIdentifier_ is an ID string that provides developers with a simple, standard system to continue to track ads throughout their apps.
 
 ##### Example
+<details>
+  <summary><code>import ...</code></summary>
+
+```java
+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 android.util.Log;
+```
+</details>
 
 ```java
 ...
@@ -234,20 +245,20 @@ public void onResume() {
                     if (!adInfo.isLimitAdTrackingEnabled()) {
                         advertisingIdentifier = adInfo.getId();
                     } else {
-                        MobileCore.log(LoggingMode.DEBUG, "ExampleActivity", "Limit Ad Tracking is enabled by the user, cannot process the advertising identifier");
+                        Log.d("ExampleActivity", "Limit Ad Tracking is enabled by the user, cannot process the advertising identifier");
                     }
                 }
 
             } catch (IOException e) {
                 // Unrecoverable error connecting to Google Play services (e.g.,
                 // the old version of the service doesn't support getting AdvertisingId).
-                MobileCore.log(LoggingMode.DEBUG, "ExampleActivity", "IOException while retrieving the advertising identifier " + e.getLocalizedMessage());
+                Log.e("ExampleActivity", "IOException while retrieving the advertising identifier " + e.getLocalizedMessage());
             } catch (GooglePlayServicesNotAvailableException e) {
                 // Google Play services is not available entirely.
-                MobileCore.log(LoggingMode.DEBUG, "ExampleActivity", "GooglePlayServicesNotAvailableException while retrieving the advertising identifier " + e.getLocalizedMessage());
+                Log.e("ExampleActivity", "GooglePlayServicesNotAvailableException while retrieving the advertising identifier " + e.getLocalizedMessage());
             } catch (GooglePlayServicesRepairableException e) {
                 // Google Play services is not installed, up-to-date, or enabled.
-                MobileCore.log(LoggingMode.DEBUG, "ExampleActivity", "GooglePlayServicesRepairableException while retrieving the advertising identifier " + e.getLocalizedMessage());
+                Log.e("ExampleActivity", "GooglePlayServicesRepairableException while retrieving the advertising identifier " + e.getLocalizedMessage());
             }
 
             MobileCore.setAdvertisingIdentifier(advertisingIdentifier);
@@ -270,11 +281,11 @@ public fun setAdvertisingIdentifier(advertisingIdentifier: String)
 
 ```kotlin
 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
+import android.util.Log
 ```
 </details>
 
@@ -290,11 +301,11 @@ suspend fun getGAID(applicationContext: Context): String {
         Log.d("ExampleActivity", "Limit Ad Tracking disabled; ad ID value: ${idInfo.id}")
         adID = idInfo.id
     } catch (e: GooglePlayServicesNotAvailableException) {
-        Log.d("ExampleActivity", "GooglePlayServicesNotAvailableException while retrieving the advertising identifier ${e.localizedMessage}")
+        Log.e("ExampleActivity", "GooglePlayServicesNotAvailableException while retrieving the advertising identifier ${e.localizedMessage}")
     } catch (e: GooglePlayServicesRepairableException) {
-        Log.d("ExampleActivity", "GooglePlayServicesRepairableException while retrieving the advertising identifier ${e.localizedMessage}")
+        Log.e("ExampleActivity", "GooglePlayServicesRepairableException while retrieving the advertising identifier ${e.localizedMessage}")
     } catch (e: IOException) {
-        Log.d("ExampleActivity", "IOException while retrieving the advertising identifier ${e.localizedMessage}")
+        Log.e("ExampleActivity", "IOException while retrieving the advertising identifier ${e.localizedMessage}")
     }
     Log.d("ExampleActivity", "Returning ad ID value: $adID")
     return adID
@@ -316,6 +327,7 @@ import kotlinx.coroutines.launch
 val scope = CoroutineScope(Dispatchers.IO).launch {
     val adID = sharedViewModel.getGAID(context.applicationContext)
     Log.d("ExampleActivity", "Sending ad ID value: $adID to MobileCore.setAdvertisingIdentifier")
+    
     MobileCore.setAdvertisingIdentifier(adID)
 }
 ```

From 9e2413efc088cd81f313c5a8ca11380460a19ae4 Mon Sep 17 00:00:00 2001
From: Arjun Bhadra <abhadra@adobe.com>
Date: Mon, 6 Jun 2022 19:15:09 -0700
Subject: [PATCH 4/4] Documentation format fixes

---
 Documentation/api-reference.md | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/Documentation/api-reference.md b/Documentation/api-reference.md
index de0f017b..218a5dc7 100644
--- a/Documentation/api-reference.md
+++ b/Documentation/api-reference.md
@@ -41,6 +41,7 @@ String extensionVersion = Identity.extensionVersion();
 
 This API retrieves the Experience Cloud ID (ECID) that was generated when the app was initially launched. This ID is preserved between app upgrades, is saved and restored during the standard application backup process, and is removed at uninstall.
 
+> **Note**
 > The ECID value is returned via the `AdobeCallback`. When `AdobeCallbackWithError` is provided to this API, the timeout value is 500ms. If the operation times out or an unexpected error occurs, the `fail` method is called with the appropriate `AdobeError`.
 
 #### Java
@@ -68,6 +69,7 @@ Identity.getExperienceCloudId(new AdobeCallback<String>() {
 
 Get all the identities in the Identity for Edge Network extension, including customer identifiers which were previously added.
 
+> **Note**
 > When `AdobeCallbackWithError` is provided, and you are fetching the identities from the Mobile SDK, the timeout value is 500ms. If the operation times out or an unexpected error occurs, the `fail` method is called with the appropriate `AdobeError`.
 
 #### Java
@@ -91,7 +93,8 @@ Identity.getIdentities(new AdobeCallback<IdentityMap>() {
 ------
 
 ### getUrlVariables
-> :information_source: This API is available with version 1.1.0 and above.
+> **Note**
+> This API is available with version 1.1.0 and above.
 
 This API returns the identifiers in URL query parameter format for consumption in **hybrid mobile applications**. There is no leading & or ? punctuation as the caller is responsible for placing the variables in their resulting URL in the correct locations. If an error occurs while retrieving the URL variables, the callback handler will be called with a null value. Otherwise, the encoded string is returned, for example: `"adobe_mc=TS%3DTIMESTAMP_VALUE%7CMCMID%3DYOUR_ECID%7CMCORGID%3D9YOUR_EXPERIENCE_CLOUD_ID"`
 
@@ -100,7 +103,8 @@ This API returns the identifiers in URL query parameter format for consumption i
   * `MCORGID` - Experience Cloud Org ID
   * `TS` - A timestamp taken when this request was made
 
-> :memo: When `AdobeCallbackWithError` is provided, and you are fetching the url variables from the Mobile SDK, the timeout value is 500ms. If the operation times out or an unexpected error occurs, the `fail` method is called with the appropriate `AdobeError`.
+> **Note**
+> When `AdobeCallbackWithError` is provided, and you are fetching the url variables from the Mobile SDK, the timeout value is 500ms. If the operation times out or an unexpected error occurs, the `fail` method is called with the appropriate `AdobeError`.
 
 #### Java
 
@@ -130,7 +134,8 @@ Identity.getUrlVariables(new AdobeCallback<String>() {
 
 Registers the Identity for Edge Network extension with the Mobile Core extension.
 
-> :information_source: 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://aep-sdks.gitbook.io/docs/foundation-extensions/identity-for-edge-network/identity-faq#q-i-am-using-aep-edge-and-adobe-solutions-extensions-which-identity-extension-should-i-install-and-register).
+> **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://aep-sdks.gitbook.io/docs/foundation-extensions/identity-for-edge-network/identity-faq#q-i-am-using-aep-edge-and-adobe-solutions-extensions-which-identity-extension-should-i-install-and-register).
 
 #### Java
 
@@ -191,7 +196,8 @@ This API is not recommended for:
 * Removing existing custom identifiers; use the [`removeIdentity`](#removeidentity) API instead.
 * Removing a previously synced advertising identifier after the advertising tracking settings were changed by the user; use the [`setAdvertisingIdentifier`](https://aep-sdks.gitbook.io/docs/foundation-extensions/mobile-core/identity/identity-api-reference#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://aep-sdks.gitbook.io/docs/foundation-extensions/mobile-core/mobile-core-api-reference#resetidentities) for more details.
+> **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.
 
 ------
 
@@ -327,7 +333,7 @@ import kotlinx.coroutines.launch
 val scope = CoroutineScope(Dispatchers.IO).launch {
     val adID = sharedViewModel.getGAID(context.applicationContext)
     Log.d("ExampleActivity", "Sending ad ID value: $adID to MobileCore.setAdvertisingIdentifier")
-    
+
     MobileCore.setAdvertisingIdentifier(adID)
 }
 ```