Adobe Experience Platform Web SDK Tag Setup Guide

Adobe Experience Platform Web SDK (Adobe Alloy) is a client-side JavaScript library that allows customers of the Adobe Experience Cloud to interact with the various services in the Experience Cloud through the Adobe Experience Platform Edge Network.

Tag tips

• Use mappings to override standard config values and set custom parameters.
• If you are configuring multiple instances, you must provide a unique Datastream ID and Org ID for each instance. Provide multiple values in a comma-separated list.

How it works

Mapping destinations are represented with a dot notation. The final API payload consists of a series of nested JSON objects based on the dot notation represented in the tag.

The Adobe Experience Platform Web SDK tag includes the following mappings specific to the Adobe application you are using and include XDM and non-XDM data mappings. XDM data is an object whose content and structure matches a schema you have created within Adobe Experience Platform.

• XDM Event triggers: Use to trigger events with a specific eventType value.
• Event-specific parameters: Use to map both XDM and non-XDM attributes for specific events.
• Analytics XDM data: Use to map data to be passed in the XDM object.
• Target Data: Use to map non-XDM attributes to be passed in the data object to update a Target profile or send Target Recommendations attributes.

For more information about sending XDM and non-XDM data to Adobe, see Track Events in the Adobe documentation.

Event example

Configure Adobe Experience Platform Web SDK events by selecting a variable that maps to an event and then specifying a trigger. Events are triggered when the variable is equal to a specific value, passing the chosen event name as eventType.

Use case: Purchase event with XDM Event Triggers

To set up a purchase event:

1. Navigate to the Data Mappings screen of the Adobe Experience Platform Web SDK tag configuration.
2. Select tealium_event from the variable drop-down list and click Select a Destination.
3. In the Category section, select XDM Event Triggers.
4. Set the When mapped variable equals field to Purchase. This is the value tealium_event must equal to trigger a purchase.
5. In the Trigger event drop-down list, select Purchases (commerce.purchases) under the sendEvent: Commerce Events section. This is the event that is triggered when tealium_event equals a purchase event.

Use case: Purchase event with Event-specific Parameters

If you need to send data with the purchase event that is not already included in the existing E-Commerce extension mappings, use Event-specific Parameters. Select an attribute from the list or enter a custom destination. Ensure you follow the specific dot notation for the given event and attribute.

The following example passes purchaseOrderNumber as XDM data with the purchase event:

1. Navigate to the Data Mappings screen of the Adobe Experience Platform Web SDK tag configuration.
2. Select po_number (or the relevant client-specific data layer element) from the variable drop-down list and click Select a Destination.
3. In the Category section, select Event-specific Parameters.
4. Because purchaseOrderNumber is not one of the default destinations, you must enter a Custom Parameter. Select Custom from the Parameter drop-down and enter the full dot notation path for the destination: commerce.purchases.xdm.commerce.order.purchaseOrderNumber.
5. In the For event drop-down list, select the event Purchases.
6. Click Add to add the parameter

Use case: Non-XDM data/Adobe Target data

Non-XDM, or Target data, can also be set using event mapping. In this use case, we will also send product_brand for use in Adobe Target.

1. Navigate to the Data Mappings screen of the Adobe Experience Platform Web SDK tag configuration.
2. Select product_brand from the variable drop-down list and click Select a Destination.
3. In the Category section, select Target Data.
4. Select entity.brand as the mapping destination.
5. The purchase event sent to the Adobe Web SDK will now include data.__adobe.target.entity.brand in the payload.

The following examples shows the resulting Adobe Web SDK call, including some default mappings from the E-Commerce extension. This example shows how the Adobe dot notation is broken out into a nested object for commerce.purchases.xdm.commerce.order.purchaseOrderNumber.

alloy("sendEvent",{
  "xdm":{
    "commerce":{
      "order":{
        "purchaseID":"123456789",
        "currencyCode":"USD",
        "priceTotal":39.98,
        "purchaseOrderNumer":"A1234"
      }
    },
    "productListItems":[
      {
        "SKU":"HT105",
        "name":"The Big Floppy Hat",
        "priceTotal":29.99,
        "quantity":1
      }
    ]
  },
  "data":{
    __adobe: {
      target: {
        "entity.brand": "Acme"
      }
    }
  }
});

Manage Flicker with Adobe Target

Loading the Adobe Experience Platform Web SDK asynchronously can cause content flicker, as previously loaded content could be updated by Adobe Target. To minimize flicker, Adobe recommends adding a prehiding snippet. Add this snippet to the utag.sync.js template with a JavaScript extension.

For more information about utag.sync.js, see How utag.sync.js works.

For information about the prehiding snippet, see Manage Flicker.

Blank page error when using a Cookie Management Solution

When using a cookie management solution (CMS) to ensure that tags are not triggered until the user has consented to different cookie categories, the prehiding snippet loads, rendering a blank page until it times out (3-7 seconds). The reason for this behavior is that the Adobe Experience Platform Web SDK tag cannot be loaded until the user accepts consent.

