Tag Management Software often uses a Data Layer as an Interface to global website data. Here external applications can push data to or a tag management code an push additional information. With every push to the dataLayer as a new event. Making the Data Layer a queue of events and data. If you have a Data Layer that follows this design (like Google Tag Manager) this guide will help you to migrate events from the Data Layer to Jentis. It is easy to setup and transform data like a Plug&Play application.

In this guide we will cover the following steps to setup a JTM to have States, Variables, Tags and Triggers ready to work with Data Layer events:

  • Create a Data Layer Event to State translator script (Custom JTM State)

  • Create a JTM Frontend Variable to access a property of the global Data Layer JS variable

  • Create a Trigger that reacts to the new State and Event from Data Layer

  • Create a Tag that will use the trigger and frontend variable created to submit it to a Tracker (Google Analytics)

Basic Idea

Jentis uses a States concept to determine when events happen and make a snapshot of all frontend variables at this time. With every state all triggers will be checked and if they apply the data is submitted to the server side and used to communicate to Tracker objects (external and third party applications that you want to connect to, such as Google Analytics, Facebook CAPI, etc).

Now we can easy connect existing Data Layer events to Jentis. By defining certain (or even all) events that appear in the global Data Layer object (window.dataLayer or any other Variable that follows the Event Queue design).

Create a Custom Data Layer Event State

The first step is to define a custom State in our Jentis Tag Manager (JTM). We will go ahead and use the following code as the core of our new Data Layer Event to State application. A quick walk through the JS code is found below.

Navigate to the Components > States section of your JTM and create a new State object.

Custom State Name: Data Layer Event to State

Customize this parts of the code:

  • line 4: this Array object holds String values of event names that must be translated as States; you can keep this Array empty to make all Events available as States if required. In the example code only the “my_event” will be translated, for example when dataLayer.push({event:'my_event',…}); is called.

function(initState){
  	//define events to listen to as single String values in array
	//keep empty to listen to all events
	var RELEVANT_EVENTS = ["my_event"]; 
  
	var dl = window.dataLayer || [];
	if(Array.isArray(dl) && dl.length && dl.length > 0) {
		dl.forEach(arrayItem => {
			initiateRelevantStates(arrayItem.event);
		})
	}

	var originalPush = dl.push;
	dl.push = function(args){
		initiateRelevantStates(args.event);
		originalPush.call(window["dataLayer"], args);
	}
    window.dataLayer = dl;

	function initiateRelevantStates(event_name){
		if(Array.isArray(RELEVANT_EVENTS) && 
		   RELEVANT_EVENTS.length > 0 &&
		   typeof event_name != "undefined")
			if(RELEVANT_EVENTS.includes(event_name))
				initState();
      		else
                console.log("JTM Data Layer Event States: non relevant event - no state initialized");
		else if(typeof event_name != "undefined")
			initState();
	}
}
JS

This function follows the basic JTM State syntax where a parameter (initState) is expected that must be called at the moment a State definition is reached. In our case that means whenever a dataLayer.push is called with an event property that matches RELEVANT_EVENTS (array) list.

There are three parts of this code:

  1. Check all existing events that were pushed to the dataLayer before JTM was executed. (code line 6 to 11)

  2. Update the dataLayer.push-function to translate all further push function calls to also initiate a State with JTM. (code line 13 to 18)

  3. Check if the event from the dataLayer is relevant (matching our list of relevant events). If so a JTM State is initiated. (code line 20 to 30)

Create a Frontend Variable to Access a Data Layer Value

Now we get a “notification” with our JTM setup when our my_event is pushed to the global window.dataLayer object. Next step is to access a property of that same event which we need with a Tag later, for example to track an event with Google Analytics.

A simple mockup code of this “expected” situation is:

dataLayer.push({
  event:'my_event',
  event_category:'cat'
})
JS

Our target is to use “event_category” of this event as a Frontend Variable with JTM to submit the value of this parameter to a Google Analytics event.

So we need to add a Frontend Variable to our JTM. You can do this by navigating to Data Sources > Frontend Variables and add a new object. Give this a Name (ie. as suggested below, or in Screenshot “DataLayerEventName” that describes the content of the variable) and add the following code in the “JavaScript Code” field value.

Variable Name: Data Layer Event Category

Variable Code: as below.

Customize this parts of the code

  • line 6: define here the parameter name that is used in the dataLayer object pushed. In our case it is “event_category”

  • line 11: define a specific event name, if this parameter name is used in different pushes with same event value.

  • line 12: define “last” or “first” occurance pointer (if this parameter is found multiple times in the dataLayer this will determin to use the first occurance found or the last).

function(){
  /**
   * The parameters name of which to return the value from.
   * Mandatory, empty String not allowed.
   */
  var PARAM_NAME = "event";
  
  /**
   * Further customization.
   */
  var EVENT_NAME = "";       // either empty String or the actual event value to match 
  var OCC_POINTR = "last";  // use 'first' or 'last' to either select the first occurance of the parameter or the last found on iteration
  
  return get_dl_value_of(PARAM_NAME, OCC_POINTR, EVENT_NAME);
  
  /**
   * Access a dataLayer parameter as required. This convenience function
   * will look within the global dataLayer object and iterate it until a
   * certain parameter is found. The search conditions are defined by the
   * input parameters. Iteration starts at 0 ("first" is described as the 
   * most early occurances in the dataLayer queue and "last" respectively).
   * @params pname {String}    The parameter name to look for.
   * @params opointer {String} Either "first" or "last" which either returns 
   *                           the first or last occurance of the parameter
   *                           found in the dataLayer.
   * @params ename {String}    (optional) Event name that must be matched to 
   *                           return the parameter value.
   */
  
  function get_dl_value_of(pname, opointer, ename){
    var dl = window.dataLayer || [];
    var r  = [];
    
    for(var i = 0; i < dl.length; i++){
      if((ename == "" || dl[i].event === ename) &&
         typeof dl[i][pname] !== "undefined")
        r.push(dl[i][pname]);
    }
    
    if(opointer == "first")
      return r.length > 0 ? r[0] : "";
    else if(opointer == "last")
      return r.length > 0 ? r[r.length-1] : "";
    else
      return "unexpected opointer value";
  }
}
JS

Now we have a Frontend Variable in our JTM that holds the value of event_category. Let's use both, the State and Variable created, to submit data to a partner.

Setup Trigger and Variable in JTM

The first step is to have a trigger that listens to our newly created State in the previous steps.

Navigate to the Server Tag Manager > Trigger section and create a new object.

Trigger Name:Data Layer Event my_event” would be a descriptive name in that case.

State: The previously created State “Data Layer Event to State”

Conditions: Add further filter criteria if the event only should trigger in certain cases.

Now you need to navigate to Server Tag Manager > Tags to create a new tag. This one will use all the parts we created in the previous steps. We will create a tag that sends an event to Google Analytics with the event_category of GA mapped to our “Data Layer Event Category” Frontend Variable.

Follow the process to create the tag and select the Trigger “Data Layer Event my_event“ (from previous step).

In the configuration of the tag parameters you will add the Frontend Variable. Mapped to the parameter as you need it (ie. as the event category for GA).

Now save the tag and make sure to preview your configuration. All the data you need will now be read from the DataLayer (via Frontend Variable), submitted to the Jentis server (via State) and activate a GA tag (via Trigger and Tag) on the server side.