imagino - Kameleoon Documentation

imagino computes attributes and cohorts for each known customer, but Kameleoon can’t use them until imagino sends the data. This integration sends that data to Kameleoon, indexed on a customer identifier. On your website, Kameleoon reads the customer identifier, retrieves the attributes, and stores them as custom data that you use in segments.

How imagino fits into your workflow

Send imagino data to Kameleoon: Connect imagino to your Kameleoon site, define the data structure, and map its attributes to Kameleoon.
Retrieve imagino data in Kameleoon: Choose the lookup key, understand the data that imagino sends, and create custom data that reads each attribute on your website.
Target visitors with an imagino segment: Create a segment from the custom data and use it in your experiments.

Before you begin

To configure this integration, you need the following information from Kameleoon:

Send imagino data to Kameleoon

imagino sends its data to Kameleoon through a connection that you set up in imagino. Each attribute that imagino sends must map to its own custom data in Kameleoon, with a matching format. Changing the credentials of an existing connection can affect your existing data sources and projects.

Set up the connection in imagino

Connect imagino to your Kameleoon instance and select the project that receives the data.

Set up a connection with the customer’s Kameleoon instance.

The Kameleoon connection in imagino, with the Client ID and secret fields.

Select the project that receives the data.

The Project field in the Data Write capability options, containing the Kameleoon project ID.

When the connection works, the Kameleoon connection shows Connected.

Define the data structure to send

Define the JSON structure of the data that imagino pushes to Kameleoon. Open the Cataloging capability options in imagino, and define the JSON structure of the data to push in Custom Properties.

The Custom Properties field in the Cataloging capability options, containing a JSON list of properties and their types.

imagino makes the structure available as properties of the Visitor object in its Data Catalog.

The Visitor object in the imagino Data Catalog, listing the Visitor Code, Purchases Count, Has Purchases, and Full Name properties with their types.

When the structure is available, the Visitor object lists each property with the type that you defined.

Map imagino data to Kameleoon

Map each imagino attribute to the field that Kameleoon expects.

Activate the imagino audience data to push to Kameleoon.

The Data Update overview in imagino, with Kameleoon as the connection, Visitor as the target object, and a data mapping of 4 items.

Edit the audience data mapping to define the fields from imagino, and the fields expected in Kameleoon (previously configured structure).

The Data Update settings in imagino, with Insert Only as the method, Kameleoon as the data source, and Visitor as the object to update. The data mapping maps Visitor Code and Full Name.

Each row in the Data Mapping table maps one source field to one target field.

The Data Mapping table in imagino with sample values for four fields: a visitor code, a full name, a boolean, and a number.

Check that Kameleoon receives the data

Confirm that Kameleoon returns the imagino attributes for a known visitor. Call the Kameleoon Data API with your site code and the lookup key of a known visitor. The response is a JSON object that contains the attributes that imagino sent for that key. If the response has no data for a known visitor, the lookup key that your website reads doesn’t match the key that imagino uses. Contact your Kameleoon Technical Account Manager to check the key and the data that Kameleoon received.

A Data API GET request to the map endpoint, with the site code and key parameters, returning a JSON object with the hasPurchases, purchasesCount, and fullName attributes.

Retrieve imagino data in Kameleoon

Kameleoon receives the visitor attributes that imagino computes, stores them on its Data API servers, and exposes them in the browser. Your website reads the lookup key, and the Data API returns the attributes. The flow has four parts:

imagino computes the attributes and cohorts of each known customer.
imagino sends them to Kameleoon, indexed on a customer identifier (the lookup key).
On your website, Kameleoon reads the same identifier and queries the Data API to retrieve the attributes.
Kameleoon stores the attributes as custom data, which you use in segments for targeting and reporting.

Choose the lookup key

The lookup key is the identifier that imagino uses when it sends data to Kameleoon. It is almost always your own customer identifier, such as a CRM ID, an account ID, or a hashed email. The identifier must be available on the front end (DOM, cookie, dataLayer, and so on) so that Kameleoon can retrieve the right record.

Don’t use Kameleoon.API.Visitor.code unless imagino is explicitly configured to index its data on the Kameleoon visitorCode. The browser generates this code. imagino doesn’t know it by default, and it doesn’t follow the customer across devices. Using it means querying the Data API with a key that doesn’t exist, so the query returns nothing.

Common lookup key sources:

DataLayer: window.dataLayer[0].userId
Existing custom data: Kameleoon.API.Visitor.customData["Account ID"]
First-party cookie: value extracted from document.cookie

Understand the data that imagino sends

imagino sends a flat JSON object, with one entry per attribute:

{
  "USER_CAGNOTTE": 55,
  "SEGMENT_NAME": "Birthday",
  "USER_IS_PLUS_MEMBER": "TRUE",
  "USER_IS_PLUS_STATUS": "active"
}

The payload is a set of key/value pairs. Each attribute has its own type (string, boolean, number) and must map to its own custom data, with the matching Kameleoon format. The mapping configured in imagino must contain only the attributes that you need for targeting. You don’t need to send directly identifying personal data, such as an email address, to Kameleoon. If you still need a sensitive attribute for targeting, you can use either of the following options, or combine them:

Encrypt or hash the data at the source, in imagino, before sending it. Kameleoon then receives only the encrypted value, and targeting runs on this value.
Enable Use this data only locally for targeting purposes on the custom data. The value stays stored on the visitor’s device and never reaches the Kameleoon reporting servers.