The solution consists of checking if consent has been given and, based on consent, triggering the prehiding snippet or not.

If you use a custom CMS external to Tealium, manage consent checking through that CMS platform.

If you use the Tealium JavaScript extension, update the logic so that the function is triggered only if the consent cookie contains a specific value, representing the user consent for the cookie category to which the AEP Web SDK tag belongs (for example, the functional cookie’s category).

Example

In this example, the CMS sets a cookie called mycms_cookie that contains the value functional:1 if the user has accepted the usage of the functional cookies or all:1 if the user has accepted all the cookies.

The following code checks for those values to trigger the prehiding snippet.

There are comments in the example that identify lines of code that need to be modified for your configuration.

!function(e,a,n,t){
  if (a) return;
  //Check if the cookie exists, and if it does, get its value. Update the mycms_cookie bit with the actual name of your CMS's cookie.
  var cms_cookie_value = (document.cookie.match(/^(?:.*;)?\s*mycms_cookie\s*=\s*([^;]+)(?:.*)?$/)||[,null])[1];
  if(cms_cookie_value){
    //Add the accepted values to an array. In the example below, the cookie value must contain either all:1 or functional:1 to trigger the prehidding snippet.     
    var accepted_values = ['all:1','functional:1'];
    for(var i=0;i<accepted_values.length;i++){
      if(cms_cookie_value.includes(accepted_values[i])){
        var x=e.head;
        if(x){
          var o=e.createElement("style");
          o.id="alloy-prehiding";
          o.innerText=n;
          x.appendChild(o);
          setTimeout(function(){o.parentNode&&o.parentNode.removeChild(o)},t);
          return;
        }
      }
    }
  }
}

(document, document.location.href.indexOf("adobe_authoring_enabled") !== -1, "body { opacity: 0 !important }", 3000);

Update the "body { opacity: 0 !important }" code with the element to target, such as a specific div. Otherwise, the default behavior of the code is to hide the whole body of the content.

Adobe Analytics migration guide

The Adobe Analytics tag is a legacy tag replaced by the Adobe Experience Platform Web SDK tag. The Adobe Experience Platform Web SDK tag sends data to Adobe Analytics by translating the Experience Data Model (XDM) into an Adobe Analytics format.

The Adobe Experience Platform Web SDK tag supports legacy variables, properties, and events.

Code comparison

The following examples show the structural differences between calls in Adobe Analytics and Adobe Experience Platform Web SDK:

Adobe Analytics

// Load the AppMeasurement library
var s = new AppMeasurement();
// Set the report suite ID
s.account = "example-rsid";
// Set the page name
s.pageName = "Home Page";
// Set other variables as needed
s.prop1 = "value1";
s.eVar1 = "value2";
s.hellow = "value3";
// Send the data to Adobe Analytics servers
var s_code = s.t();
if (s_code) document.write(s_code);

Adobe Experience Platform Web SDK

window.alloy("sendEvent", {
    // Set the type of event
    type: "viewStart",
    // Set the data for Adobe Analytics
    xdm: {
      web: {
        webPageDetails: {
          // Set the page name
          name: "Home Page"
        }
      },
      _experience: {
        analytics: {
          customDimensions: {
            props: {
              prop1: "value1"
            },
            eVars: {
              eVar1: "value2"
            }
          }
        }
      },
    },
    data: {
      // Set other variables as needed
      hellow: "value3",
    }
  });

Migrate the Adobe Analytics tag using Tealium Tools

Using the Adobe Experience Platform Web SDK Migrator tool, you can migrate existing Adobe Analytics AppMeasurement tags into the Adobe Experience Platform Web SDK tag.

Before using the Migrator Tool, note the following limitations:

• This tool does not migrate doPlugins or extensions. If your configuration uses doPlugins or extensions, you will need to migrate those manually. For instructions on migrating these elements, see the Migrate events globally section of the Adobe documentation).
• The link_name and link_trackvars variables are not supported.
• products variables must to be split into different attributes before they can be manually mapped as per Adobe specifications in the Adobe Experience Platform Web SDK tag. For more information, see products in the Adobe documentation.
• Any events and attributes that do not automatically migrate with the tool will have an empty mapping. You can manually map these empty attributes using the Migrate the Adobe Analytics tag manually guide.

Complete the following steps to migrate your Adobe Analytics tag using Tealium Tools:

1. Add the Adobe Experience Platform Web SDK Migrator to your Tealium Tools using the JSON definition at the following URL: https://solutions.tealium.net/hosted/tealiumTools/aep_migrate/aep_migrate.json. For more information about adding custom tools, see Manage Custom Tools.
2. Go to iQ Tag Management > Tags and launch the Adobe Experience Platform Web SDK Migrator tool.
3. To disable your existing Adobe Analytics tag as part of the migration, select Disable existing tag.
4. Select the scope for the migration:
   • All AppMeasurement Tags
   • All Active AppMeasurement Tags
   • Specific AppMeasurement Tag (You will need to add the tag UID for the tag you want to migrate.)
