# 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.