# 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

```javascript
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:

```javascript
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](/developer-guide/variables/client-side-variables/function-arguments/statecontext.md))

***

### Example States

#### Document Ready

```javascript
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

```javascript
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)

```javascript
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](https://caniuse.com/) to check browser support for specific features.
* Avoid heavy DOM operations or long delays — states should be lightweight and reliable.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.jentis.com/developer-guide/states.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.