Kameleoon.API.Data - Kameleoon Documentation

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.

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.

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.

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.

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.

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

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.

APIs

​readLocalData

​performRemoteSynchronization

​resetCustomData

​retrieveDataFromRemoteSource

​setCustomData

​writeLocalData

readLocalData

performRemoteSynchronization

resetCustomData

retrieveDataFromRemoteSource

setCustomData

writeLocalData