States are a core concept of Jentis. It is crucial to understand it if you want to better grasp how Jentis works internally and what is the best way to interact with it as an application interface. All variables and values that Jentis tracks in the frontend and processes in the backend are ordered in a queue, where every single state is a certain milestone in a website visit.

Every State definition is a technical description. To define which signals play a relevant part in your tracking setup. Every account will have multiple State definitions: click and scroll events, tool initialization, Data Layer push events, Page Load, etc. So every State is an opportunity to react on events on your website.

With States you will be able to fine tune your JTM setup. You can either go with industry standards and make your tracking align to core concepts such as “DOM Ready” or “Window Load”. Or you can decide to synchronize states with your React, Angular or any other single page application, so all tracking is running smoothly and as a core part of your web application.

Web Navigation and Jentis States

The concept of States in Jentis revolves around the navigation of website visitors. Here protocols exists and define certain aspects and concepts, such as “DOM Ready”, “Window Load” or the initialization of an application (such as Jentis when the internal JS library is loaded). All of that is an abstraction of the navigation on the web, which itself follows more broad concepts.

A website visitor doesn’t know what and when a navigation happened exactly, if a click on a link opens a new website is just an AJAX call or a “real” page load. To a client this is not as relevant as to web applications or tracking. To flexibly react to all kinds of frameworks Jentis created the States concept. States in Jentis are an open framework that can handle all kinds of interactions, either of Single Page Applications or the reload on page navigation. And you can create your own State definitions!

The basic states are:

  • jts.init: This is triggered at the moment the Jentis JS file is initiated.

  • jts.dom: This is triggered at the moment the DOMContentLoaded event occurs on a web navigation.

  • jts.load: This is triggered at the moment the window.load event occurs on web navigation.

  • jts.submit: This is a generic push functionality, which is the bare minimum to connect to Jentis. Any application can use this state by simply calling _jts.push({“track”:”submit”});

Any application however can create its own states to customize the tracking of a website. There are also common use cases where States already are implemented to work with existing concepts like dataLayerfrom Google Tag Manager or a State for Single Page Applications virtual pageview actions. This will be described in the next steps.

Data Queue and State Processing

The core tracking process of Jentis is divided into the following steps.

  1. Receive data: Data can be grabbed via CSS selectors or references to other objects in a browsers runtime. Either data is fetched (Frontend Variables, where you define what value to look for) or an external application pushes data (_jst.push). This step only receives data, not reacting to it, yet.

  2. Evaluate data: As a State definition is called (which is basically a callback function) the JTM will start the tracking process. This could be a DOM ready event or a click. Now all conditions of States are checked (frontend) and all Frontend Variables are resolved that are required in this state (based on your Tags and parameter setup in JTM, so only the required variables are actually resolved). If no condition is met to activate a tag in your setup, no data must be send server side and hence performance is saved.

  3. Submit data: If conditions are met in the previous data evaluation step this will trigger the next process. Now all data is evaluated (variable values will not change due to race conditions) and Jentis will send all of the data to the server. Where the Tracker and Business logic will be applied to cater to your requirements.

  4. Transform and load data: On your Jentis server the data is received and can be processed according to your configuration of Trackers, Tags and Triggers combined with Backend Variables, Functions and Enrichment Variables. With this you can model all data as required to the needs of individual Tags.

State Registry

Creating and customizing a state can be achieved in your JTM account. Navigate to the Components area to edit or create new State objects. Here you can edit existing State definitions or create new ones.

A States has the basic parameters such as name, description or id, as with all elements in Jentis. The JavaScript code will define a function with a single input parameter (a function) and must call the input parameter at the end. The following example will help you to better understand this concept.

State Function Reference

A state is an anonymous JavaScript function with one input parameter. This function will determine a moment in time or interaction of a client and submit a callback.

Input Parameter: {function} initState

This function object must be called when the function (state) is determined to be activated.

Returns: void

Basic State Definition - DOM Ready State

The most basic use case for a state is the DOMContentLoaded handle. This will create a state in your JTM account that activates on the web browsers event. Further details on this api and specs can be found here: https://developer.mozilla.org/en-US/docs/Web/API/Window/DOMContentLoaded_event

DOM Ready State JavaScript Function

function(initState) {
  document.addEventListener('DOMContentLoaded', (event) => {
    initState();
  });
};
CODE

With this state in place your JTM will react as soon as the event was triggered in a users browser. Activating all triggers, checking conditions and calculating all Frontend Variables values. So with this state you are ready to go, if this event fits your requirements.

Common Use Cases

There are common use cases for states that are already available to use in your Jentis account. These are described in the following sections:

  • Data Layer States

  • Single Page Application - Virtual Pageview States

Data Layer States

The Data Layer is a global array that awaits for data to be pushed into it. Making it an application interface (API) and a queue at the same time, as all data is ordered in the chronological order it was pushed (submitted) to it. So every event (dataLayer.push(…) function call) is a good idea to be translate as a State in a Jentis setup.

Here is a State definition that you can use to listen to all push events and process the data as you need it. You also have the option to define certain events, that are relevant to your Jentis setup. Simply put those String values into the array RELEVANT_EVENTS. With this State definition published to your Jentis account you will have all events of your dataLayer object translated into states.

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_name"];  
  
	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();
	}
}
CODE