Data Layer Management Using the ContextHub Tool

The Dynamic Tag Management (DTM) AEM ContextHub tool can be used for both ContextHub and generic data layer implementations. The ContextHub data layer schema is loaded by default in the tool and provides a simple integration with Adobe Experience Manager (AEM) ContextHub stores. Examples for both the default ContextHub implementation and a custom generic data layer implementation are provided.

Prerequisites

To use the ContextHub Tool, you must meet the following prerequisites:

  • An existing ContextHub or Javascript object data layer on a website.
  • A JSON schema that properly defines the data layer in use on the website.
  • An active DTM web property in use on the website.

AEM ContextHub Tool Components

The AEM ContextHub Tool adds two pieces of functionality to DTM:

  • The Data Layer Definition
  • The AEM ContextHub data layer type

Additionally, a new event type has been added to facilitate data layer monitoring called dataelementchanged. This event type can be used independently of the AEM ContextHub tool.

Each functional area corresponds to a configuration step described in both examples below.

Data Element Monitoring

The new dataelementchanged event type monitors any changes that occur to a specific data element value during a page view. The following observations should be noted when using this event type.

  1. The data element must map to a simple Javascript value. Complex values like arrays and objects that are returned in a data element custom script will not work correctly. Cookies, CSS selectors, and URL parameters also produce unexpected results and might not work at all. Simple values like strings and integers work fine.

  2. Be conservative in the number of dataelementchanged event types that are referenced on a single page. Although the monitoring is efficient, large numbers of evaluations could impact page performance.

  3. The dataelementchanged event type works only within the current page view because it is a DOM-based monitoring system.

  4. The data element monitor polls for the values.

ContextHub Data Layer Default Example

Example using the AEM ContextHub tool that references and uses the default ContextHub data layer within the Dynamic Tag Management configuration.

The ContextHub data layer will be loaded on a test Adobe Experience Manager (AEM) website, but ContextHub can be used independently of AEM. Contact your Adobe representative if you would like to use ContextHub independently of AEM.

All of the ContextHub stores can be referenced from the browser console.

The DTM data layer monitor starts before any other DTM functions, so the examples will not deploy the data layer through DTM even though it is possible to do so. Instead they will depend on the server-generated data layer. Otherwise Javascript warnings might occur because certain data layer values may not be available.

Define the Data Layer

The first step in configuring the AEM ContextHub tool is to add it to a web property.

Note: At this time only one AEM ContextHub tool is allowed per DTM web property.
  1. Click Web Property Name > Overview > Add a Tool > AEM ContextHub.

  2. Specify a descriptive name for the tool.

  3. Click Create Tool to display the AEM ContextHub Settings page.

  4. Select Use Default ContextHub Data Layer to leverage the standard ContextHub stores.

    Or

    Select Customize ContextHub Data Layer to modify the schema. It is necessary to use the customized option if a non-default ContextHub data layer is being used in the implementation.

    The default Data Layer Root enables access to all of the ContextHub stores. Given the dynamic nature of the ContextHub stores, there are additional functions available with this data layer that are not available in the simple Javascript object reference used by the generic data layer approach.

  5. (Conditional) To use a custom data layer, click Open Editor to view the data layer schema definition. If the custom data layer is a modification of the ContextHub schema be sure to add “ContextHub” in the Data Layer Root field.

    The default ContextHub schema is populated in the editor.

    1. Modify the schema as necessary to match the site data layer schema.

    2. Click Save and Close to save the schema and close the editor.

  6. Click Save Changes.

Create a Data Layer Data Element

  1. In the web property, click the Rules tab, then click Data Elements in the left menu.

  2. Click Create New Data Element.

  3. Specify a name for the data element. In this example, name the data element "total_price."

  4. From the Type drop-down list, select AEM ContextHub.

    The name of the AEM ContextHub Tool is populated in the “Source,” but only one AEM ContextHub Tool can be defined in the current version.

  5. Map the data element to the data layer by selecting a path in the Object selector.

    In this example, select the cart.totalPriceFloat object.

  6. Click Save Data Element.

Create an Event-Based Rule that Uses the Data Element Change Event Type

  1. In the web property, click the Rules tab, then click Event Based Rules in the left menu.

  2. Click Create New Rule.

  3. Name the rule. In this example, name the rule "cart_total_update."

  4. Expand the Conditions section.

  5. From the Event Type drop-down list, select dataelementchanged.

  6. Select the data element that was created in the previous section (total_price).

  7. Under Rule Conditions, select Data Element Value from the drop-down list, then click Add Criteria.

  8. Select the data element that was created in the previous section (total_price) and assign a value to cause the rule to fire.

    In this example, a regular expression is used to evaluate anything greater than or equal to 50: ^([5-9]\d|[1-9]\d{2,})$

    Note: If data element values are used in this way as conditions, it is important that the data element settings are considered in the match. For example, selecting the Force Lowercase Value option in the data element settings would convert the value to all lowercase before evaluation. Because Javascript is case sensitive “test” is not the same as “Test” and the condition would not fire as expected.
  9. Expand the Javascript / Third Party Tags section.

  10. Click Add New Script.

  11. Add a non-sequential Javascript that provides a notification if the rule fires. Name the rule “big_money_alert,” then add an alert script similar to the following example:

    alert('$' + _satellite.getVar(‘total_price’) + ‘ is big money!’);

  12. Click Save Code, then click Save Rule.

