Custom data

Custom data is one of the most powerful features offered by Kameleoon. Custom data allows any type of data to be easily associated with each visitor, and is used for two purposes:

1. To generate targeting segments based on visitor data, including creating advanced segments for experiments and personalizations.

Examples of custom data can include a wide range of information, such as age, previous purchases, current cart amount, and favorite category. Typically, custom data is closely tied to the specificities of a given business. For example, if you operate a marketplace website, you may want to create custom data that indicates whether a particular visitor is primarily a "buyer" or a "seller".

2. To provide advanced analysis reports by breaking down the results according to this information, as well as filtering experiment and personalization reports using any stored data value.

It can be of the following types: single, list, or counted list with a string, boolean, or number format and the scope of page, visit, or visitor.

This article serves as a general guide for learning more about custom data and how to use it effectively. If you're interested in creating custom data within the Kameleoon platform, you can refer to the following user guide.

Technical Overview

Once a custom data value is set, it is stored locally on your server or on the user’s device, depending on whether you use a server-side SDK or a client-side SDK, including our application file (engine.js), rather than retrieving it from a remote Kameleoon server. This storage means that the data can be retrieved in subsequent page views of the same visit or in future visits. When Kameleoon is loaded, any custom data that has been written will be automatically available for use later, either through the Activation API or our SDKs.

note

If you use Kameleoon Web Experimentation, our LocalStorage implementation is unified, meaning that user journeys spanning multiple subdomains are automatically handled by Kameleoon, as long as you follow our implementation guidelines for unified session data across subdomains. Kameleoon also takes care of saving and loading custom data, and handling complex issues, such as concurrent access from multiple tabs on the same website.

Any value set for a custom data can also be sent to our data collection servers as part of the standard Kameleoon tracking process, which serves three purposes:

1. The data is available for reporting purposes and can be used to filter or break down visit or visitor data by specific attributes (for example, number of visits or visitors per profile type), or to analyze data (for example, conversions by payment type). Linking custom data to a goal as metadata is required if you plan to filter or break down conversion data based on metadata value.

note

When a custom data is set as a metadata of a goal, Kameleoon will automatically use the most recently tracked value of the custom data in our reporting for each goal conversion. You can manually set the custom data's value by using the metadata parameter of the processConversion method of the Activation API, or the trackConversion method of the SDK.

2. The data can be used as input for our machine learning algorithms for AI Predictive Targeting and Contextual Bandit experiments.
3. The data is stored on our backend servers and can be retrieved using our Data API.

note

The latest version (2.3) of Intelligent Tracking Prevention (ITP) restrictions on Safari browsers clear the LocalStorage after seven days, meaning that if a returning visitor comes back after seven days, additional synchronization server calls to retrieve the content of custom data cannot be avoided in Safari. However, we optimize these calls and only make them if necessary (for example, if the seven day period has elapsed). For more information about our solution, see this article on ITP management.

Core technical concepts / Scope of custom data

The configuration of custom data depends on the purpose:

• Targeting: Targeting is only evaluated once on the page based on the custom data's value. Targeting is not reevaluated if the custom data value changes on the same page. The custom data's scope is also important, with three possible values: PAGE, VISIT or VISITOR:
  • Page: The custom data's value resets after each page. Use case: Target a page type.
  • Visit: The custom data's value resets after each visit. The custom data will keep the last value when moving from page to page. Use case: Target a visitor who signed up for a newsletter during the visit.
  • Visitor: The custom data's value won't reset. The custom data will keep the last value when moving from one visit to another. Use case: Target a visitor who has bought on the site three times.
