Custom data

Configure and use custom data in Kameleoon to target visitors based on attributes and analyze experiment results with data breakdowns.

Custom data is one of the most powerful features in Kameleoon. Custom data allows any data type association with each visitor and serves two purposes:

1. To generate targeting segments based on visitor data, including creating advanced segments for experiments and personalizations. Examples of custom data include age, previous purchases, current cart amount, and favorite category. Typically, custom data is closely tied to the specificities of a business. For example, if you operate a marketplace website, you can create custom data that indicates whether a visitor is primarily a “buyer” or a “seller.”
2. To provide advanced analysis reports by breaking down results according to custom data, as well as filtering experiment and personalization reports using any stored data value.

Custom data 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 you set a custom data value, Kameleoon stores it locally on the server or on the user’s device, depending on whether you use a server-side SDK or client-side SDK, including the app file (engine.js), rather than retrieving it from a remote Kameleoon server. This local storage means you can retrieve data in subsequent page views of the same visit or in future visits. When Kameleoon loads, any custom data that you’ve written becomes automatically available for use later, either through the Activation API or the SDKs.

If you use Kameleoon Web Experimentation, Kameleoon unifies the LocalStorage implementation, so it automatically handles user journeys spanning multiple subdomains, as long as you follow the implementation guidelines for unified session data across subdomains. Kameleoon also saves and loads custom data and handles complex issues, such as concurrent access from multiple tabs on the same website.

You can also send any custom data value to Kameleoon data collection servers as part of the standard tracking process, which serves three purposes:

1. The data is available for reporting purposes and you can use it 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). You must link custom data to a goal as metadata to filter or break down conversion data based on metadata value.

When you set custom data as goal metadata, Kameleoon automatically uses the most recently tracked value of the custom data in reporting for each goal conversion. You can manually set the custom data’s value using the metadata parameter of the processConversion method of the Activation API, or the trackConversion method of the SDK.

2. Machine learning algorithms can use the data as input for AI Predictive Targeting and Contextual Bandit experiments.
3. Backend servers store the data so you can retrieve it using the Data API.

Version 2.3 of Intelligent Tracking Prevention (ITP) restrictions on Safari browsers clears LocalStorage after 1 second, meaning that if a returning visitor comes back after 1 second, you can’t avoid additional synchronization server calls to retrieve custom data in Safari. However, Kameleoon optimizes these calls and only makes them when necessary (for example, if the 1 second period has elapsed). For more information about the solution, refer to the ITP management article.

Core technical concepts: Scope of custom data

The scope of custom data is crucial as it determines how the value behaves for targeting and how it’s stored and displayed in reporting. Custom data’s configuration depends on your implementation type: Web Experimentation or Feature Experimentation (SDKs) and how and when you expect to use the custom data.

Scope for targeting

How custom data behaves for targeting differs significantly between Web and Feature Experimentation.

Web Experimentation (engine.js)

For Web Experimentation, targeting evaluates once on the page based on the custom data’s value. It doesn’t reevaluate if the custom data’s value changes on the same page. The custom data’s scope dictates its lifespan for targeting:

• Page: The custom data’s value resets after each page view.
  • Use case: Target users who browse (or are on) a specific page type (product pages, for example).
• Visit: The custom data’s value resets after each visit. The custom data retains its last value when a user navigates from page to page within the same visit.
  • Use case: Target a visitor who signed up for a newsletter during their current visit.
• Visitor: The custom data’s value doesn’t reset. It retains its last value across multiple visits from the same visitor.
  • Use case: Target a visitor who has made purchases on the site 3 times historically.

If there’s a risk that you may get a custom data value after Kameleoon initializes and executes its first targeting, set the scope to PAGE. If the scope isn’t set to PAGE, the current custom data value may be “late” and cause targeting issues, especially when running an experiment targeting visitors that move to a product page after browsing a category page and getting a new value after just a few seconds. With a PAGE scope, this issue doesn’t occur.