Validate the Implementation

On the DTM-enabled website that runs the above web property, validate the implementation.

  • In the developer console check for the existence of the data layer (ContextHub).

  • Change the data layer object that is being monitored to a value that does NOT match the condition above: ContextHub.setItem('/store/cart/totalPriceFloat','5');

  • Change the data layer object that is being monitored to a value that DOES match the condition above: ContextHub.setItem('/store/cart/totalPriceFloat','52');

  • In the example implementation, an alert box should appear:

If DTM debugging is turned on, the failed evaluation should appear in the console.

Custom Data Layer Example

Example using the AEM ContextHub tool that references and uses a custom, non-ContextHub data layer within the Dynamic Tag Management configuration.

The example data layer (_dl) will be loaded on the test web page as a Javascript object definition in the <head/> section of the page before the DTM embed code is referenced.

<head>
    <script>
        window._dl = {
            page: {
                name: 'homepage',
                quantity: 1,
                friend: 'No one' }
        }
    </script>
    <script src="//assets.adobedtm.com/satelliteLib-*.js"></script>
</head>

The DTM data layer monitor (see below) starts before any other DTM functions, so the examples will not deploy the data layer through DTM. Otherwise Javascript warnings might occur because certain data layer values may not be available.

Define the Data Layer

The first step in configuring the AEM ContextHub tool is to add it to a web property.

Note: At this time only one AEM ContextHub tool is allowed per DTM web property.
  1. Click Web Property Name > Overview > Add a Tool > AEM ContextHub.

  2. Specify a descriptive name for the tool.

  3. Click Create Tool to display the AEM ContextHub Settings page.

  4. Select Customize ContextHub Data Layer to modify the schema.

    A root Javascript object name must be added to the Data Layer Root field for non-ContextHub data layers. The _dl definition is used in the generic examples in this section.

  5. Click Open Editor to view the data layer schema definition.

    By default, the default ContextHub schema is populated in the editor.

  6. Delete the default schema and paste in the site data layer schema.

    The following sample non-ContextHub schema is used in the generic examples:

    {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "type": "object",
      "properties": {
        "page": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "quantity": {
              "type": "number"
            },
            "friend": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "quantity",
            "friend"
          ]
        }
       },
      "required": [
        "page"
      ]
    }
    
  7. Click Save and Close to save the schema and close the editor, then click Save Changes.

Create a Data Layer Data Element

  1. In the web property, click the Rules tab, then click Data Elements in the left menu.

  2. Click Create New Data Element.

  3. Specify a name for the data element. In this example, name the data element "my_friend."

  4. From the Type drop-down list, select AEM ContextHub.

    The name of the AEM ContextHub Tool is populated in the “Source,” but only one AEM ContextHub Tool can be defined in the current version.

  5. Map the data element to the data layer by selecting a path in the Object selector.

    In this example, select the page.friend object.

  6. Click Save Data Element.

Create an Event-Based Rule that Uses the Data Element Change Event Type

  1. In the web property, click the Rules tab, then click Event Based Rules in the left menu.

  2. Click Create New Rule.

  3. Name the rule. In this example, name the rule "find_a_friend."

  4. Expand the Conditions section.

  5. From the Event Type drop-down list, select dataelementchanged.

  6. Select the data element that was created in the previous section (my_friend).

  7. Under Rule Conditions, select Data Element Value from the drop-down list, then click Add Criteria.

  8. Select the data element that was created in the previous section (my_friend) and assign a value to cause the rule to fire.

    In this example use “Carl” as the value.

    Note: If data element values are used in this way as conditions, it is important that the data element settings are considered in the match. For example, selecting the Force Lowercase Value option in the data element settings would convert the value to all lowercase before evaluation. Because Javascript is case sensitive “test” is not the same as “Test” and the condition would not fire as expected.
  9. Expand the Javascript / Third Party Tags section.

  10. Click Add New Script.

  11. Add a non-sequential Javascript that provides a notification if the rule fires. Name the rule “found_my_friend,” then add an alert script similar to the following example:

    alert(_satellite.getVar(‘my_friend’) + ‘ is my friend.’);

  12. Click Save Code, then click Save Rule.

Validate the Implementation

On the DTM-enabled website that runs the above web property, validate the implementation.

  • In the developer console check for the existence of the data layer (_dl).

  • Change the data layer object that is being monitored to the value that was set in the condition above (_dl.page.friend = ‘Carl’).

    • In the example implementation, an alert box should appear:

  • Change the object to a different value (_dl.page.friend = ‘Bob’) and no alert should display.

    Note: If DTM debugging is turned on, the failed evaluation should appear in the console.
  • Change the object to a lowercase value of the match (_dl.page.friend = ‘carl’) and no alert should display.

  • Change the object to the correct case value of the match (_dl.page.friend = ‘Carl’) and the alert should once again display.