ÃÛ¶¹ÊÓƵ

DocumentationAEMCore Components Guide

Using the ÃÛ¶¹ÊÓƵ Client Data Layer with the Core Components data-layer-core-components

Last update: Fri Oct 01 2021 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer
  • Admin

The goal of the ÃÛ¶¹ÊÓƵ Client Data Layer is to reduce the effort to instrument websites by providing a standardized method to expose and access any kind of data for any script.

The ÃÛ¶¹ÊÓƵ Client Data Layer is platform agnostic, but is fully integrated into the Core Components for use with AEM.

Like the Core Components, the code for the ÃÛ¶¹ÊÓƵ Client Data Layer is available on GitHub along with its developer documentation. This document gives an overview of how the Core Components interact with the Data Layer, but full technical details are deferred to the GitHub documentation.

TIP
For further information about the ÃÛ¶¹ÊÓƵ Client Data Layer,
For further technical details about the integration of the ÃÛ¶¹ÊÓƵ Client Data Layer with the Core Components, see the file in the Core Components repository.

Installation and Activation installation-activation

As of Core Components release 2.9.0, the Data Layer is distributed with the Core Components as an AEM Client Library and no installation is necessary. All projects generated by the AEM Project Archetype v. 24+ include an activated Data Layer by default.

To manually activate the Data Layer you must create a context-aware configuration for it:

  1. Create the following structure below the /conf/<mySite> folder, where <mySite> is the name of your Site’s project:

    • /conf/<mySite>/sling:configs/com.adobe.cq.wcm.core.components.internal.DataLayerConfig
    • Where each node has a jcr:primaryType set to nt:unstructured.

  2. Add a boolean property called enabled and set it to true.

    Location of DataLayerConfig in WKND Reference Site

    Location of DataLayerConfig in WKND Reference Site

  3. Add a sling:configRef property to the jcr:content node of your site below /content (e.g. /content/<mySite>/jcr:content) and set it to /conf/<mySite> from the previous step.

  4. Once enabled, you can verify the activation by loading a page of the site outside of the editor, for example by using the View as Published option in the editor. Inspect the page source and the <body> tag should include an attribute data-cmp-data-layer-enabled

    code language-html 
    <body class="page basicpage" id="page-id" data-cmp-data-layer-enabled>
    <script>
      window.adobeDataLayer = window.adobeDataLayer || [];
      adobeDataLayer.push({
          page: JSON.parse("{\x22page\u002D6c5d4b9fdd\x22:{\x22xdm:language\x22:\x22en\x22,\x22repo:path\x22:\x22\/content\/wknd\/language\u002Dmasters\/en.html\x22,\x22xdm:tags\x22:[],\x22xdm:template\x22:\x22\/conf\/wknd\/settings\/wcm\/templates\/landing\u002Dpage\u002Dtemplate\x22,\x22@type\x22:\x22wknd\/components\/page\x22,\x22dc:description\x22:\x22WKND is a collective of outdoors, music, crafts, adventure sports, and travel enthusiasts that want to share our experiences, connections, and expertise with the world.\x22,\x22dc:title\x22:\x22WKND Adventures and Travel\x22,\x22repo:modifyDate\x22:\x222020\u002D09\u002D29T07:50:13Z\x22}}"),
          event:'cmp:show',
          eventInfo: {
              path: 'page.page\u002D6c5d4b9fdd'
          }
      });
    </script>

  5. You can also open your browser’s developer tools and in the console the adobeDataLayer JavaScript object should be available. Enter the following command to get the Data Layer state of your current page:

    code language-javascript 
    window.adobeDataLayer.getState();

Supported Components supported-components

The following components support the Data Layer.

Also refer to the events triggered by the components.

Core Components Data Schemas data-schemas

The following is a list of schemas that the Core Components use with the Data Layer.

Component/Container Item Schema item

The Component/Container Item schema is used in the following components:

The Component/Container Item schema is defined as follows.

id: {                   // component ID
    @type               // resource type
    repo:modifyDate     // last modified date
    dc:title            // title
    dc:description      // description
    xdm:text            // text
    xdm:linkURL         // link URL
    parentId            // parent component ID
}

