Data Layer Manager

Data Layer Manager High Level Concepts

A Management Tool for Array Based Data Layers

In the world of data layers, there are two basic types: Array-based and Object-based. This extension is for Array-based data layers.

An array-based data layer is implemented as a javascript Array upon which JSON Objects are added to reflect application events as they happen.

Array-based data layers are the best choice for :

• Asynchronous Tag Management System deployments

• Single Page Applications

• Modern event-driven web sites

• Implementers desiring future flexibility

An object-based data layer is implemented as single JSON Object that is updated to reflect the present state of the application at the present moment in time this structure is fine for describing static data, but presents challenges when representing asynchronous and event driven data. Values are directly on the object with no record of prior values.

This extension is designed to work ONLY with Array-based data layers. Although it will work with the events array of the w3c (v1 2013 CEDDL suggestion), for best results we recommend going with a pure array-based data layer from the start.

Concept One: Establishing the Data Layer Array (politely)

Before anything can interact with the data layer, it must be established as a variable on the browser's window object. In order to establish it, we need to give it a name. You can name your data layer anything that you please (assuming that you choose a valid javascript name and avoid reserved words), but in this documentation, we will use the name, appEventData, for our data layer. Below is a code snippet to establish the data layer.

// Establish the data layer, naming it appEventData (One liner version)
window.appEventData = window.appEventData || [];

Since you will see this line of code many times in this documentation, it's really worth understanding what it does. If you already understand this code, skip ahead. If not, below is a much more verbose form of the same code.

// Establish the data layer, naming it appEventData (Verbose version)
if (typeof window.appEventData === "undefined") {
    window.appEventData = new Array();
}

Both code examples above do the same thing; Use the existing appEventData array if it exists, and create it if it does not exist.

Always use this 'polite' method to establish the data layer unless you absolutely wish to overwrite existing data.

Concept Two: Pushing events to the Data Layer Array

The best thing about array-based data layers is that the push method exists as soon as the data layer is established (See Concept One above). This means that the application can push events onto the data layer even before the Data Layer Manager has initialized. This is a huge benefit for those using Data Layer Manager with the Adobe Launch Asynchronous Deployment option.

OK. There was a lot in that last paragraph. Lucky for you, all the technical stuff has been handled in Data Layer Manager. The only thing you really need to know is "What is an event?" and "How does one get pushed onto the data layer?" We'll get the first part in a bit (See Concept Three) but for now, let's see some code.

// Establish the data layer, naming it appEventData
window.appEventData = window.appEventData || [];

// Push an event object onto appEventData
window.appEventData.push({"event":"Page Loaded"});

// Push another event object onto appEventData
window.appEventData.push({"event":"Product Viewed"});

Go ahead and copy the code above and paste it into your browser's dev console. Congratulations! You've just pushed two events to your data layer. Enter console.log(window.appEventData) as shown below to see what the data layer looks like after these two pushes.

There are a few things worth noting in the image above:

1. We included the 'one-liner' before we pushed events.

2. We passed a JSON object to each push. {"event" : "Page Loaded"} in the first push and {"event" : "Product Viewed"} in the second push.

3. In this example, each JSON object has an "event" key with a String value assigned.

To solidify the concept, let's simulate a couple other application events by pushing to the data layer.

In the image above, we see two more event objects pushed to the data layer. The first has an event value of "Video Started". The second has an event value of "Video Paused". See how after pushing them, window.appEventData now has four items.

In the examples above, we are manually pushing event objects onto the data layer to illustrate the concepts. In practice, it will be the website developer's responsibility to incorporate data layer pushes into the website.

Concept Three: Event Objects

The examples in the previous section give a gentle introduction to the Event Object. In those examples we were using the most simple form of event object; one with nothing more than an event value. This is well and good, but event objects become vastly more useful when they carry some data that describes the event beyond just giving it a name.

How much more useful would it be the data layer pushes for the "Page Loaded" and "Product Viewed" events looked like this?

window.appEventData = window.appEventData || [];
window.appEventData.push({
  "event": "Page Loaded",
  "page": {
    "siteLanguage": "en-us",
    "siteCountry": "US",
    "pageType": "product detail",
    "pageName": "pdp - crossfit zoom",
    "pageCategory": "womens > shoes > athletic"
  }
});

window.appEventData.push({
  "event": "Product Viewed",
  "product": [
    {
      "productInfo": {
        "productID": "10345678934",
        "isOutOfStock": false
      },
      "price": {
        "sellingPrice": "95.97",
        "basePrice": "129.95"
      }
    }
  ]
});

That was a rhetorical question... but in case you need an answer, "Infinitely more useful!" Below is an image showing how our data layer would look if the application were pushing these, richer event objects.

The only required field of an event object is event but additional data may accompany the event. It is considered best practice to provide this additional data in a sub-object as shown above.

Concept Four: Pushed Events Trigger Data Layer Manager Events in Launch

Everything before this point was foundational information provided to prepare the reader for this key concept.

When an Event Object is pushed to the data layer, Data Layer Manager triggers events in Launch.

Within Launch, Data Layer Manager provides the "Data Layer Push" event type. To take advantage of this event type, in the rule's event configuration, for Extension, select "Data Layer Manager". For Event Type, select "Data Layer Push". For Event Name, manually enter or select the value of the event key on the event object that is to be pushed onto the data layer.

For example, in order to configure a Launch rule to be triggered by the "Page Loaded" event in the example above, we configure the event as shown below.

Concept Five: Context Aware Data Elements

When the Data Layer Manager triggers an event in Launch, it also provides access to the additional information carried in that event object via the Context Aware Data Element Type. To make use of this feature, Launch data elements are created using the Context Aware data element type.

By way of example, let's say that we want to have ready access to the pageName that accompanied the "Page Loaded" event object. To do that we create a new Launch Data Element as shown below:

Note that in Data Layer Path we enter "page.pageName" the path to the key that we care about. This data element will reliably return the value page.pageName regardless of the context in which it is requested.

• If we request page.pageName in the context of the "Page Loaded" event, the value returned will be that which was contained in the event object.

• If we request page.pageName in the context of some later event, the value returned will be the last known value.

Consider a Single Page Application that would send a "Page Loaded" event every time the user is shown a new application state. In the example below, there is a "Page Loaded" event for a product detail page followed by a "Product Viewed" event after a "Product Added" event was triggered followed by another "Page Loaded" event when the shopping cart is displayed.

The value returned for the page.pageName context aware data element is not surprising, but that's the point... for the value returned to make sense regardless of the context in which it is requested. Let's say that in between the Product Viewed event and the Product Added event, there were Launch rules triggered by user interactions not handled by the data layer events (clicks, mouse-overs, viewport scrolls, etc). If the page.pageName context aware data element were evaluated in those rules, the value returned would be the last know value, or "pdp - crossfit zoom" in this case.