# User Storage

## `userStorage` API (Server-Side)

The `userStorage` API is the primary interface for **persisting data server-side per tool instance** for a specific user. It is commonly used to store **identifiers** such as:

* Client IDs (e.g., `client_id`)
* Click IDs (e.g., `gclid`, `fbclid`)
* Campaign parameters or session-level values

These functions are available within the **server-side variable runtime environment** under the `this` scope.

***

### Available Functions

#### 1. `this.userStorage.write(name, value, expirationTimestamp)`

Stores a value under a given key and defines when it should expire.

**Parameters**

| Placeholder              | Description                                               | Type                    | Required                                      | Example                 |
| ------------------------ | --------------------------------------------------------- | ----------------------- | --------------------------------------------- | ----------------------- |
| `<NAME>`                 | The key used to store and retrieve the value              | `string`                | <i class="fa-square-check">:square-check:</i> | `"client_id"`           |
| `<VALUE>`                | The value to be stored (can be any data type)             | `any`                   | <i class="fa-square-check">:square-check:</i> | `"123abcd123.11111111"` |
| `<EXPIRATION TIMESTAMP>` | Unix timestamp (in milliseconds) for automatic expiration | `number` (milliseconds) | <i class="fa-square-check">:square-check:</i> | `1740555149453`         |

**Example**

```js
async function() {
    const href = this.getFrontendVariable('window_location_href');
    const url = new URL(href);
    const gclid = url.searchParams.get("gclid");

    if (gclid) {
        const expirationTime = Date.now() + 7890000000;
        this.userStorage.write("gclid", gclid, expirationTime);
        return gclid;
    }

    return null;
}
```

***

#### 2. `this.userStorage.read(name)`

Reads a stored value from user storage based on the given key.

**Parameters**

| Placeholder | Description                             | Type     | Required                                      | Example   |
| ----------- | --------------------------------------- | -------- | --------------------------------------------- | --------- |
| `<NAME>`    | The key under which the value is stored | `string` | <i class="fa-square-check">:square-check:</i> | `"gclid"` |

**Example**

```js
async function() {
    const gclid = this.userStorage.read("gclid");
    return gclid || "";
}
```

***

#### 3. `this.userStorage.delete(name)`

Deletes a stored value from user storage by key.

**Parameters**

| Placeholder | Description                             | Type     | Required                                      | Example   |
| ----------- | --------------------------------------- | -------- | --------------------------------------------- | --------- |
| `<NAME>`    | The key under which the value is stored | `string` | <i class="fa-square-check">:square-check:</i> | `"gclid"` |

**Example**

```js
async function() {
    this.userStorage.delete("gclid");
    return "";
}
```

***

### Best Practices

* Always set a **realistic expiration** for stored values to prevent unnecessary data buildup.
* Combine client-side values with server-side logic for advanced tracking use cases.

***

### Summary

The `userStorage` API enables persistent, scoped storage for identifiers and session-related data inside server-side variables. It offers a simple but powerful interface to **write, read, and delete** values securely within the JENTIS TWIN-Browser runtime.

For additional guidance or complex implementations, please refer to the Server-Side Variable Guide or contact JENTIS Support.


---

# 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/variables/server-side-variables/public-function-scope/user-storage-per-tool-instance.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.