Skip to main content

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

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

  1. The data can be used as input for our machine learning algorithms for AI Predictive Targeting and Contextual Bandit experiments.
  2. 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 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 is typically evaluated once on the page based on the custom data's value. It won't be reevaluated 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 will retain 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 won't reset. It will retain its last value across multiple visits from the same visitor.
    • Use case: Target a visitor who has made purchases on the site three times historically.
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 issues, 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 PAGE scope, this issue won't occur.

Feature Experimentation (SDKs)​

With SDKs for Feature Experimentation, there's no concept of a "page" in terms of scope. Custom data values are passed explicitly at the time of evaluation. Here, the scope primarily defines how the custom data is stored on Kameleoon's servers and which value is automatically retrieved (for example, by using getRemoteVisitorData()).

By default, the API retrieves only VISITOR-scoped values. These values are attached to the visitor and used during evaluation.

Reporting and display of custom data​

How custom data appears in your reports also depends on your experimentation type.

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: All values set during a visit will be displayed on the Results page to break down 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 visits according to the categories of pages viewed.
  • Single type & visit scope: The Results page will only display 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 shows all values 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): Any values assigned during the visit will be shown on the Results page for a detailed breakdown of the visits. If a value is assigned to a visit, whether once or repeatedly, it will be displayed 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 does not 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 will only keep and report the last value 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 for breakdowns by the last value within a visit or across multiple visits for a visitor, respectively.
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.

By default, custom data are attributes related to users; however, if you'd like to use custom data as properties of a conversion, you can use metadata.

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.

note

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

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​

For Feature Experimentation (SDKs), custom data values are acquired and sent to Kameleoon solely via SDK method, meaning they are explicitly passed through your SDK integration (for example, using methods like addData() or setCustomData() depending on the specific SDK).

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.