Adobe Analytics

Adobe Analytics is a powerful analytics solution that provides real-time analytics and detailed segmentation capabilities. Ensemble provides native integration with Adobe Analytics offering:

• Real-time analytics tracking
• User identity management
• Consent management
• User profile management
• Adobe Assurance integration
• Edge network support

Prerequisites

1. You have created an Adobe Experience Platform project
2. You have created an app on Ensemble Studio
3. You have Flutter (opens in a new tab) installed on your machine
4. You have a Simulator for testing

Adobe Experience Platform Setup

The following setup on Adobe Experience Platform is required regardless of whether you're enabling Adobe Analytics through Ensemble Studio or local development.

1. Get Adobe Experience Platform Configuration:

   • Navigate to Adobe Experience Platform → Data Collection → Mobile Properties
   • Create a new mobile property or select an existing one
   • Copy your configuration details including:
     • App ID

2. Configure Edge Network:

   • Set up your Edge Network configuration
   • Configure your datastreams
   • Set up your schema and datasets

Enable Adobe Analytics

In Ensemble Studio

If you're using Ensemble Studio for building your application, follow these steps to enable Adobe Analytics.

1. Navigate to Build & Deploy → Build Settings
2. Enable Adobe Analytics toggle in the Modules section
3. Enter Configuration Details:
   • Adobe Experience Platform App ID

In Local Project

If you're developing locally without using Ensemble Studio build system, follow these configuration steps.

1. Update ensemble_modules.dart:
   • Uncomment the Adobe Analytics import:

     import 'package:ensemble_adobe_analytics/adobe_analytics.dart';
   • Set useAdobeAnalytics to true:

     useAdobeAnalytics: true,
   • Initialize Adobe Analytics with your App ID:

     GetIt.I.registerSingleton<AdobeAnalyticsModule>(
       AdobeAnalyticsImpl(appId: "YOUR_APP_ID")
     );

Example Actions

Core Operations

Track Action (User Interactions)

Track event actions that occur in your application.

logEvent:
  name: trackButtonClick
  provider: adobe
  operation: trackAction
  parameters:
    eventName: 'button_click'
    eventType: 'button_click'
    eventSource: 'mobile_app'
    eventCategory: 'button_click'
    eventAction: 'button_click'
    eventLabel: 'button_click'

Track State (Page Views)

Track states that represent screens or views in your application.

logEvent:
  name: trackScreenView
  provider: adobe
  operation: trackState
  parameters:
    eventName: 'screen_view'
    eventType: 'screen_view'
    eventSource: 'mobile_app'

Edge Operations

Send an Experience event to Adobe Experience Platform Edge Network.

logEvent:
  name: trackXdmEvent
  provider: adobe
  operation: sendEvent
  parameters:
    xdmData:
      eventType: 'commerce.productViews'
      commerce:
        productViews:
          value: 1
    data:
      customField: 'customValue'
      userSegment:
        - 'segment1'
        - 'segment2'
    datastreamIdOverride: <your_datastream_id>

Identity Management

Get Experience Cloud ID

Retrieve the Experience Cloud ID (ECID) that was generated when the app was initially launched.

logEvent:
  name: getExperienceCloudId
  provider: adobe
  operation: getExperienceCloudId

Get URL Variables

Returns the identifiers in a URL's query parameters for consumption in hybrid mobile applications. The response will not return any leading & or ?, since the caller is responsible for placing the variables in the resulting URL in the correct locations. If an error occurs while retrieving the URL variables, the callback handler will return a null value. Otherwise, the encoded string is returned. An example of an encoded string is as follows: 'adobe_mc=TS%3DTIMESTAMP_VALUE%7CMCMID%3DYOUR_ECID%7CMCORGID%3D9YOUR_EXPERIENCE_CLOUD_ID'

