States

Introduction to States in JENTIS

In JENTIS, a State defines the point in time at which data should be collected from the browser. States are essential for ensuring that data is only extracted when the relevant context is available — whether that’s after the page has loaded, during user interaction, or at key behavioral events.

---

What is the Goal of a State?

A state controls when data collection or processing should begin. This allows for event-driven data tracking and ensures that your setup is both accurate and performance-optimized.

Here are a few common examples of when a state might be triggered:

• Document Ready: The DOM is fully loaded

• User Interaction: A specific button is clicked

• Page Transition: A user navigates to a new page (SPA/virtual pageview)

• Session Start: A new session begins

---

How to Write a State

A state in JENTIS is defined as a JavaScript function that runs in the user's web browser. This function receives a callback as an argument, which must be called once the specified condition has occurred.

Basic Syntax

function(cb) {
    cb(); // Triggers the state immediately
}

This is an example of a state that fires instantly, without waiting for any condition.

Advanced Syntax

For more advanced use cases, the callback can be invoked using the initState function with additional configuration options:

function(initState) {
  initState({
    stateCallback: function() {
      console.log("State works!");
    },
    requestType: "sendBeacon",
    contextualStateInformation: {
      info: "A",
      value: "123"
    }
  });
}

Explanation of Parameters

• initState(): The main callback function provided by JENTIS. You can either call it directly (initState()) or pass a configuration object.

• stateCallback: This function is executed when the synchronous part of the state logic is triggered. Use it to run JavaScript logic before or alongside data processing.

• requestType (optional): Defines the method for sending data to the backend:

  • Default: XMLHttpRequest

  • Alternative: "sendBeacon" for asynchronous, low-priority transmission.

• contextualStateInformation (optional): An object containing additional metadata that will be attached to the event. These values can be used for enrichment, debugging, or downstream processing. This can be further used on Client-Side Variables (stateContext)

---

Example States

Document Ready

function(cb) {
  if (document.readyState === "complete") {
    cb();
  }
}

This state fires when the JavaScript event document.readyState === "complete" occurs — meaning the DOM is fully loaded and the page is ready.

---

Button Click

function(cb) {
  document.querySelector('#my-button')?.addEventListener('click', function () {
    cb();
  });
}

This state triggers when the user clicks on a specific button with the ID my-button.

---

URL Change (for Single Page Applications)

function(cb) {
  let lastUrl = location.href;
  new MutationObserver(() => {
    const currentUrl = location.href;
    if (currentUrl !== lastUrl) {
      lastUrl = currentUrl;
      cb();
    }
  }).observe(document, { subtree: true, childList: true });
}

This state detects URL changes typical in SPAs, triggering when the user navigates within the app.

---

Key Points

• You can access any browser data that is available via JavaScript.

• States must be written in JavaScript ES5 to ensure compatibility with 100% of browsers. → Use caniuse.com to check browser support for specific features.

• Avoid heavy DOM operations or long delays — states should be lightweight and reliable.