# Asynchronous Variables

## Asynchronous Variables

**Asynchronous Variables** are a special type of client-side variable in JENTIS that gather information **asynchronously**, typically from third-party sources such as APIs or tracking pixels.

***

### Key Characteristics

* **Execution is asynchronous** and may take up to **2 seconds**.
* The **entire state execution is paused** until all asynchronous variables either:
  * Return a value via callback, or
  * Hit the timeout limit.
* **Client-Tags that rely on asynchronous variables are also paused** until those variables are resolved.

***

### When to Use

Use asynchronous variables when you need to **fetch data dynamically from external sources** before continuing the tracking execution.

#### Potential Use Cases:

* Retrieve a **third-party cookie value** or identifier from a pixel.
* Wait for external data before sending it to the **JENTIS Environment**.

***

### How It Works

To define an asynchronous variable, your variable function must include a call to:

```js
this.sendHTTPRequest(...)
```

When this function is detected, the variable is automatically treated as **asynchronous**.

To complete the variable evaluation, you **must call**:

```js
args.callback(returnValue);
```

This returns the value and resumes state and tag execution.

***

### Function: `sendHTTPRequest`

#### Signature

```ts
this.sendHTTPRequest(config: {
  url: string;
  method: string;
  contentType?: string;
  withCredentials?: boolean;
  data?: string | object;
}, callback: (response: any) => void): void
```

#### Parameters

* **`url`** (`string`, required):\
  The endpoint to which the HTTP request will be sent.
* **`method`** (`string`, required):\
  The HTTP method (e.g., `"GET"`, `"POST"`).
* **`contentType`** (`string`, optional):\
  MIME type of the request body (e.g., `"application/json"` or `"text/plain"`).
* **`withCredentials`** (`boolean`, optional):\
  Whether or not to send credentials like cookies.
* **`data`** (`string | JSON`, optional):\
  Payload to be sent with the request (for `POST`, etc.).

#### Return Value

The callback function receives the **parsed HTTP response** as its parameter.

***

### Example: Asynchronous Variable Fetching a Third-Party ID

```js
function(args) {
  this.sendHTTPRequest({
      url: "https://track.adform.net/Serving/Cookie/?adfaction=getjs;adfcookname=uid",
      method: "GET",
      contentType: "text/plain",
      withCredentials: true
    },
    function(res) {
      args.callback(res.adform_id); // Return the ID from Adform
    }
  );
}
```

In this example:

* The Adform pixel is queried for a user ID.
* Once the ID is retrieved, it’s returned via `args.callback`.
* The variable resolves, and JENTIS continues state and tag processing.

***

### Execution Flow

```plaintext
Website (with JENTIS) 
    ↓
Trigger fires state with async variable
    ↓
State execution pauses
    ↓
Asynchronous variable sends request via `sendHTTPRequest`
    ↓
Waits up to 2 seconds for response
    ↓
Callback received (or timeout)
    ↓
State and client-tags resume
    ↓
Data is sent to JENTIS Environment
```

***

### Notes

* Always ensure that `args.callback(...)` is called; otherwise, the variable will timeout.
* Avoid long-running operations to maintain performance.
* Only use asynchronous variables when absolutely necessary, as they delay the full data submission process.

***

Asynchronous variables are powerful tools that let you enrich your tracking setup with dynamic, external data—while still ensuring proper execution flow and consent handling through the JENTIS system.