Feature Experimentation (SDKs)

With SDKs for Feature Experimentation, there’s no concept of a “page” in terms of scope. You pass custom data values explicitly at the time of evaluation. Here, the scope primarily defines how Kameleoon stores the custom data on its servers and which value it automatically retrieves (for example, by using getRemoteVisitorData()).

By default, the API retrieves only VISITOR-scoped values. The API attaches these values to the visitor for use during evaluation.

Reporting and displaying custom data

How custom data appears in your reports also depends on your experimentation type, the custom data’s type and scope, and whether you use the optional overwrite parameter with setCustomData().

Default logic (when overwrite parameter is false or omitted)

For Web Experimentation (results page)

On the Results page for Web Experimentation, all custom data types can have multiple values on the same page and during the same visit. The following rules apply for displaying these values:

• Single type & page scope: The Results page displays all values you set during a visit to break down visits. If you set a value once or multiple times, it displays the same way (for example, Kameleoon tags the visit with that value).
  • Use case: Break down visits according to the categories of pages viewed.
• Single type & visit scope: The Results page displays only the last value you 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 shows all values it received for that custom data for the visitor, which covers all previous visits exposed to or influenced by the experiment, within the selected timeframe.
  • Use case: Break down visitors according to the number of purchases they’ve made on the site across all visits.
• All combinations for types/scopes (list, countList/page, visit, visitor): The Results page shows any values you assigned during the visit for a detailed breakdown of the visits. If you assign a value to a visit, whether once or repeatedly, it displays consistently, tagging the visit with that value.
  • Use case: Break down visits according to all the newsletters a user signed up for, the navigation menu links clicked, or filters selected on a category page.

For Feature Experimentation (SDKs)

For Feature Experimentation, custom data reporting operates differently due to the nature of SDK environments, which typically don’t have a “page” concept like web browsers.

• The Page scope doesn’t apply for reporting purposes in Feature Experimentation because SDKs often run in server-side or mobile environments where a distinct “page load” event (which would trigger a data reset) doesn’t inherently exist.
• For any given custom data, Kameleoon stores and reports only the last value it received during a visit. This approach is efficient and relevant for environments where the most recent state of a user’s attributes within a continuous session is generally what matters for feature decisions.
• The Visit and Visitor scopes behave as expected for reporting, allowing you to break down by the last value within a visit or across multiple visits for a visitor, respectively.

Unlike custom data, where Kameleoon keeps only the last value received during a visit, data points collected natively by the engine or SDK, such as browser, page URL, or SDK name, show the first value received per visit. At the visitor level, though, each of a visitor’s visits contributes its own value, so a visitor can show more than one value for the same data point, for example a different browser if they use Chrome during one visit and Firefox during another. See Native data point breakdown values for details.

Overriding default behavior with the overwrite parameter

The overwrite (optional boolean) parameter of the setCustomData() method lets you explicitly control how Kameleoon stores custom data values and, consequently, how they appear in reports.

• When overwrite is true: The new value you provide to setCustomData() always replaces any existing values for that custom data key within the current session/visit, regardless of its type (Single, List, Count List) or scope (Page, Visit, Visitor), meaning only the most recently set value is available for targeting and reporting.
• When overwrite is false or omitted: The default logic described in the preceding sections applies.

You can use custom data as metadata when setting up a goal, allowing Kameleoon to attach the custom data’s value to each conversion for reporting and analysis purposes. For more information on creating a goal, refer to the Create a new goal article.

By default, custom data consists of user attributes. However, if you want to use custom data as properties of a conversion, you can use metadata.

Retrieval methods

Kameleoon offers several built-in integrations, 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. Specify the variable’s name in the data layer, and Kameleoon completes the integration automatically once the data layer loads on the page.

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

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

Use the Activation API to set custom data values on the browser (client-side environment). Locate a particular DOM element on the page and use its content as the custom data value. For example, get the current cart amount value from the web page if it displays there and fill the corresponding custom data accordingly.

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

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 written in JavaScript

