Skip to main content

Custom data

Custom data is one of the most powerful features in Kameleoon. Custom data allows any data type association 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 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 a custom data value is set, it is stored locally on the server or on the user’s device, depending on whether a server-side SDK or a client-side SDK is used, including the application file (engine.js), rather than retrieving it from a remote Kameleoon server. This storage means that 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 the SDKs.

note

If Kameleoon Web Experimentation is used, the LocalStorage implementation is unified, meaning that user journeys spanning multiple subdomains are automatically handled by Kameleoon, as long as implementation guidelines for unified session data across subdomains are followed. Kameleoon also saves and loads custom data and handles complex issues, such as concurrent access from multiple tabs on the same website.

Any value set for custom data can also be sent 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 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 to filter or break down conversion data based on metadata value.
note

When custom data is set 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 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 machine learning algorithms for AI Predictive Targeting and Contextual Bandit experiments.
  2. The data is stored on backend servers and can be retrieved using the 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, Kameleoon optimizes these calls and only makes them if necessary (for example, if the seven day 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 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, 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, 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, the custom data's type and scope, whether the optional overwrite parameter was used 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: 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.

Overriding default behavior with the overwrite parameter​

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

  • When overwrite is true: The new value provided to setCustomData() will always replace 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 that only the most recently set value will be available for targeting and reporting.
  • When overwrite is false or omitted: The default logic as described in the sections above will apply.
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 the Create a new goal 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.

Retrieval 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. Specify the variable's name in the data layer, and Kameleoon automatically completes the integration as soon as the data layer loads on the page.

tip

Kameleoon supports 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​

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, 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 JavaScript 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 no value is available yet but will be obtained later on the page, do not return any value (returning null or undefined is also acceptable). The system executes the code 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 the regular execution.

The first execution takes place before the Kameleoon targeting system is triggered, providing the chance to set up custom data before targeting executes.

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

Avoid using this retrieval method if possible. Write 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 retrieval method to set the custom data.

SDK method​

For Feature Experimentation (SDKs), custom data values are acquired and sent to Kameleoon solely via SDK methods, meaning they are explicitly passed 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​

If looking to set up a server-to-server integration, the Data API is the recommended approach. 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 the custom data value to be stored locally on the user's device or on the server if using one of the server-side SDKs. Since this data will not be stored on Kameleoon servers, it cannot be used for analytics in 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 allows machine learning algorithms to use this custom data as an input. This feature is 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, which will be used to map several Kameleoon visits to a unique user for cross-device experimentation. Learn more about this feature in the Cross-device experimentation article.

Using Custom Data​

Targeting condition for segments​

The Kameleoon segment builder will automatically add targeting conditions for any custom data that you define. The process is automatic, 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 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​

Any custom data (except those marked as local only) can be used as a filter or a breakdown option in experiment or personalization result pages. This information is also available in reports produced by the raw data export tool, and complex queries including custom data can be performed (with 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, values are currently accessible only through a Raw Export. An update to the reporting page—expected later in Q2—will allow metadata use 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.

See 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

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