I built the EDDL Helper extension to make it a bit easier to use an event driven data layer within Launch. It allows you to use an array on your site to fire direct call rules, and it merges the contents of the array together to provide a merged (or computed) state. It’s quite similar to other extensions which do this for you, such as the Adobe Client Data Layer from Adobe or Data Layer Manager from Search Discovery. EDDL Helper is designed to be really simple. It uses direct call rules rather than adding a new event type to make it easy to set up and easy to remove. It lets you control the name of your data layer object and choose when to fire rules.
The purpose of this post is to show you how I’ve set up this extension on my own website as an example. Check out the EDDL Helper page for details on installing the extension.
Installing EDDL Helper
I already have Adobe Launch on my site. I am running an asynchronous script at the top of each page. When I get the extension from the catalog there are some initial settings and one rule to build. Firstly, the settings. I chose “digitalData” as my data layer name. You can choose any name. If the object doesn’t exist when the extension loads it will be created for you. I chose “event” as my direct call rule identifier. This identifier will be used as the key for firing direct call rules. For example the push event digitalData.push({"event":"test"}); will fire the “test” direct call rule. I also ticked the “fire direct call rules” box because I do want the extension to fire rules.
This is the main settings done. Now I will need to create a rule to load the extension in order for it to work. I’ll make a Library Loaded rule with the Set Up EDDL Helper action. What this action does is set up the data layer and process any push events that happened before Launch was ready.
That’s it. My extension is installed and will process my data layer. Let’s do a quick check to make sure it’s working ok.
Testing
The first thing I want to test is that the extension is installed and ready. It’s easy to use Launch debug mode by typing _satellite.setDebug(true); in the browser console. I will refresh my page and get some information about how the extension is loading.
As you can see I am getting debug messages in the console. There are three messages from EDDL Helper. The first indicates that the library has been loaded correctly. The second says “setting up digitalData as an empty array” which lets me know that the object didn’t exist when EDDL Helper first loaded, so it created an empty array to use. The final message says “setting up digitalDataState as the data layer helper object” which is from the Advanced Settings in the extension configuration. The data layer helper object is how EDDL Helper works. You don’t need to worry about it in normal use, but it can be useful for debugging and testing. You can use the data layer helper name getState method to quickly check the merged state of your data layer in the browser console. I would use digitalDataState.getState() to see my merged state. For now my data layer is empty so that shows an empty object.
To demonstrate how EDDL Helper works in an asynchronous environment I will set up some test data layer push events on my site. Before the Launch script is loaded I will run a push event, and after the Launch script is loaded I will run another push event. You can see for yourself in the page source of my site below.
Let’s see what happens now when I load the page again with Launch debug mode on.
My pushes have worked and some direct call rules are fired. Firstly notice that there is a new message saying “an array object digitalData already exists, using this object” which tells me that EDDL Helper found an existing object when it loaded so it doesn’t need to create a new object. In addition there are some messages about the push events themselves. Both push events contain an “event” key, which is set as the “direct call rule identifier” in the extension settings. This means that both push events fired direct call rules. You can see the payload of each direct call rule, which is the data that was contained in each push event AND the entire merged state of the data layer at the time of the push. Also note that the push events fired direct call rules in the order they were received, with the “before_launch” rule first.
You can type in push events to the browser console for additional tests.
The Merged State and Data Elements
Now that I can see some rules firing it’s time to use the data layer itself. A major component of an event driven data layer is the ability to access a “merged state” of the data layer. This allows websites to push in data as it becomes available. Each push event either adds or overwrites data to the merged state. The easiest way to access the merged state is through data elements that EDDL Helper provides.
Say I have a “view page” data layer event, perhaps used on a single page application type of website which would let me fire off page views to analytics. I could ask my website developers to use the following push event when the a new screen is shown.
window.digitalData = window.digitalData || [];
digitalData.push({"event":"view_page","page":{"page_name":"EDDL Helper Launch Extension"}});This is a really basic example to show how to get values from the data layer. If I want to be able to use the “page_name” value I would create the following data element.
You can also leave the input field blank to create a data element which would return the entire merged state of the data layer.
Now say there are several push events happening on the page, each adding a little bit of data.
window.digitalData = window.digitalData || [];
digitalData.push({"page":{"page_name":"EDDL Helper Launch Extension"}});And then…
window.digitalData = window.digitalData || [];
digitalData.push({"page":{"page_type":"blog"}});And finally…
window.digitalData = window.digitalData || [];
digitalData.push({"event":"view_page"});In the debug console you can see what happens.
So let’s go through what is happening here. The first push event has no “event” key, so it won’t fire a direct call rule but will update the data layer. The second push event is the same. The final push event does contain the “event” key, thus it would fire the “view_page” direct call rule. You can see in this example I have not yet set up a rule to match that identifier. So what have we achieved here? Let’s check the merged state of the data layer. You can set up a data element to get the entire merged state of the data layer but for testing it’s quick to use the data layer helper object. In advanced extension settings I have named my helper object “digitalDataState” but you can give it any name you like. Let’s use the getState() method.
As you can see, the entire merged state includes all of the data that has been pushed in so far, including both page_name and page_type which were pushed in different events. Also note the “data” key here. This was pushed in by my test push events earlier. I have two test push events, each setting a different value to the “data” key. The latest push event overwrites the earlier push events when the same key is found, so my merged state is up to date.
Event.Detail
You may not always want to access the merged state. Some of the time you may need to access only the payload of each push event. You can do this with “event.detail” in Launch. This is a native part of Launch direct call rules and it’s not added with the EDDL Helper extension. When EDDL Helper sends a direct call rule, both the push event payload and the entire merged state of the data layer are included in the “event.detail” object. Let’s take a look how that works.
I’ve added a direct call rule with the identifier “view_page” to use in this example.
window.digitalData = window.digitalData || [];
digitalData.push({"event":"view_page","page":{"page_name":"EDDL Helper Launch Extension"}});When I type that into my console I can view the payload included in the rule.
Notce the “message” and “state” objects passed into the direct call rule. The “message” object contains the payload for the event. The “state” object contains the entire data layer at the time of this event. Both of these can be accessed within the rule with “event.detail.message” and “event.detail.state” respectivley. Let’s do a test. I have made a “view_page” rule and I will set some custom code to log these objects.
When I type in my “view_page” data layer event, let’s see what happens.
Firstly the rule fired correctly. Secondly I can see my console logs. The first one (1) has printed the “message” which was the data layer event payload. The second (2) shows the entire data layer, including my “data” value which was pushed in when the page loaded. I could use the values from these objects to send to analytics.
Arrays
The EDDL Helper extension gives you two options to handle arrays being pushed into your data layer. The reason there needs to be special options for arrays is because these are a little tricky as compared to simple key value pairs. With a plain object like “page_name”:”EDDL Helper Launch Extension” for example, there can only be a sinlge value for the “page_name” key. Each time a new value is pushed it gets overwriten with the new value. But now say you have an array of products shown on a page. Maybe there are 20 products, and each is one object in an array. Say the user navigates to a new section of the site and it’s a single page application (so there is no full page load) so there is a new data layer push event with the new products shown to the user. What happens? By default the new array is merged into the old array and overwrites happen based on where each item is within the array; the index of each item.
I like to keep examples simple, so here is a really simple example.
digitalData.push({“array”: [1,2,3,4,5]});
The “array” object contains 5 items.
digitalData.push({“array”: [6,7]});
I push in two items.
The final “array” object looks like this.
“array”: [6,7,3,4,5]
What has happened here? Each item in the array is merged based on the index of each item. My second push event (with values 6 and 7 inside) contained an array with values in index 0 and index 1 so these values replaced the old values at index 0 and index 1 inside the merged data layer. This is the default behaviour when merging arrays together.
There is a second way that EDDL Helper can handle arrays and that is to clear the array each time. You can find this setting in Advanced Settings.
If you enabled “clear arrays” then this is the result you get.
digitalData.push({“array”: [1,2,3,4,5]});
The “array” object contains 5 items.
digitalData.push({“array”: [6,7]});
I push in two items.
The final “array” object looks like this.
“array”: [6,7]
As you can see, when any new values are pushed into the array, the entire array is cleared first. This can be helpful in situations where you need any new values to replace any old values. Going back to the example of showing products in a single page application, you would want the data layer to reflect what is shown to the user, so each push event containing a products array should first clear out the old products. This way you can be sure that the data layer won’t contain old products from previous push events.
Conclusion
Well that’s it for now. There are many different use cases for EDDL Helper but I think I’ve covered the basics in getting it set up and tested.