> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kameleoon.API.Data

> Reference for the Kameleoon.API.Data methods that set custom data and read or write Kameleoon LocalStorage data.

This module provides methods to set **custom data** for tracking customer or visit characteristics. It also includes data management methods to retrieve and write data in Kameleoon's unified LocalStorage.

## readLocalData

The `readLocalData()` method reads local data you previously stored through `writeLocalData()`. The engine retrieves this data from unified Local Storage, which bypasses standard storage limitations.

```javascript theme={null}
var userId = Kameleoon.API.Data.readLocalData("myUserId");

if (userId) {
  Kameleoon.API.Data.retrieveDataFromRemoteSource(userId, function (data) {
    console.log(data.returningVisitor);
  });
}
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| key | String | Key of the data to retrieve. This field is mandatory. |

**Return value**

| Name | Type | Description |
| - | - | - |
| value | String | Value of the data. |

## performRemoteSynchronization

The `performRemoteSynchronization()` method triggers a Server Synchronization Call (SSC) to the Data API. This call retrieves visit history stored on Kameleoon backend servers for the current visitor and writes it to LocalStorage. The synchronization ensures that the data is accessible through the Activation API and available for targeting. This method typically runs automatically for cross-device reconciliation or Safari ITP. It doesn't require manual invocation.

```javascript theme={null}
Kameleoon.API.Data.performRemoteSynchronization("customDataName", "customDataValue", false);
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| key | String | Key of the custom data serving as the mapping identifier (for example, account ID or email). If omitted, the method uses the default identifier configured for cross-device reconciliation in the Kameleoon App. |
| value | String | Current visitor identifier value used for the Data API call. If omitted, the method uses the current value of the custom data provided in the first argument. |
| currentVisitOnly | Boolean | When active, the SSC requests data only for the current visit. Use this optimization to refresh custom data values acquired via the Data API or Server-to-Server integration. If omitted, the method defaults to **false**. |

## resetCustomData

The `resetCustomData()` method resets a custom data value.

```javascript theme={null}
Kameleoon.API.Data.resetCustomData("MyCustomDataName");
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| name | String | Name of the custom data as defined in the Kameleoon App. This field is mandatory. |

## retrieveDataFromRemoteSource

The `retrieveDataFromRemoteSource()` method retrieves data stored on a remote Kameleoon server with the specified **key**. This method supports retrieving data previously stored through the Data API. Use this for quick storage and retrieval of large data volumes for visitors.

This asynchronous mechanism requires a **callback** function when the server call completes.

```javascript theme={null}
if (location.href.indexOf("loginPage") != -1) {
  Kameleoon.API.Core.runWhenConditionTrue(function () {
    return typeof dataLayer != null;
  }, function () {
    dataLayer.forEach(function (map) {
      if (map.userId) {
        Kameleoon.API.Data.retrieveDataFromRemoteSource(userId, function (data) {
          Kameleoon.API.Data.setCustomData("known_user", data.knownUser);
        });
      }
    });
  }, 200);
}
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| key | String | The lookup key. This field is mandatory. |
| callback | Function | Function that runs after the method retrieves the data. It receives a **data** argument, which is a JS Object. This field is mandatory. |

## setCustomData

The `setCustomData()` method sets a custom data value.

```javascript theme={null}

// Single Type Custom Data
Kameleoon.API.Data.setCustomData("mySingleCustomDataName", "myNewValue"); // --> "myNewValue"

// List Type Custom Data
Kameleoon.API.Data.setCustomData("myListCustomDataName", "myFirstValue"); // --> ["myFirstValue"]
Kameleoon.API.Data.setCustomData("myListCustomDataName", "mySecondValue"); // --> ["myFirstValue", "mySecondValue"]
Kameleoon.API.Data.setCustomData("myListCustomDataName", ["myThirdValue", "myFourthValue"]); // --> ["myFirstValue", "mySecondValue", "myThirdValue", "myFourthValue"]
Kameleoon.API.Data.setCustomData("myListCustomDataName", ["myThirdValue", "myFourthValue"], true); // --> ["myThirdValue", "myFourthValue"]

// Count List Type Custom Data
Kameleoon.API.Data.setCustomData("myCountListCustomDataName", "myFirstValue"); // --> {value: 'myFirstValue', count: 1}
Kameleoon.API.Data.setCustomData("myCountListCustomDataName", "myFirstValue"); // --> {value: 'myFirstValue', count: 2}
Kameleoon.API.Data.setCustomData("myCountListCustomDataName", "mySecondValue"); // --> {value: 'myFirstValue', count: 2}, {value: 'mySecondValue', count: 1}
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| CustomDataNameOrIndex | String or Number | Name or Index of the custom data as defined in the Kameleoon App. (the index appears in the 'INDEX' column of the Custom Data dashboard). This field is mandatory. |
| value | String, Number, Boolean, Array | Value of the custom data. The argument provided should match the type declared for this custom data in the Kameleoon app. This field is mandatory. **Note that `setCustomData()` accepts String, Number, and Boolean when you set the `Type` to `Single`. If you set the `Type` to `List` or `Count List`, it accepts an array of String or Number.** |
| overwrite | Boolean | **Optional boolean**. When `true`, the new value overwrites existing custom data. When `false` or omitted: **Lists/Count Lists** append values (all values appear in reports); **Single types** overwrite (only the most recent value appears); **Page-scoped Custom Data** (all types) append values. |

## writeLocalData

The `writeLocalData()` method records local data in the visitor's browser for later retrieval through `readLocalData()`. The engine stores this as unified session data in Local Storage, bypassing standard storage limitations. Data becomes available immediately for retrieval in the same tab through RAM caching, while the physical write occurs asynchronously.

```javascript theme={null}
Kameleoon.API.Data.writeLocalData("myData", "myDataValue", true);
```

**Arguments**

| Name | Type | Description |
| - | - | - |
| key | String | Key (name) of the data to write. This field is mandatory. |
| value | String | Value of the data to write. This field is mandatory. |
| persistent | Boolean | Toggle data persistence. Non-persistent data expires after 1 hour, while persistent data remains for 30 days. If omitted, the method defaults to **false**. |