Target your imported audiences - Kameleoon Documentation

Data warehouse integrations are available as a premium add-on for Kameleoon’s Web Experimentation and Feature Experimentation module. For more information, contact your Customer Success Manager.

Your data warehouse already knows which visitors belong to a group, such as everyone born in London. To use that group in a campaign, Kameleoon must receive the group membership for each visitor. Each Data Ingestion Task polls one audience, and a custom data holds every audience that a visitor belongs to. The result is that a campaign can target visitors by their warehouse audience. Kameleoon supports data warehouse integrations from the following providers:

BigQuery
Snowflake
Redshift
Databricks

Choose your targeting approach

Pick the approach that matches what you want to target:

Target a pre-built audience from an Ingestion Task (for example, all visitors in “The Londoners”): follow Target your imported audiences in a Kameleoon experiment. You create one custom data that lists every Ingestion Task audience, then build segments from it.
Target a specific visitor attribute (for example, place_of_birth with many different cities): follow Targeting imported audiences by attributes. You add the attribute to the SQL query and create a custom data that holds its value.

Pick the retrieval method for the custom data according to your Kameleoon setup:

Kameleoon SDK method: for Feature Experimentation only.
Custom JavaScript code: for Web Experimentation, or for Web Experimentation and Feature Experimentation together.

Custom data retrieval method describes both methods.

Target your imported audiences in a Kameleoon experiment

This standard example shows a basic method of targeting your imported audiences in a Kameleoon experiment. Suppose your warehouse has a user table with id, place_of_birth, and subscription_plan columns.

Sample user table in a data warehouse with id, place_of_birth and subscription_plan columns. Several rows have LONDON as place_of_birth.

In this example, you want to target all users born in London. This audience requires a Data Ingestion Task, which you create in the Data Ingestion Tasks section of your warehouse’s source audience-targeting article. Name this Ingestion Task “The Londoners.” The SQL query for this task is: SELECT id FROM user WHERE place_of_birth="LONDON" To target the audiences that your Ingestion Tasks poll, complete the following setup.

Set up a Kameleoon custom data entry

Create custom data that holds the warehouse audiences each visitor belongs to.

In the left menu, click Settings > Custom data.
Click New custom data.
Provide a name for your custom data.
Select the project on which you configured the Data Ingestion Task.
Choose the retrieval method Kameleoon SDK method or Custom JavaScript code.
- See the following section dedicated to this parameter: Custom data retrieval method.
Choose List for the type and String for the format.
For the Scope, select Visit.
Click Next.

Options step of the custom data form, with the option to save values for the targeting condition turned on and an empty JavaScript table editor.

You can set the different values that will appear in the segment’s targeting condition you create. Select the checkbox Save the values for the targeting condition associated with the custom data point.

const sitecode= "YOUR_SITE_CODE"; //replace this value with your project's sitecode.
const xhr = new XMLHttpRequest();
 xhr.open('GET', `https://data.kameleoon.io/map/maps?siteCode=${sitecode}&keys=%5B%22warehouse%5Faudience%5Fconfig%22%5D`, false);
 xhr.send(null);
 if (xhr.status === 200) {
    const data = JSON.parse(xhr.responseText)
    if ("warehouse_audience_config" in data) {
       if ("audience_labels" in data["warehouse_audience_config"]) {
          return data["warehouse_audience_config"]["audience_labels"];
       }
    }
    return [];
 } else {
    console.error("Error calling for existing custom data values");
    return [];
 }

Click Create.

The custom data appears in the Custom data list, with its index in the Index column.

Custom data retrieval method

The custom data retrieval method specifies what code fills the custom data’s value and where this code runs. There are several retrieval possibilities according to your Kameleoon set up. If you are using Feature Experimentation only, you can select the Kameleoon SDK method. When you use this method, the acquisition code runs at the points where you call Kameleoon SDK methods. These methods fetch the warehouse audiences your visitor belongs to and store that information in the custom data. The precise code snippet depends on the SDK you are using. Here is an example written with Kameleoon’s JavaScript SDK:

import { KameleoonClient } from '@kameleoon/javascript-sdk';
 const client = new KameleoonClient({ siteCode: 'my_site_code' });
 async function init() {
 await client.initialize();
 // -- Get visitor code
 const visitorCode = client.getVisitorCode();
 // -- Replace with the visitor ID your organization uses in your warehouse
 const warehouseVisitorId = 'YOUR_WAREHOUSE_VISITOR_ID';
 // -- Index of your custom data
 const customDataIndex = 10;
 // -- Get visitor warehouse audience data using `warehouseKey`
 // and add it to storage
 const customData = await getVisitorWarehouseAudience({
 visitorCode: visitorCode,
 customDataIndex: customDataIndex,
 warehouseKey: warehouseVisitorId,
 });
 }
 init();

Replace YOUR_WAREHOUSE_VISITOR_ID so that the warehouseVisitorId variable contains the visitor ID that your organization uses for this visitor in their warehouse. The visitor ID depends on your organization’s visitor identification system (see Visitor identification). If your organization has no such identifier, you can use the Kameleoon Visitor Code, but you must also use that code in your warehouse. Replace the value of customDataIndex with your custom data’s index. You can find the index in the Index column of the custom data list:

Custom data list with the Index column highlighted. The Frequent buyer custom data has index 125.

If you are using Web Experimentation (or both Web Experimentation and Feature Experimentation), you can select Custom JavaScript code. In this case, the Kameleoon application file runs the code snippet. You can either add the following snippet to your project’s global custom script (click Admin > Projects, click Edit on the project’s row, then click the Scripts tab):

// Replace with the visitor ID your organization uses in your warehouse
const warehouseVisitorId = 'YOUR_WAREHOUSE_VISITOR_ID';
Kameleoon.API.Data.retrieveDataFromRemoteSource(warehouseVisitorId, function(data) {
     if("warehouseAudiences" in data){
         Kameleoon.API.Data.setCustomData("My Warehouse Audiences", Object.keys(data["warehouseAudiences"]));
     }
});

For this method, the snippet identifies the custom data by its name, not by its index. Alternatively, you can enter the snippet below in the code field that appears when you choose Custom JavaScript code as the retrieval method:

// Replace with the visitor ID your organization uses in your warehouse
const warehouseVisitorId = 'YOUR_WAREHOUSE_VISITOR_ID';
 if (typeof window.kameleoon_configured_warehouse_audiences === 'undefined') {
    window.kameleoon_configured_warehouse_audiences = null;
    Kameleoon.API.Data.retrieveDataFromRemoteSource(warehouseVisitorId, function(data) {
      if ("warehouseAudiences" in data) {
        window.kameleoon_configured_warehouse_audiences = Object.keys(data["warehouseAudiences"]);
      }
    });
 }
 if (window.kameleoon_configured_warehouse_audiences === null) {
    return null;
 }
 return {"value": window.kameleoon_configured_warehouse_audiences};

This one-time setup works for all of your Ingestion Tasks.

Create a segment for warehouse audiences

Create a segment that targets warehouse audiences through the custom data you set up. For example, if you have a second Ingestion Task that polls visitors born in March, and you call it “Born in March.” The custom data’s value for a visitor born in March and in London contains both audiences (“The Londoners,” “Born in March”). Thus, you can use this single custom data for all of your Kameleoon segments that target your warehouse audiences. You can then use this custom data in your Kameleoon campaigns (experiments, feature experiments, or personalizations) to target users based on their membership of a specific audience in your warehouse. To create such a segment, follow these steps:

Create a segment.
In your segment, use a custom data condition.
When you choose the is among the values operator, the list shows the audiences of the Data Ingestion Tasks you created, for example “The Londoners” and “Born in March.”

Targeting imported audiences by attributes

This section explains an alternative method for targeting audiences you’ve imported from your warehouse. This method is especially helpful if you want to run separate experiments that target different values of the same visitor attribute, such as many cities of origin. Creating one Ingestion Task for each place of birth works, but it becomes tedious when you want to target 50 different cities. Kameleoon lets you import attributes of the visitors in your warehouse audiences. To import them, add extra fields to the SQL query after the visitor ID field, like this: SELECT id, place_of_birth FROM user You can then create a custom data that holds the value of the attribute place_of_birth. For the JavaScript SDK, the code looks like this:

import { KameleoonClient } from '@kameleoon/javascript-sdk';
const client = new KameleoonClient({ siteCode: 'my_site_code' });
async function init() {
    await client.initialize();
    // -- Replace with the visitor ID your organization uses in your warehouse
    const warehouseVisitorId = 'YOUR_WAREHOUSE_VISITOR_ID';
    // -- Id of the ingestion task
    const taskId = "your_task_id";
    // -- Name of the attribute
    const attributeName = "place_of_birth";
    // -- Get remote data
    const jsonData = await getRemoteData(warehouseVisitorId);
    const data = JSON.parse(jsonData);
    if ("warehouseAudiences" in data){
        if (taskId in data["warehouseAudiences"]){
            const city = data["warehouseAudiences"][taskId][attributeName];
             // -- The index of the custom data you have created
             const customDataIndex = 10; // replace with your custom data index
             const customData = new CustomData(customDataIndex, city);
             // -- Add custom data
             client.addData(warehouseVisitorId, customData); 
         }
     }
}
init();

Alternatively, use the following snippet when you configure the custom data with the retrieval method Custom JavaScript code:

// Replace with the visitor ID your organization uses in your warehouse
const warehouseVisitorId = 'YOUR_WAREHOUSE_VISITOR_ID';
const taskId = "your_task_id";
const attributeName = "place_of_birth";
// Unique storage key for this custom data, built from the attribute name and the task ID
const storageKey = "kameleoon_warehouse_" + attributeName + "_" + taskId;

 if (typeof window[storageKey] === 'undefined') {
     window[storageKey] = null;
     Kameleoon.API.Data.retrieveDataFromRemoteSource(warehouseVisitorId, function(data) {
         if ("warehouseAudiences" in data) {
             if (taskId in data["warehouseAudiences"]){
                  const city = data["warehouseAudiences"][taskId][attributeName];
                  window[storageKey] = city;
             }
         }
     });
 }
 if (window[storageKey] === null) {
     return null;
 }
 return {"value": window[storageKey]};

You can then create a Kameleoon segment that targets the name of the city in the custom data value. If you want to target multiple cities in one segment, you can add several Or conditions to the same custom data when building the segment. The snippet stores its result in a window property named from attributeName and taskId. Keep this name unique for each custom data you create, because two custom data scripts that share a window property overwrite each other’s value. The taskId is the Ingestion Task ID: the unique number Kameleoon assigns to the task. The Data Ingestion Tasks list shows each task as its ID followed by its name, for example 543 Attributes. The ID is only the number (543), not the name. Set taskId to that number. You can add as many visitor attributes as you like in the SQL query and use these attributes in many ways with Kameleoon’s SDKs.

Data types of imported values

Kameleoon converts every imported value to text (string) on its side, whatever Type or Format you choose in the custom data form. The Type dropdown offers Single, List, and Count List. The Format dropdown offers Boolean, Number, and String. Kameleoon recommends String.

Use Boolean values from Databricks

To target a Boolean column from Databricks, convert its value to 1 or 0 in your custom code. The column reaches Kameleoon as text, for example {"is_premium": "true"}. Parse that text and store 1 or 0 as the custom data value. Segments then test that value against 1 or 0, not TRUE or FALSE.

Visitor identification

Modern apps and websites use many external tools and often many visitor identifiers. For this feature to work, the visitor identifier you use in your code to retrieve the JSON object must be the same identifier extracted from your warehouse. How you generate this visitor identifier is up to you. There are many possibilities. You can use identifiers that are only obtained after the user logs in to your solution, such as an email address. You can use anonymous identifiers if your business doesn’t require or support logging in. You can even use a mixture of both if you have a use case where you want to target users whether or not they’re logged in. You are in charge of your data warehouse and managing the table that Kameleoon queries from, so there are no limitations, except that the identifier must be available for tracking at some point. The Kameleoon Customer Success Team can advise you on choosing an identifier based on your specific setup, external tools, and business requirements.

Integrations

​Choose your targeting approach

​Target your imported audiences in a Kameleoon experiment

​Set up a Kameleoon custom data entry

​Custom data retrieval method

​Create a segment for warehouse audiences

​Targeting imported audiences by attributes

​Data types of imported values

​Use Boolean values from Databricks

​Visitor identification

Choose your targeting approach

Target your imported audiences in a Kameleoon experiment

Set up a Kameleoon custom data entry

Custom data retrieval method

Create a segment for warehouse audiences

Targeting imported audiences by attributes

Data types of imported values

Use Boolean values from Databricks

Visitor identification