This option lets you write ad hoc custom JavaScript code. The main rule to follow when setting custom data is that your code must 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 no value is available yet but you’ll get it later on the page, don’t return any value (returning null or undefined is acceptable). The system executes the code again (every 100 ms for the first 1 second after the first invocation, then every 1 second). By convention, returning {"value": null} doesn’t set the custom data but stops the regular execution.

The first execution takes place before Kameleoon’s targeting system triggers, giving you the chance to set up custom data before targeting executes.

Avoid this retrieval method if possible. Write JavaScript code in a different location, such as Tag Manager, an external script file, or inline script in HTML, and use the Activation API method to set the custom data instead.

SDK method

For Feature Experimentation (SDKs), you acquire and send custom data values to Kameleoon only through SDK methods, meaning you explicitly pass them through SDK integration (for example, using methods like addData() or setCustomData() depending on the specific SDK).

For more details regarding using custom data in SDKs, refer to the using visit history article.

Data API / Server to server integration

To set up a server-to-server integration, use the Data API. Using the Data API involves implementing a REST call to Kameleoon servers, specifying the custom data name and value and the visitorCode.

Advanced options

Use this data only locally for targeting purposes

Enabling this option allows you to store the custom data value locally on the user’s device or on the server if you use one of the server-side SDKs. Since Kameleoon won’t store this data on its servers, you can’t use it for analytics in reporting. This feature can be beneficial for privacy or legal reasons. Some customers require that sensitive data isn’t stored outside their systems, but still want to personalize the visitor’s experience based on that data.

Use this custom data as input for AI Predictive Targeting

Enabling this option allows machine learning algorithms to use this custom data as an input. Only Number and Boolean custom data types work with this feature. It’s only available with a subscription 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 and uses it to map several Kameleoon visits to a unique user for cross-device experimentation. Learn more about this feature in the Cross-device experimentation article.

How to use custom data

Targeting condition for segments

The Kameleoon segment builder automatically adds targeting conditions for any custom data that you define. The process is automatic: if the custom data value matches your condition, the segment includes that visitor.

Retrieving values with the Activation API

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

Via the SDKs

The getRemoteVisitorData() method retrieves all custom data collected during the current visitor’s previous visit. For more details, refer to the using visit history article.

Analytical purposes

You can use any custom data (except those marked as local only) as a filter or breakdown option in experiment or personalization result pages. The raw data export tool also provides this information in reports, and you can perform complex queries including custom data (with a dedicated Kameleoon data cluster).

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

For a breakdown with Number type custom data, the results break down with a maximum of 50 possible values. In the case of numerical custom data, this limit doesn’t always make sense.

When you link custom data to a goal as metadata, you can access values only through a Raw Export. An update to the reporting page will let you use metadata as filters directly in the results.

Advanced settings

Custom select box component for targeting conditions

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:

• You can associate raw values with descriptive labels.
• The targeting condition interface displays labels and values dynamically.

This feature is especially useful for integrating with third-party data providers like DMPs and 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 (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.

Only users with access to the Kameleoon platform see the labels you associate with custom data. The labels don’t appear in the JavaScript app file, so website visitors can’t view them. The process stays hidden from the user.

To implement this feature for a specific custom data, provide JavaScript code that returns 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 must be JavaScript objects.
• These objects must have two keys: a value key (containing the actual possible value for the custom data) and a label key (representing the textual description for that value).
• The type of value you provide for the value key must match the custom data’s actual type. For the label key, provide a string.

See the code sample below for an example of how this feature works in practice. In this example, the code makes a remote call to a third-party server (usually a DMP or similar platform) that provides the list of available segments on the platform. You use this code only 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=[e-mail]&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;

Ensure the code runs synchronously and returns its value with blocking behavior. Avoid any asynchronous remote server calls, as they may cause the feature to malfunction.