• MCID: This is also known as the Experience Cloud ID (ECID).
• MCORGID: This is also known as the Experience Cloud Organization ID.
• TS: The timestamp that is taken when the request was made.

logEvent:
  name: getUrlVariables
  provider: adobe
  operation: getUrlVariables

Get All Identities

Get all identities in the Identity for Edge Network extension.

logEvent:
  name: getIdentities
  provider: adobe
  operation: getIdentities

Update Identities

Update the currently known identities within the SDK.

logEvent:
  name: updateIdentities
  provider: adobe
  operation: updateIdentities
  parameters:
    identities:
      CustomNamespace:
        - id: 'test-custom-id'
          authenticatedState: 'authenticated'
          primary: true
      CustomNamespace2:
        - id: 'test-custom-id-2'
          authenticatedState: 'authenticated'
          primary: false

Remove Identity

Remove the identity from the stored client-side 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

logEvent:
  name: removeIdentity
  provider: adobe
  operation: removeIdentity
  parameters:
    item:
      id: 'test-custom-id'
      authenticatedState: 'ambiguous'  # Options: 'authenticated', 'ambiguous', 'loggedOut'
      primary: false
    namespace: 'CustomNamespace'

Reset All Identities

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.
• Removing existing custom identifiers; use the removeIdentity API instead.
• Removing a previously synced advertising identifier after the advertising tracking settings were changed by the user; use the setAdvertisingIdentifier API instead.

ℹ️ The Identity for Edge Network extension does not read the Mobile SDK's privacy status and therefor setting the SDK's privacy status to opt-out will not clear the identities from the Identity for Edge Network extension.

logEvent:
  name: resetIdentities
  provider: adobe
  operation: resetIdentities

Set Advertising Identifier

When this API is called with a valid advertising identifier, the Identity for Edge Network extension includes the advertising identifier in the XDM Identity Map using the namespace GAID (Google Advertising ID) in Android and IDFA (Identifier for Advertisers) in iOS. If the API is called with the empty string (''), null/nil, or the all-zeros UUID string values, the advertising identifier is removed from the XDM Identity Map (if previously set). The advertising identifier is preserved between app upgrades, is saved and restored during the standard application backup process, and is removed at uninstall.

logEvent:
  name: setAdvertisingIdentifier
  provider: adobe
  operation: setAdvertisingIdentifier
  parameters:
    advertisingIdentifier: <your_advertising_identifier>

Consent Management

Get Current Consents

Retrieve the current consent preferences stored in the Consent extension.

logEvent:
  name: getConsents
  provider: adobe
  operation: getConsents

Update Consent

Merge the existing consents with the given consents.

logEvent:
  name: updateConsent
  provider: adobe
  operation: updateConsent
  parameters:
    allowed: true  # or false

Set Default Consent

Sets the default consent preferences for the Consent extension.

logEvent:
  name: setDefaultConsent
  provider: adobe
  operation: setDefaultConsent
  parameters:
    allowed: true  # or false

User Profile Management

Get User Attributes

Get user profile attributes which match the provided keys.

logEvent:
  name: getUserAttributes
  provider: adobe
  operation: getUserAttributes
  parameters:
    attributes:
      - 'firstName'
      - 'lastName'
      - 'email'

Update User Attributes

Set multiple user profile attributes.

logEvent:
  name: updateUserAttributes
  provider: adobe
  operation: updateUserAttributes
  parameters:
    attributeMap:
      firstName: 'John'
      lastName: 'Doe'
      email: 'john.doe@example.com'

Remove User Attributes

Remove provided user profile attributes if they exist.

logEvent:
  name: removeUserAttributes
  provider: adobe
  operation: removeUserAttributes
  parameters:
    attributes:
      - 'firstName'
      - 'lastName'

Adobe Assurance

Configure Adobe Assurance for debugging and validation.

logEvent:
  name: setupAssurance
  provider: adobe
  operation: setupAssurance
  parameters:
    url: <your_assurance_url>