Adobe Launch: Data Elements Guide

 

You’re missing the boat if you aren’t using Data Elements in Adobe DTM or Adobe Launch. Data Elements are built so you don’t have to rely on JavaScript or type the same text over and over again. Using Data Elements saves a whole lot of time and makes your rules leaner/cleaner. They work like a variable in math or coding. Each Data Element, like a variable, has a key and value pair.

For example, my Adobe Analytics implementation ID might be mysite-prod. I’ll set this as a Data Element so that I don’t have to type that out each time I want to use that value. The name (key) of my Data Element would be something like Implementation ID while the value would be set as mysite-prod. Now whenever I want to use that value I simply reference the Implementation ID Data Element and it will input mysite-prod. One of the biggest benefits of this is that if I need to change the Implementation ID across 20 different rules and extensions, I only need to update it in one place!

Proper use of Data Elements can ease the transition from Adobe DTM to Launch and are important to understand before going into any new implementation. If you’re a DTM veteran, this will look very familiar. If you’re unsure what Adobe Launch brings to the table, check out my article on Adobe DTM vs. Launch.

How to Use Data Elements

Data Elements are values that can be stored and recalled anywhere. For instance, I’ll create a Data Element named User Signed In that pulls in whether or not a user is signed in (true/false). I can use that as a rule condition to determine if a rule should fire:

The left side just shows the list of Data Elements. The right side (where the arrow is pointing) shows how it is referenced in a rule by using the %…% syntax:

%User Signed In%

If you’re using custom JavaScript, they’re referenced using the syntax _satellite.getVar(‘…’):

_satellite.getVar('User Signed In')

Check out the Adobe Launch Cheat Sheet for additional examples and resources. The Adobe Launch team has also done a great job documenting Data Elements on the Adobe Launch docs site.

Data Elements are mostly used in Adobe Launch rules, but can also be used in Extensions, custom code, or even other Data Elements (cue Inception music). They can even be referenced outside of Adobe Launch using the _satellite.getVar(‘…’) method referenced above.

How Data Elements Work

A Data Element will try to reset its value each time it’s referenced. Let me repeat that: A Data Element will try to reset its value each time it’s referenced. Even if you have a Data Element scoped on the Visitor storage duration, each time it’s referenced it will try to set its value. This is important because let’s say you want to store whether a user is registered. Here’s what it looks like (thanks to Jan Exner for helping me validate this):

 

Do not confuse Data Elements with setting and reading cookies. They are not the same! You also cannot check the value of a Data Element to determine if you want to reset it. By simply querying the Data Element you are evaluating it and its value could change. If you want to squirrel away a value and use it later, you might be better off using cookies instead of Data Elements.

We use Data Elements for every reason they don’t behave exactly like cookies. They exist to serve as a backbone of an implementation that relies on consistently using name:value pairs. They’re built for evaluating data layers, query strings, cookie values, etc. While they can store and recall data, the framework has nuance and should be used with caution.

Storage Types

Data Elements can be stored in 4 different scopes: Visitor, Session, Pageview, and None. This determines when you are able to recall stored values.

Visitor: Stores the value for 2 years after the user’s last session.

Session: Stores the value until the session ends (either 30 minutes of inactivity or closes the browser).

Pageview: Stores the value as long as the user is on the same page.

None: Does not store the value.

These should be familiar to analysts. The only oddball is the “None” scope, which is a new storage duration type primarily intended to serve Single Page Apps.

Core Data Element Types

Cookie

The Cookie Data Element will grab the value of any cookie being stored on a web property. Cookies are stored in name:value pairs. Simply type the name of the cookie in the Cookie Name field and Launch will deliver its value. This is useful for collecting information like login status. Here’s how you see the list of available cookies:

1. Open up devTools (right-click, then click Inspect)
2. Go to the Application tab
3. Expand the Cookies dropdown and select your current domain
4. Input the name of the cookie into Launch (note the red underlined column labels)

Custom Code

The Custom Code Data Element supports custom JavaScript you want to use to set a value. The code input box acts like any code editor and will highlight code errors. Each Custom Code Data Element MUST return a value (note return foo in the example above). If you’re used to Google Tag Manager, Launch is different because you don’t have to wrap the JS inside of a function.

Note that Custom Code does not support the $(this) method. If you wanted to create a Data Element that returns $(this).text(), there are built-in utilities for that.

DOM Attribute

 

The DOM Attribute Data Element scrapes a value from the DOM. For instance, given the following HTML:

<div class="classy">
  <a id="myLink" href="/foo.html">Some Link</a>
</div>

