diff --git a/Documentation/api-reference.md b/Documentation/api-reference.md index 76a32248..8860b955 100644 --- a/Documentation/api-reference.md +++ b/Documentation/api-reference.md @@ -91,7 +91,7 @@ Edge.getLocationHint(object: AdobeCallbackWithError { Registers the Edge Network extension with the Mobile Core extension. -> **Warning** +> **Warning** > Deprecated as of 2.0.0. Use the [MobileCore.registerExtensions API](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/MobileCore/api-reference.md) instead. @@ -135,6 +135,11 @@ See [MobileCore.resetIdentities](https://github.com/adobe/aepsdk-core-android/bl Sends an Experience event to the Adobe Experience Platform Edge Network. +Starting with `Edge` extension version **2.3.1** onwards, the `sendEvent` API supports optional Datastream overrides. This allows you to adjust your datastreams without the need for new ones or modifications to existing settings. The process involves two steps: + +1. Define your Datastream configuration overrides on the [datastream configuration page](https://experienceleague.adobe.com/docs/experience-platform/datastreams/configure.html). +2. Send these overrides to the Edge Network using the `sendEvent` API. + #### Java ##### Syntax @@ -151,9 +156,98 @@ public static void sendEvent(final ExperienceEvent experienceEvent, final EdgeCa Map xdmData = new HashMap<>(); xdmData.put("eventType", "SampleXDMEvent"); xdmData.put("sample", "data"); - + +ExperienceEvent experienceEvent = new ExperienceEvent.Builder() + .setXdmSchema(xdmData) + .build(); +``` +```java +// Example 1 - send the experience event without handling the Edge Network response +Edge.sendEvent(experienceEvent, null); +``` +```java +// Example 2 - send the experience event and handle the Edge Network response onComplete +Edge.sendEvent(experienceEvent, new EdgeCallback() { + @Override + public void onComplete(final List handles) { + // Handle the Edge Network response + } +}); +``` + +##### Example with Datastream ID override + +```java +// Create experience event from Map +Map xdmData = new HashMap<>(); +xdmData.put("eventType", "SampleXDMEvent"); +xdmData.put("sample", "data"); + +ExperienceEvent experienceEvent = new ExperienceEvent.Builder() + .setXdmSchema(xdmData) + .setDatastreamIdOverride("SampleDatastreamId") + .build(); +``` +```java +// Example 1 - send the experience event without handling the Edge Network response +Edge.sendEvent(experienceEvent, null); +``` +```java +// Example 2 - send the experience event and handle the Edge Network response onComplete +Edge.sendEvent(experienceEvent, new EdgeCallback() { + @Override + public void onComplete(final List handles) { + // Handle the Edge Network response + } +}); +``` + +##### Example with Datastream config override + +```java +// ----------------- Datastream config overrides map start ----------------- +Map configOverrides = new HashMap<>(); + +// com_adobe_experience_platform +Map experiencePlatform = new HashMap<>(); +Map datasets = new HashMap<>(); + +Map eventDataset = new HashMap<>(); +eventDataset.put("datasetId", "SampleEventDatasetIdOverride"); + +Map profileDataset = new HashMap<>(); +profileDataset.put("datasetId", "SampleProfileDatasetIdOverride"); + +datasets.put("event", eventDataset); +datasets.put("profile", profileDataset); + +experiencePlatform.put("datasets", datasets); +configOverrides.put("com_adobe_experience_platform", experiencePlatform); + +// com_adobe_analytics +Map analytics = new HashMap<>(); +analytics.put("reportSuites", new String[]{"rsid1", "rsid2", "rsid3"}); +configOverrides.put("com_adobe_analytics", analytics); + +// com_adobe_identity +Map identity = new HashMap<>(); +identity.put("idSyncContainerId", "1234567"); +configOverrides.put("com_adobe_identity", identity); + +// com_adobe_target +Map target = new HashMap<>(); +target.put("propertyToken", "SamplePropertyToken"); +configOverrides.put("com_adobe_target", target); +// ----------------- Datastream config overrides map end ----------------- + +// Create experience event from Map +Map xdmData = new HashMap<>(); +xdmData.put("eventType", "SampleXDMEvent"); +xdmData.put("sample", "data"); + ExperienceEvent experienceEvent = new ExperienceEvent.Builder() .setXdmSchema(xdmData) + .setDatastreamConfigOverride(configOverrides) .build(); ``` ```java @@ -165,10 +259,11 @@ Edge.sendEvent(experienceEvent, null); Edge.sendEvent(experienceEvent, new EdgeCallback() { @Override public void onComplete(final List handles) { - // Handle the Edge Network response + // Handle the Edge Network response } }); ``` + #### Kotlin #### Example @@ -189,17 +284,82 @@ Edge.sendEvent(experienceEvent, null) ```kotlin // Example 2 - send the experience event and handle the Edge Network response onComplete Edge.sendEvent(experienceEvent) { - // Handle the Edge Network response + // Handle the Edge Network response } ``` +##### Example with Datastream ID override + +```kotlin +// Create experience event from Map +val xdmData = mutableMapOf() +xdmData["eventType"] = "SampleXDMEvent" +xdmData["sample"] = "data" + +val experienceEvent = ExperienceEvent.Builder() + .setXdmSchema(xdmData) + .setDatastreamIdOverride("SampleDatastreamId") + .build() +``` +```kotlin +// Example 1 - send the experience event without handling the Edge Network response +Edge.sendEvent(experienceEvent, null) +``` +```kotlin +// Example 2 - send the experience event and handle the Edge Network response onComplete +Edge.sendEvent(experienceEvent) { + // Handle the Edge Network response +} +``` + +##### Example with Datastream config override + +```kotlin +// Create experience event from Map +val xdmData = mutableMapOf() +xdmData["eventType"] = "SampleXDMEvent" +xdmData["sample"] = "data" + +val configOverrides = mapOf( + "com_adobe_experience_platform" to mapOf( + "datasets" to mapOf( + "event" to mapOf("datasetId" to "SampleEventDatasetIdOverride"), + "profile" to mapOf("datasetId" to "SampleProfileDatasetIdOverride") + ) + ), + "com_adobe_analytics" to mapOf( + "reportSuites" to listOf("rsid1", "rsid2", "rsid3") + ), + "com_adobe_identity" to mapOf( + "idSyncContainerId" to "1234567" + ), + "com_adobe_target" to mapOf( + "propertyToken" to "SamplePropertyToken" + ) + ) + +val experienceEvent = ExperienceEvent.Builder() + .setXdmSchema(xdmData) + .setDatastreamConfigOverride(configOverrides) + .build() +``` +```kotlin +// Example 1 - send the experience event without handling the Edge Network response +Edge.sendEvent(experienceEvent, null) +``` +```kotlin +// Example 2 - send the experience event and handle the Edge Network response onComplete +Edge.sendEvent(experienceEvent) { + // Handle the Edge Network response +} +``` ------ ### setLocationHint Sets the Edge Network location hint used in requests to the Edge Network. Passing `null` or an empty string clears the existing location hint. Edge Network responses may overwrite the location hint to a new value when necessary to manage network traffic. -> **Warning** +> **Warning** > Use caution when setting the location hint. Only use valid [location hints for the `EdgeNetwork` scope](https://experienceleague.adobe.com/docs/experience-platform/edge-network-server-api/location-hints.html). An invalid location hint value will cause all Edge Network requests to fail with a `404` response code. #### Java @@ -295,13 +455,13 @@ Use this class when calling the [sendEvent](#sendevent) API with `EdgeCallback`. */ public class EdgeEventHandle { /** - * @return the payload type or null if not found in the {@link JSONObject} response - */ + * @return the payload type or null if not found in the {@link JSONObject} response + */ public String getType() {...} /** - * @return the event payload values for this {@link EdgeEventHandle} or null if not found in the {@link JSONObject} response - */ + * @return the event payload values for this {@link EdgeEventHandle} or null if not found in the {@link JSONObject} response + */ public List> getPayload() {...} } ``` @@ -322,44 +482,71 @@ public final class ExperienceEvent { } /** - * Sets free form data associated with this event to be passed to Adobe Experience Edge. - * - * @param data free form data, JSON like types are accepted - * @return instance of current builder - * @throws UnsupportedOperationException if this instance was already built - */ + * Sets free form data associated with this event to be passed to Adobe Experience Edge. + * + * @param data free form data, JSON like types are accepted + * @return instance of current builder + * @throws UnsupportedOperationException if this instance was already built + */ public Builder setData(final Map data) {...} /** - * Solution specific XDM event data for this event. - * - * @param xdm {@link Schema} information - * @return instance of current builder - * @throws UnsupportedOperationException if this instance was already built - */ + * Solution specific XDM event data for this event. + * + * @param xdm {@link Schema} information + * @return instance of current builder + * @throws UnsupportedOperationException if this instance was already built + */ public Builder setXdmSchema(final Schema xdm) {...} /** - * Solution specific XDM event data and dataset identifier for this event. - * - * @param xdm {@code Map} of raw XDM schema data - * @param datasetIdentifier The Experience Platform dataset identifier where this event is sent. - * If not provided, the default dataset defined in the configuration ID is used - * @return instance of current builder - * @throws UnsupportedOperationException if this instance was already built - */ + * Solution specific XDM event data and dataset identifier for this event. + * + * @param xdm {@code Map} of raw XDM schema data + * @param datasetIdentifier The Experience Platform dataset identifier where this event is sent. + * If not provided, the default dataset defined in the configuration ID is used + * @return instance of current builder + * @throws UnsupportedOperationException if this instance was already built + */ public Builder setXdmSchema(final Map xdm, final String datasetIdentifier) {...} /** - * Solution specific XDM event data for this event, passed as raw mapping of keys and - * Object values. - * - * @param xdm {@code Map} of raw XDM schema data - * @return instance of current builder - * @throws UnsupportedOperationException if this instance was already built - */ + * Solution specific XDM event data for this event, passed as raw mapping of keys and + * Object values. + * + * @param xdm {@code Map} of raw XDM schema data + * @return instance of current builder + * @throws UnsupportedOperationException if this instance was already built + */ public Builder setXdmSchema(final Map xdm) {...} + /** + * Override the default datastream identifier to send this event's data to a different datastream. + * + * When using {@link Edge#sendEvent}, this event is sent to the Experience Platform using the + * datastream identifier {@code datastreamIdOverride} instead of the default Experience Edge + * configuration ID set in the SDK Configuration key {@code edge.configId}. + * + * @param datastreamIdOverride Datastream identifier to override the default datastream identifier set in the Edge configuration + * @return instance of current builder + * @throws UnsupportedOperationException if this instance was already built + * + */ + public Builder setDatastreamIdOverride(final String datastreamIdOverride) {...} + + /** + * Override the default datastream configuration to trigger different datastream behaviors than the + * default ones for this event. + * + * When using {@link Edge#sendEvent}, this event is sent to the Experience Platform along with the + * datastream overrides defined in {@code datastreamConfigOverride}. + * + * @param datastreamConfigOverride Map defining datastream configuration overrides for this Experience Event + * @return instance of current builder + * @throws UnsupportedOperationException if this instance was already built + */ + public Builder setDatastreamConfigOverride(final Map datastreamConfigOverride) {...} + /** * Builds and returns a new instance of {@code ExperienceEvent}. * @@ -371,8 +558,12 @@ public final class ExperienceEvent { public Map getData() {...} - public Map getXdmSchema() {...} -} + public Map getXdmSchema() {...} + + public String getDatastreamIdOverride() {...} + + public Map getDatastreamConfigOverride() {...} +} ``` #### Java @@ -490,4 +681,4 @@ xdmData["sample"] = "data" val experienceEvent = ExperienceEvent.Builder() .setXdmSchema(xdmData, "datasetIdExample") .build() -``` \ No newline at end of file +``` diff --git a/Documentation/event-reference.md b/Documentation/event-reference.md index a7c567bb..6af4aad9 100644 --- a/Documentation/event-reference.md +++ b/Documentation/event-reference.md @@ -41,10 +41,25 @@ If the required `xdm` key is not present in the event data payload, the event is | --- | ---------- | -------- | ----------- | | xdm | Map | Yes | XDM formatted data; use an `XDMSchema` implementation for better XDM data ingestion and data format control. | | data | Map | No | Optional free-form data associated with this event. | +| config | Map | No | Optional config settings. Find the available keys for `config` below.| | datasetId | `String` | No | Optional custom dataset ID. If not set, the event uses the default Experience dataset ID set in the datastream configuration. | -| request | Map | No | Optional request parameters. | +| request | Map | No | Optional request parameters. Find the available keys for `request` below. | -> **Note** +config + +| Key | Value type | Required | Description | +| --- | ---------- | -------- | ----------- | +| datastreamIdOverride | `String` | No | Optional datastream identifier used to override the default datastream identifier set in the Edge configuration. | +| datastreamConfigOverride | Map | No | Optional datastream configuration used to override individual settings from the default datastream configuration. | + +request + +| Key | Value type | Required | Description | +| --- | ---------- | -------- | ----------- | +| path | `String` | No | Optional path to be used for the Edge request. | +| sendCompletion | `Boolean` | No | Optional flag to determine if a "complete" event is requested. | + +> **Note** > Events of this type and source are only processed if the data collection consent status stored in the `collect` property is **not** `n` (no); that is, either `y` (yes) or `p` (pending). ----- @@ -95,7 +110,7 @@ This event is a request to process and deliver a Consent update event to Edge Ne This event is a request to set the Edge Network location hint used by the Edge Network extension in requests to Edge Network. -> **Warning** +> **Warning** > Use caution when setting the location hint. Only use valid [location hints defined within the `EdgeNetwork` scope](https://experienceleague.adobe.com/docs/experience-platform/edge-network-server-api/location-hints.html). An invalid location hint value will cause all Edge Network requests to fail with a `404` response code. #### Event dispatched by @@ -126,7 +141,7 @@ This event contains the latest consent preferences synced with the SDK. The Edge | `p` | Pending | Hits are queued until `y`/`n` is set; when set, queued events follow the value's behavior | #### Event dispatched by -* [`Consent.update(Map consents)`](https://github.com/adobe/aepsdk-edgeconsent-android/blob/main/Documentation/api-reference.md#updateConsents) +* [`Consent.update(Map consents)`](https://github.com/adobe/aepsdk-edgeconsent-android/blob/main/Documentation/api-reference.md#updateConsents) #### Event details @@ -140,11 +155,11 @@ This event contains the latest consent preferences synced with the SDK. The Edge | --- | ---------- | -------- | ----------- | | consents | Map | No | XDM formatted consent preferences containing current collect consent settings. If not specified, defaults to `p` (pending) until the value is updated. | ------ +----- ### Edge identity reset complete -This event signals that [Identity for Edge Network](https://github.com/adobe/aepsdk-edgeidentity-android) has completed [resetting all identities](https://developer.adobe.com/client-sdks/documentation/identity-for-edge-network/api-reference/#resetidentities) usually following a call to [`MobileCore.resetIdentities()`](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/MobileCore/api-reference.md). +This event signals that [Identity for Edge Network](https://github.com/adobe/aepsdk-edgeidentity-android) has completed [resetting all identities](https://developer.adobe.com/client-sdks/documentation/identity-for-edge-network/api-reference/#resetidentities) usually following a call to [`MobileCore.resetIdentities()`](https://github.com/adobe/aepsdk-core-android/blob/main/Documentation/MobileCore/api-reference.md). When this event is received, the Edge extension queues it up and removes the cached internal `state:store` settings. If other events are queued before this event, those events will be processed first in the order they were received. @@ -183,7 +198,7 @@ This event is a response to the [Edge request identity event](#edge-request-iden | --- | ---------- | -------- | ----------- | | locationHint | `String` | Yes | The Edge Network location hint currently set for use when connecting to Edge Network. | ------ +----- ### Edge error response content @@ -202,7 +217,7 @@ This event is an error response to an originating event. If there are multiple e | requestId | `String` | Yes | The ID (`UUID`) of the batched Edge Network request tied to the event that triggered the error response. | | requestEventId | `String` | Yes | The ID (`UUID`) of the event that triggered the error response. | ------ +----- ### Edge response content @@ -234,7 +249,7 @@ This event tells the Edge Network extension to persist the event payload to the This event does not have standard keys. ------ +----- ### Edge location hint result @@ -270,4 +285,4 @@ This event is a response to an [Edge request content](#edge-request-content) eve | Key | Value type | Required | Description | | --- | ---------- | -------- | ----------- | -| requestId | `String` | Yes | The ID (`UUID`) of the batched Edge Network request tied to the event that requested the completion response. | \ No newline at end of file +| requestId | `String` | Yes | The ID (`UUID`) of the batched Edge Network request tied to the event that requested the completion response. |