• Results page: All custom data types can have several values on the same page and during the same visit. The following rules apply:
  • Single type & page scope: All values set during the visit will be displayed on the Results page to break down the visits. If a value is set once or multiple times, it results in the same display (for example, the visit is tagged with that value). Use case: Break down the visits according to the visitor's payment mode on the payment page.
  • Single type & visit scope: The Results page will display only the last value set during the visit to break down visits. Use case: Break down visits by user membership type.
  • Single type & visitor scope: If you use the Visitor view on the Results page and break down by custom data, Kameleoon will display all values received for this custom data for the visitor across previous visits exposed to the experiment, or influenced by it, and for the chosen timeframe. Use case: Break down the visitors according to the number of purchases they made on the site.
  • All combinations of these types/scopes: list, countList/page, visit, visitor: Any values assigned during the visit will be shown on the Results page for a detailed breakdown of the visits. If the same value is assigned once or multiple times, it will be displayed the same way, tagging the visit with that value. Use case: Break down the visits according to all the newsletters the user signed up for. Or break down the visits according to all the navigation menu links clicked or the filters selected on a category page.

note

The Activation API method setCustomData() includes a parameter called overwriteIfCollection. For more details on this method, refer to the Activation API documentation.

caution

If there is a risk that a custom data value may be obtained after Kameleoon's initialization and the associated first targeting execution, we recommend setting the scope to PAGE. If the scope isn't set to PAGE, the current custom data value may be "late" and cause targeting problems, especially when running an experiment targeting visitors that move to a product page after browsing a category page, obtaining a new value after only a few seconds. With a scope of PAGE, this issue would not occur.

note

You can use custom data as metadata when setting up a goal, allowing the custom data's value to be attached to each conversion for reporting and analysis purposes. For more information on creating a goal, refer to this article.

Acquisition Methods

Kameleoon offers various integrations out of the box, which are detailed below.

Data layers

These methods retrieve the custom data's value from a given variable in the data layer for Google Tag Manager, Tealium, or Commander's Act. You must only specify the variable's name in your usual data layer, and integration is automatically done as soon as the data layer is loaded on your page.

tip

We support several levels of hierarchy and array variables in the data layer. For example, you can fetch a value from product.category.name, cart["amount"] or purchases[3].

caution

Kameleoon can set the custom data value only after the data layer is available on your page, which can take several seconds (depending on when you load your tag manager). If you use the custom data as a targeting condition in an A/B test, a noticeable flicker effect can occur.

Activation API

We recommend using our Activation API to set custom data values on the browser (client-side environment). You can locate a particular DOM element on the page and get its content as the value for the custom data, which lets you obtain the current cart amount value if it is displayed on the web page and fill the corresponding custom data accordingly.

caution

The Kameleoon.API.Data.setCustomData() method always overwrites previous existing values for the custom data, except if the type is a List or Counted List, and the third argument is false, in which case, it adds to the existing list.

Custom Code

This option lets you write ad hoc custom JavaScript code. The main rule to follow when setting a custom data is that 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).

If you don't have any value to provide for this custom data yet, but will obtain it later on this page, don't return any value (you can also return null or undefined). Your code will be executed again (every 100 ms for the first three seconds after the first invocation, then every three seconds). By convention, returning {"value": null} will not set the custom data, but will stop your code's regular execution.

Your code's first execution takes place before the Kameleoon targeting system is triggered, giving you the chance to set up your custom data before targeting is executed.

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

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

caution

We advise against using this acquisition method if possible. It is preferable to write your JavaScript code in a different location, such as Tag Manager, an external script file, or inline script code in the HTML code, and then use the Activation API acquisition method to set the custom data.

SDK method

You must use the SDK method addData(), which is documented in all of our SDKs. For more details regarding using custom data in SDKs, please refer to this article.

Data API / Server to Server integration

If you are looking to set up a server to server integration, our Data API is the recommended approach. Using our Data API involves implementing a REST call to our servers, where you will specify the custom data name and value, and the visitorCode.

Advanced Options

Use this data only locally for targeting purposes

Enabling this option allows the custom data value to be stored locally on the user's device or on your server, if you are using one of our server-side SDKs. Since this data will not be stored on our servers, it cannot be used for analytics in our reporting. This feature can be beneficial for privacy or legal reasons. Some customers may require that sensitive data is not stored outside their systems, but still wish to personalize the visitor's experience based on that data.