5. Click Start.
   The Migrator tool will automatically migrate existing Adobe Analytics AppMeasurement tags into the Adobe Experience Platform Web SDK tag.
6. Save and publish your profile.

If your configuration uses doPlugins or extensions, you will need to migrate those manually (see below).

Migrate the Adobe Analytics tag manually

To migrate from the Adobe Analytics tag to the Adobe Experience Platform Web SDK tag manually, complete the following steps.

This migration guide uses the following example data mappings in the Adobe Analytics tag:

1. Go to the Tag Marketplace to add a new Adobe Experience Platform Web SDK tag. For more information, see About tags.
2. Configure the following tag settings in Tealium:
   • Org ID: Your Adobe-assigned Experience Cloud organization ID. For example, XXX@AdobeOrg.
   • Datastream ID: Your Adobe-assigned datastream ID, which links the SDK to the appropriate accounts and configuration. Also referred to as the edgeConfigId.
3. Configure the following settings in Adobe Experience Platform:
   1. Go to Datastreams and select the datastream you want to use in the migration.
   2. In your Datastream Configure screen, note the Event Schema used in your datastream and click Save.

      

   3. In the Datastream details screen, ensure your Adobe Analytics service is enabled and select the service.

      

   4. In the Adobe Analytics service screen, enter the Adobe Report Suite ID that points to the appropriate data stores.

      

   5. Go to Data Management > Schemas and select the Event Schema that is linked to your datastream.
   6. Ensure that Field Groups includes the Adobe Analytics ExperienceEvent Template field group.

      

4. In this example, you would map the following legacy attributes, properties, and events to the Adobe Experience Platform Web SDK tag in Tealium. For more information, see About data mappings.
   1. In the Adobe Experience Platform Web SDK tag, go to Data Mappings.
   2. Select the sf (js) variable and map it to Analytics eVars > evar181 then click Done.
   3. Select the page_category (js) variable and map to Analytics Props > prop5 and lick Done.
   4. Select the medallia_custom_event(js) variable and XDM Event Trigger. Configure the mapping using the following values and click Done:
      • Add MDigital_Invite_Displayed:_experience.analytics.event101to200 as a custom destination.
      • When mapped variables equals: MDigital_Invite_Displayed
      • Trigger event: Experience Analytics Events 101-200 (_experience.analytics.event101to200)
      • Custom event name: 200
   5. Select the page_category (js) variable and configure the mapping using the following values and click Done:
      • Add xdm._experience.analytics.customDimension and data.channel as custom destinations.
      • Go to Non-XDM/Custom Schema and for Non-XDM/Custom Schema Path enter channel.
5. Click Finish.
6. Disable your Adobe Analytics tag.
7. Save and publish.

For more information about configuring Adobe Experience Platform Datastream, services, and schemas, see the following articles in the Adobe documentation:

• Configure a Datastream
• Create and edit schemas in the UI
• Adobe Analytics settings

Tag configuration

Navigate to the Tag Marketplace to add a new tag. For more information, see About tags.

When adding the tag, configure the following settings:

• Tag Version: Select the appropriate tag version. The default is the latest version.
• Instance Name: The namespace for your SDK. The default is alloy.
• Org ID: Your Adobe-assigned Experience Cloud organization ID. For example, XXX@AdobeOrg.
• Edge Domain: The domain that will be used to interact with Adobe services. Update the default setting if you mapped one of your first-party domains (using CNAME) to an Adobe-provisioned domain.
• Datastream ID: Your Adobe-assigned datastream ID, which links the SDK to the appropriate accounts and configuration. Also referred to as the edgeConfigId.
• Debug Enabled: Enables debugging messages to be displayed in the browser’s JavaScript console.
• Edge Base Path: Configured in your Adobe account. The default is ee.
• Auto Pageview Tracking: Fires the web.webpagedetails.pageViews event automatically for every page view.
• Auto Purchase Tracking: Fires the commerce.purchases event automatically whenever an order ID is present.

Load rules

Load the tag on all pages or set conditions for when your tag will load. For more information, see About load rules.

Data mappings

Mapping is the process of sending data from a data layer variable to the corresponding destination variable of the vendor tag. For more information, see About data mappings.

The available categories are:

Standard

Data Collection

E-Commerce

Privacy Options

Personalization Options

Audiences Options

Identity Options

identityMap Parameters

XDM Event Triggers

Analytics XDM Data

Target Data (non-XDM, data object)

Analytics eVars

This connector supports direct mapping for eVar1-eVar250. For example, mapping destinations will expand to _experience.analytics.customDimensions.eVars.eVar1-250.

Analytics Props

This connector supports direct mapping for prop1-prop75. For example, mapping destinations will expand to _experience.analytics.customDimensions.props.prop1-75

XDM (Legacy)

Adobe Audience Manager Config (Legacy)