Skip to main content

Create custom data

Creating custom data enables you to target visitors according to data already available, like user account information.

All of your custom data is available on the Custom data page in the Configure menu of the App where you can create and manage custom data.

Create new custom data​

To create new custom data:

  1. Click Settings > Custom data
  2. Click New custom data in the top right of the page.

You must fill in several fields to set up custom data.

Structure of the creation pop-in​

  1. Name the new custom data.
  2. Select a project.
  3. Tell Kameleoon how to retrieve custom data.

Custom data name​

Give your custom data an easily identifiable name.

If several websites are selected, you must ensure that custom data is being pulled from all sites.

You can have a maximum of 255 active custom data.

Value retrieval​

Retrieval Method​

Choose the custom data's value retrieval method in the dropdown menu.

The main tag management tools are:

  • GTM data layer (dataLayer)
  • Commanders Act data layer (tc_vars)
  • Tealium (utag.data & utag_data)

For these tag managers, you must indicate the name of the variable you want to retrieve.

If you choose to use GTM dataLayer, proceed as follows to retrieve values:

  • If the key is in level 1 of the dataLayer, enter name in the Variable Name field.
  • If the key is in level 2 of the dataLayer, enter properties.countryCode in the Variable Name field.

If you choose to use a custom JavaScript code to retrieve the value you need, check the code and be careful if you're using scripts.

When you're setting up custom data, your code should return an object with two keys: value, with the value you want to provide for this custom data, and (optionally) override, with a boolean value (false by default). The code will be executed again: every 100 ms for the first three seconds after the first invocation, then every three seconds.

Here is an example:

if (! window.myObject) return null; 
// custom data will not be set, but code will run later again

if (window.myObject) return {"value": window.myObject.x, "overwrite": true}; 
// returning a value and setting the custom data

if (window.someObject.value == 3) return {"value": null} 
// stopping the periodic execution of the code, without setting the custom data

If the Kameleoon Activation API option is selected, your website must make regular calls to the Kameleoon Activation API.

If you use Kameleoon Feature Experimentation and one of our SDKs, you need to use the Kameleoon SDK method.

Type​

Select the format of the data to be retrieved in the dropdown menu.

The data type can be:

  • single (example: 127)

  • list (example: 126, 127, 128; shoes, dress, coat)

  • count list of (example: shoes: 3, dress: 1, coat: 1)

  • string (example: woman dress)

  • boolean (example: female = "true/false")

  • number (example: cart amount = "127")

Scope​

Select your custom data's scope in the dropdown menu:

  • Page: For each new page, Kameleoon resets data value. For example, cart amount.
  • Visit: The value of the data is reset at each new visit by the visitor. For example, geolocation.
  • Visitor: The unit of data relates to the visitor and not to the visit. For example, female = true.

Options​

Click Next to access available options for your custom data.

Use this data only locally for targeting purposes​

If your custom data is used solely for targeting, you don't need to store it on the server. In this scenario, you should use the LocalData API, which helps conserve server space by not counting towards the limit of 255 active custom data points. However, please note that custom data managed via the LocalData API cannot be used for reporting on the Results page.

If you choose to store custom data on the server, be cautious not to save sensitive information. Also, be aware that the value of any custom data sent to the server is limited to 1,000 characters.

Use this custom data as input for AI Predictive Targeting​

To use the machine learning option, you must first activate Audiences.

If AI Predictive Targeting is enabled on your project, you must choose whether to include this custom data in the predictive model. Do not activate this option if the custom data is highly targeted (for example, specific to individual visitors or very small segments).

Only Number and Boolean type custom data are accepted. Avoid adding sensitive data such as dates, timestamps, or unique visitor identifiers (like email addresses or customer account numbers), as these elements are unsuitable for predictive models.

Use this custom data as a unique identifier for cross-device history reconciliation​

When activated, Kameleoon treats this custom data as a unique identifier for your visitors, which will be used to map several Kameleoon visits to a unique user. Learn more here.

Save the values for the targeting condition associated with the custom data point​

This option allows you to define a specific list of values that will then be available for this custom data in the segment builder.

In the New custom data pop-in (first page of the creation flow), click Paste a sample code to get a code example.

Your code must synchronously return a JavaScript array of objects. Each object in this array should represent a possible value for the custom data and must include:

  • A value key, containing the actual data (its type must match the custom data's defined type).
  • A label key, providing a string description for that value.

Example:

return [{value:'q2f6hsbzpf', label:'First segment'},
{value:'8ney4225y65a', label:'Other segment'},
{value:'3h6vjtz26b', label:'Loyal users'}];

If the format is incorrect, an error message will appear when you click Next.

Once you've entered your JavaScript, click Next > Create.

To learn how to use custom data values in the segment builder, refer to this article.

Define a custom data as targeting condition​

To add a custom data to a new segment:

  1. Select your desired data in the Custom data tab of the Conditions column.
  2. In the dropdown menu, determine the custom data's required value for a user to be targeted.
  3. Include/exclude visitors meeting the custom data condition.

Depending on the type of custom data, the targeting condition's configuration changes (“is true/is false”, “contains”, “is equal to”).

Filter/breakdown by custom data on the results page​

On an experiment's results page, you can filter or breakdown the results according to a custom data associated with the experiment.

More about custom data in our developer documentation