Use this custom data as input for AI Predictive Targeting

Enabling this option will allow our machine learning algorithms to use this custom data as an input. This feature is only available if you have subscribed to the AI Predictive Targeting add-on.

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 for cross-device experimentation. You can learn more about this feature in this article.

Using Custom Data

Targeting condition for segments

The Kameleoon segment builder will automatically add targeting conditions for any custom data that you define. Everything is done automatically here, and if the value of the custom data corresponds to your condition, this particular visitor will be included in the segment.

Via the Activation API

You can obtain a custom data's current value via Kameleoon.API.CurrentVisit.customData (PAGE or VISIT scopes) or Kameleoon.API.Visitor.customData (VISITOR scope).

Via one of our SDKs

You can use the getRemoteVisitorData() method to retrieve all custom data collected during the current visitor's previous visit. For more details, please refer to this article.

Analytical Purposes

Any custom data (except those marked as local only) can be used as a filter or a breakdown option in our experiment or personalization result pages. This information is also available in reports produced by our raw data export tool, and complex queries including those custom data can be performed (if you opted for a dedicated Kameleoon data cluster).

For a breakdown using custom data of type String, the results will include up to 50 of the most frequently used values for that data.

For a breakdown with a Number type custom data, the results will also be broken down with a maximum of 50 possible values. In the case of numerical custom data, this limit does not always make sense.

When custom data is linked to a goal as metadata, you can currently access its values only through a Raw Export. An update to our reporting page—expected later in Q2—will let you use metadata as filters directly in the results.

Advanced Settings

Implement a custom select box component for the targeting condition associated with this custom data

This feature simplifies the selection of custom data values in targeting conditions by presenting them in a select box instead of a plain text field, making it much easier for end-users to choose the appropriate value for targeting. There are two important points to consider:

• Raw values can be associated with descriptive labels.
• The labels and values are obtained dynamically when the targeting condition interface is displayed.

This feature is especially useful for integrating with third-party data providers, like DMPs or CRMs. For example, if the custom data represents an external segment from a DMP, the user can select "Loyal customers" instead of the internal ID, which is usually a complex string of characters like "8ney4225y65a". The list of defined segments in the DMP is always up-to-date on Kameleoon's interface, so this feature handles the synchronization automatically.

note

The labels associated with custom data are only visible to users who have access to the Kameleoon platform. They are not included in the JavaScript application file, so website visitors cannot view them. The process is hidden from the user.

To implement this feature for a specific custom data, you must provide JavaScript code that will return an array of objects representing the possible values along with their labels synchronously. The array must meet the following requirements:

• All elements in the array should be JavaScript objects.
• These objects should have two keys: a value key (containing the actual possible value for the custom data), and a label key (representing the textual description for this particular value).
• The content type for the value key should correspond to the custom data's actual type. For the label key, you should provide a string as content.

Check out the code sample below for an example of how this feature can be used in practice. In this example, a remote call is made to a third-party server (usually a DMP or similar platform) that provides the list of available segments defined on the platform. It's important to note that this code is only used to build the selection interface for the Kameleoon end-user.

var xhr = new XMLHttpRequest();
xhr.open("GET", "https://third-party.dmp.com/get-segments?login=XXXX@XXXX.com&password=XXXX", false);

var segments = [];
xhr.onreadystatechange = function() {

    if (this.readyState === XMLHttpRequest.DONE && this.status === 200) {
        var data = JSON.parse(xhr.response);
        data.map(function (segment) {
          if (segment.segment_uuid && segment.name !== "undefined") {
            segments.push({"label": segment.name, "value": segment.segment_uuid});
          }
        });
    }
}

xhr.send();
return segments;

caution

It is important that your code runs synchronously and returns its value with a blocking behavior. We advise avoiding any asynchronous remote server calls, as this may cause the feature to malfunction.