In the DOM element matching the CSS Selector field, I can use div > a or even .classy a to target that anchor element. This just tells Launch what to look at. The dropdown is where we tell Launch what value to grab. If we select id, the Data Element will return myLink. That’s because we’re targeting the anchor element and returning its id value.

JavaScript Variable

JavaScript Variable Data Elements are your best friend if you’re using a data layer (you should be using one). With this, you can pull in any JavaScript variable on the page. Not sure what variables are at your disposal? Open your browser’s devTools window. The easiest way to do this if you aren’t sure how is to right-click on the window and then click Inspect. Click on the Console tab at the top and type window:

It will return a really big object with a lot of stuff you can reference. Often with data layers, you’ll see something like a digitalData object (warning: this document is so old, kids born when this was last updated are about to go to grade school). Path to Variable is exactly what you would type into the console to check the value of a JavaScript object – so QA is easy. Want to know what will show up in Adobe Launch? Type it into your console.

Local Storage

Adobe Launch recently introduced the Local Storage Data Element. It’s pretty nice if you use that browser feature. In order to check what’s stored in your local storage, simply type localStorage in your devTools console. To leverage local storage values, do NOT type the full localStorage.someValue but instead only input someValue as the item name.

Page Info

The Page Info Data Element allows you to select some preset page attributes. Most of these are self-explanatory and might look familiar to those who are familiar with %URI%, %Hostname%, and other dynamic substitutions from DTM (and are still supported in Adobe Launch).

Query String Parameter

The Query String Parameter Data Element in Adobe Launch lets you grab name:value pairs from URL query strings. Consider the following URL:

https://jimalytics.com?foo=bar

The query string name is foo and the value that would be returned from the Data Element would be bar. You should NOT include special characters into the URL Query String Parameter Name box like ?, &, or =. Instead, only include that “foo” part. You can use any query string, even if it has underscores.

On another note, the case sensitivity checkbox is a bit verbose. It would make a little more sense if it was a checkbox that says “Case sensitive” since I imagine most folks who use this Data Element will opt out of case sensitivity.

Random Number

You’ll never guess what the Random Number Data Element does. It generates a random number. More specifically, a random integer between any two numbers. That means there are no decimals – only whole numbers. This is often used for cache-busting. Interestingly, for this Data Element the default value, clean text, force lowercase, and storage duration do literally nothing.

Session Storage

Adobe Launch recently introduced the Session Storage Data Element. It’s another nice browser feature. In order to check what’s stored in your session storage, simply type sessionStorage in your devTools console. To leverage session storage values, do NOT type the full sessionStorage.someValue but instead only input someValue as the item name.

…And yes, I did basically just copy-paste the Local Storage info into this Session Storage section.

Visitor Behavior

The Visitor Behavior Data Element is another dropdown which is nice because it minimizes user error. The options here are pretty self-explanatory, but I’d like to comment that elements like Landing Page are particularly helpful because you don’t need to store it in a data layer or try to use magic in your Data Element to retain the value. Many of these are calculated by counting pages or are calculations of total sessions. One option I wanted to research a bit more was Minutes On Site.

For Minutes On Site, Adobe Launch actually stores a cookie that marks when your session began. Each time you reference the Data Element it evaluates current timestamp – original timestamp. I implemented the Minutes on Site Data Element mid-stream while I was writing this article and noticed the timestamp of my initial session was already stored. Seconds after I added the Minutes on Site element it returned that my session was over 30 minutes long! Hmmm… does this mean other data is being stored in this cookie?

Intuitively, my next question was if Launch is actually storing my Session Count by default. This might be useful if I’ve implemented Adobe Launch months ago and decide I want to track this metric without starting from scratch with a fresh cookie! Alas, it does not store your session count by default. When you add the Session Count Data Element, it will start the count from scratch. Perhaps it would make sense to add Data Elements like Session Count by default in your implementation just to have a backlog of the data in case you decide to use it at some point.

Final Notes

Data Elements are easy to understand but difficult to master. It sounds melodramatic, but when you dive into the weeds and run into sequencing issues things can get interesting. Adobe Launch makes Data Elements exponentially easier, though. There are also some great extensions that expand its capabilities (like the SDI Toolkit). The elements covered in this article are solely from the Core extension (out-of-the-box).

That said, it’s important to take care of your Data Elements and to be intentional with their usage. That means minimizing JavaScript and paying attention to when the data layer updates its values. Data Elements aren’t typically intended to be used ad-hoc, either. If you’re using a Data Element for one tag in one rule – do you really need it?

To see how other people use Data Elements, download and install the Tagtician debugger. Did you know that with Tagtician you can inspect and learn from anyone’s DTM or Launch implementation?

What are some of your experiences or use cases with Data Elements? Are you an addict or do you use them sparingly?