The following event is relevant to the Component/Container Item schema:

  • cmp:click

Page Schema page

The Page schema is used by the following component:

The Page schema is defined as follows.

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    xdm:tags            // page tags
    repo:path           // page path
    xdm:template        // page template
    xdm:language        // page language
}

A cmp:show event is triggered on page load. This event is dispatched from in-line JavaScript immediately beneath the opening <body> tag, making it the earliest event in the Data Layer event queue.

Container Schema container

The Container schema is used by the following components:

The Container schema is defined as follows.

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    shownItems          // array of the displayed item IDs
}

The following events are relevant to the Container schema:

  • cmp:click
  • cmp:show
  • cmp:hide

Image Schema image

The Image schema is used by the following component:

The Image schema is defined as follows.

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    image               // asset detail (see below section)
}

The following event is relevant to the Image schema:

  • cmp:click

Asset Schema asset

The Asset schema is used inside the Image component.

The Asset schema is defined as follows.

id: {
    repo:id             // asset UUID
    repo:path           // asset path
    @type               // asset resource type
    xdm:tags            // asset tags
    repo:modifyDate
}

The following event is relevant to the Asset schema:

  • cmp:click

Content Fragment Schema content-fragment

The Content Fragment schema is used by the Content Fragment component.

The Content Fragment schema is defined as follows.

id: {
    @type
    repo:modifyDate
    dc:title
    dc:description
    xdm:text
    xdm:linkURL
    parentId
    elements            // array of the Content Fragment elements
}

The schema used for the Content Fragment element is as follows.

{
    xdm:title           // title
    xdm:text            // text
}

Core Component Events events

There are a number of events that Core Components trigger via the Data Layer. The best practice for interacting with the Data Layer is to and then take an action based on the event type and/or component that triggered the event. This will avoid potential race conditions with asynchronous scripts.

Below are the out of the box events provided by AEM Core Components:

  • cmp:click - Clicking a clickable element (an element that has a data-cmp-clickable attribute) causes the data layer to trigger a cmp:click event.
  • cmp:show and cmp:hide - Manipulating the accordion (expand/collapse), the carousel (next/previous buttons), and the tabs (tab select) components causes the data layer to trigger cmp:show and a cmp:hide events respectively. A cmp:show event is also dispatched on page load and is expected to be the first event.
  • cmp:loaded - As soon as the Data Layer is populated with the Core Components on the page, the Data Layer triggers a cmp:loaded event.

Events Triggered by Component events-components

The following tables list the standard Core Components that trigger events along with those events.

Component
Event(s)
Accordion
cmp:show and cmp:hide
Button
cmp:click
Breadcrumb
cmp:click
Carousel
cmp:show and cmp:hide
Language Navigation
cmp:click
Navigation
cmp:click
Page
cmp:show
Tabs
cmp:show and cmp:hide
Teaser
cmp:click

Event Path Info event-path-info

Each Data Layer event that is triggered by an AEM Core Component will include a payload with the following JSON object:

eventInfo: {
    path: '<component-path>'
}

Where <component-path> is the JSON path to the component in the Data Layer that triggered the event. The value, available via event.eventInfo.path, is important as it can be used as a parameter to adobeDataLayer.getState(<component-path>) which retrieves the current state of the component that triggered the event, allowing custom code to access additional data and add it to the Data Layer.

For example:


function logEventObject(event) {
    if(event.hasOwnProperty("eventInfo") && event.eventInfo.hasOwnProperty("path")) {
        var dataObject = window.adobeDataLayer.getState(event.eventInfo.path);
        console.debug("The component that triggered this event: ");
        console.log(dataObject);
    }
}

window.adobeDataLayer = window.adobeDataLayer || [];
window.adobeDataLayer.push(function (dl) {
     dl.addEventListener("cmp:show", logEventObject);
});

Tutorial

Want to explore the Data Layer and Core Components in more detail? Check out this hands-on tutorial.

TIP
To further explore the flexibility of the Data Layer, review about the integration options including how to enable the Data Layer for your custom components.
recommendation-more-help
d2be9096-a81e-404b-9952-d8925af7219c