The Use this data only locally for targeting purposes option turned on in the custom data options.

Create the custom data

Create one custom data in Kameleoon for each imagino attribute that you want to target. Choose the implementation that matches the number of imagino attributes that you need. In the code examples below, replace window.dataLayer[0].userId with the lookup key source that matches your website, for example Kameleoon.API.Visitor.customData["Account ID"].

Single attribute
Multiple attributes

Use this implementation when you need only one imagino attribute. All the logic lives in the custom data, and you don’t need to change the global script.Create a custom data with:

Retrieval method: Custom JavaScript code
Type and Format: those of the attribute (Single / String in the example below)
Scope: Page

// 1. Lookup key: the identifier imagino uses to send the data
var lookupKey = window.dataLayer && window.dataLayer[0] && window.dataLayer[0].userId;

// No identifier yet: return nothing, Kameleoon runs the code again
if (!lookupKey) return;

window.kImagino = window.kImagino || {};

// 2. Only one Data API call per page
if (!window.kImagino.requested) {
  window.kImagino.requested = true;
  Kameleoon.API.Data.retrieveDataFromRemoteSource(lookupKey, function (data) {
    window.kImagino.data = data || {};
  });
}

// 3. Response not received yet: return nothing, Kameleoon runs the code again
if (!window.kImagino.data) return;

// 4. Return the attribute you need
var value = window.kImagino.data["USER_HOTEL_SEGMENTATION_CLUSTER"];
return (value === undefined || value === null)
  ? { "value": null }
  : { "value": String(value), "overwrite": true };

The Edit custom data screen with Custom JavaScript code as the retrieval method, showing the script that returns the selected attribute.

Use this implementation when you need several imagino attributes. Kameleoon calls the Data API only once per page and fills all the custom data from this single response.Add the following block to your project’s Global custom script, and adapt the MAPPING object to your attributes:

(function () {
  // 1. Map each imagino attribute to the name of a Kameleoon custom data
  var MAPPING = {
    "USER_CAGNOTTE":       "Imagino cagnotte",
    "SEGMENT_NAME":        "Imagino segment",
    "USER_IS_PLUS_MEMBER": "Imagino PLUS MEMBER",
    "USER_IS_PLUS_STATUS": "Imagino PLUS STATUS"
  };

  window.kImagino = { loaded: false, data: {} };

  // 2. Wait until the lookup key is available on the page
  Kameleoon.API.Core.runWhenConditionTrue(function () {
    return !!(window.dataLayer && window.dataLayer[0] && window.dataLayer[0].userId);
  }, function () {
    // 3. A single Data API call for the whole page
    Kameleoon.API.Data.retrieveDataFromRemoteSource(window.dataLayer[0].userId, function (data) {
      window.kImagino.data = data || {};
      window.kImagino.loaded = true;

      // 4. Fill all the mapped custom data in a single pass
      Object.keys(MAPPING).forEach(function (attribute) {
        var value = window.kImagino.data[attribute];
        if (value === undefined || value === null) return;
        Kameleoon.API.Data.setCustomData(MAPPING[attribute], String(value));
      });
    });
  }, 200);
})();

Then create one custom data per MAPPING entry, each with:

Retrieval method: Kameleoon Activation API
Type and Format: those of the attribute
Scope: Page

The Global custom script in the Kameleoon project, with the MAPPING object that links imagino attributes to custom data names.

The Custom data list then shows one entry for each mapped attribute, with its value.

The Custom data list with five imagino custom data entries, each with its value.

If the list custom data contains attribute names instead of values, the code stores Object.keys(data) instead of reading data[attribute].

When the task works, each custom data holds the value of its imagino attribute for the page. If the custom data stays empty, the identifier isn’t available yet when the code runs, or the custom data scope isn’t Page. If the segment doesn’t match on the first page view, Kameleoon evaluated targeting before the asynchronous response arrived. Use the Custom JavaScript code retrieval method to benefit from the reruns, or check that the custom data scope is Page.

For more information about custom data types, scopes, and advanced options, see Custom data.

Target visitors with an imagino segment

A segment that uses an imagino custom data includes the visitors whose value matches the condition that you set. You can use the segment in any of your experiments.

Create a segment from the imagino custom data

Create a segment that includes visitors with a given imagino value.

Click Settings > Segments > New segment.
Enter the required information and click Continue.
Select the custom data under the Custom data dropdown.
Click Create.

The segment definition with a Custom data condition: visitors whose Imagino segment custom data is equal to Birthday.

You can now use this segment in your experiments.

Integrations

​How imagino fits into your workflow

​Before you begin

​Send imagino data to Kameleoon

​Set up the connection in imagino

​Define the data structure to send

​Map imagino data to Kameleoon

​Check that Kameleoon receives the data

​Retrieve imagino data in Kameleoon

​Choose the lookup key

​Understand the data that imagino sends

​Create the custom data

​Target visitors with an imagino segment

​Create a segment from the imagino custom data

How imagino fits into your workflow

Before you begin

Send imagino data to Kameleoon

Set up the connection in imagino

Define the data structure to send

Map imagino data to Kameleoon

Check that Kameleoon receives the data

Retrieve imagino data in Kameleoon

Choose the lookup key

Understand the data that imagino sends

Create the custom data

Target visitors with an imagino segment

Create a segment from the imagino custom data