# Global User Storage

## Global `userStorage` API (Server-Side)

The **global `userStorage`** API allows you to **store information for a specific user across all tools**, rather than being restricted to a single tool instance. This enables seamless sharing of identifiers and data points across the entire JENTIS tracking setup for the same user.

This functionality is available within the **server-side variable runtime environment** under the `this` scope and is enabled by setting the **Global Flag** to `true`.

***

### Primary Use Case

Use global user storage when:

* You need to **share user-related data across multiple tools**
* You want a **single persistent ID or value** available to all tool instances
* You’re implementing cross-tool features like unified user identifiers or campaign tracking

Examples:

* Global `client_id`
* Shared `gclid`, `fbclid`, or custom identifiers
* Cross-tool session, signup, or interaction markers

***

### Available Functions

***

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

Writes a value to **global user storage**, making it accessible across all tools.

**Parameters**

| Placeholder              | Description                                                                | Type      | Required                                      | Example                 |
| ------------------------ | -------------------------------------------------------------------------- | --------- | --------------------------------------------- | ----------------------- |
| `<NAME>`                 | The key under which the value is stored                                    | `string`  | <i class="fa-square-check">:square-check:</i> | `"client_id"`           |
| `<VALUE>`                | The value to be stored                                                     | `any`     | <i class="fa-square-check">:square-check:</i> | `"123abcd123.11111111"` |
| `<EXPIRATION TIMESTAMP>` | Expiration in milliseconds since epoch                                     | `number`  | <i class="fa-square-check">:square-check:</i> | `1740555149453`         |
| `<GLOBAL FLAG>`          | If `true`, stores the value in global user storage (not per-tool instance) | `boolean` | <i class="fa-square-check">:square-check:</i> | `true`                  |

**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; // e.g., ~3 months
        this.userStorage.write("gclid", gclid, expirationTime, true); // global write
        return gclid;
    }

    return null;
}
```

***

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

Reads a value from global user storage.

**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"` |
| `<GLOBAL FLAG>` | If `true`, reads the value from global user storage | `boolean` | <i class="fa-square-check">:square-check:</i> | `true`    |

**Example**

```js
jsCopyEditasync function() {
    const gclid = this.userStorage.read("gclid", true); // global read
    return gclid || "";
}
```

***

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

Deletes a value from global user storage.

**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"` |
| `<GLOBAL FLAG>` | If `true`, deletes the value from global user storage | `boolean` | <i class="fa-square-check">:square-check:</i> | `true`    |

**Example**

```js
jsCopyEditasync function() {
    this.userStorage.delete("gclid", true); // global delete
    return "";
}
```

***

### ✅ Best Practices

* Use **global storage** only when values are **meant to be shared across all tools**.
* Always set a realistic **expiration timestamp** to avoid stale or unnecessary data.
* Avoid storing sensitive or tool-specific values globally—use regular `userStorage` for scoped persistence.

***

### Summary

The **global `userStorage`** API is essential for scenarios where **user-specific data must persist across all tools** within the JENTIS platform. It enables consistent, unified tracking and identifier handling for a seamless cross-tool experience.

For tool-scoped storage, refer to the `userStorage` API (per tool) or `toolInstanceStorage` API for shared (non-user-specific) storage.

Need help deciding what scope is right for your use case? Contact JENTIS Support.