Target your imported audiences

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

We currently support Data warehouse integration from the following providers:

• BigQuery
• Snowflake

Support for the following providers is coming soon:

• Redshift

• Microsoft Azure

For more information and if you want to be part of our early adopter program, please contact your Customer Success Manager.

Target your imported audiences in a Kameleoon experiment

This standard example shows the most straightforward way to target your imported audiences in a Kameleoon experiment. Let’s say you have a user table in your warehouse, a sample of which looks like this:

In this example we want to target all users born in London. This audience requires an Ingestion Task that can be configured as described above and that we’ll name “The Londonners“. The SQL query for this task will be:

SELECT id FROM user WHERE place_of_birth="LONDON"

To target the audience polled by this (and all other) Ingestion Task(s) you need to to go through the following one time setup. 

First set up a Kameleoon Custom Data entry:

1. On the left menu, go to Configure → Custom data.

2. Click on the New custom data button.

3. Provide a name for your custom data. Let’s say “My Warehouse Audiences”.
4. Select the right project (the one to which you configured the Data Ingestion Task for).
5. Choose the acquisition method Kameleoon SDK method or Custom JavaScript code.  Please see the following section dedicated to this parameter here.
6. Choose List for the type and String for the format. 
7. For the Scope, select Visit.
8. Click Next.

9. You can set the different values that will appear in the targeting condition of the segment you will create. Click on the option Save the values for the targeting condition associated with the custom data point.

const sitecode= "YOUR_SITE_CODE"; //replace this value by your project 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 [];
 }

10. Click Create.

Custom data acquisition

The custom data acquisition method specifies what piece of code actually fills the value of the custom data and where this piece of code is executed. There are several acquisition possibilities according to your current Kameleoon set up.

If you are using Feature Experimentation only, you can select Kameleoon SDK method. This means that the acquisition code will run where you have implemented Kameleon SDK methods to fetch the warehouse audiences that your visitor belongs to and store them in the Custom Data. The precise code snippet depends on the SDK you are using. Here is an example written with our JavaScript SDK:

import { KameleoonClient, KameleoonUtils } from '@kameleoon/javascript-sdk';
 const client = new KameleoonClient('my_site_code');
 async function init() {
 await client.initialize();
 // -- Get visitor code
 const visitorCode = KameleoonUtils.getVisitorCode('www.example.com');
 // -- Get the warehouse visitor id
 warehouseVisitorId = anyClient.getThisVisitorId();
 // -- Index of your custom data
 const customDataIndex = 10;
 // -- Get visitor warehouse audience data using warehouseKey
 // and add it to storage
 const customData: CustomData = await getVisitorWarehouseAudience({
 visitorCode: 'my_visitor',
 customDataIndex: customDataIndex,
 warehouseKey: warehouseVisitorId,
 });
 }
 init();

Note that the warehouseVisitorId variable needs to be filled with the visitor id that your company uses for this visitor in their warehouse. This line of code depends entirely on your company’s visitor identification system. If you don’t have one you can use the Kameleoon Visitor Code, but for this to work you also need to be using the Kameleoon Visitor Code in your warehouse. For more information on visitor identification, please see the “Visitor Identification” section further down on this page.

Replace the value of customDataIndex with the index of your custom data that you can find in the dashboard:

If you are using Web Experimentation (or both  Web Experimentation and Feature Experimentation), you can select Custom JavaScript code. In this case the code snippet will be run by the kameleoon.js file. You can either add the following snippet to your project global script (in Admin > Configure > then edit the appropriate project):

const warehouseVisitorId = anyClient.getThisVisitorId();
Kameleoon.API.Data.retrieveDataFromRemoteSource(warehouseVisitorId, function(data) {
     if("warehouseAudiences" in data){
         Kameleoon.API.Data.setCustomData("My Warehouse Audiences", Object.keys(data["warehouseAudiences"]));
 }

In this case we need to use the name of your Custom Data (“My Warehouse Audiences”) and not the index as in the previous SDK example.

Or you can enter the snippet below directly when configuring the custom data in the appropriate field: 

const warehouseVisitorId = anyClient.getThisVisitorId();
 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};

Note that this is a one time setup that will work for all your Ingestion Tasks.

For example if you had a second ingestion task that polled visitors born in March and you call it “Born in March”. The value of the custom data for a visitor born in March in London will contain both audiences [“The Londonners”, “Born in March”].

Thus you can use this single custom data for all your Kameleoon Segments that target your warehouse audiences. You will then be able to use this custom data in your Kameleoon campaigns (experiments, feature experiments or personalizations) to target users based on their belonging to a specific audience in your warehouse. 

To create such a segment, go through the following steps.

First, start by creating a segment as explained in the dedicated documentation. 

Then, inside your segment, use a custom data condition.

When choosing the is among the values operator, you should see the list of Audiences associated with the Data Ingestion Tasks you created : The Londonners, Born in March, etc.

Targeting imported audiences by attributes

This section describes an alternate way of targeting your imported warehouse audiences that may be useful when you need to target many values of a visitor attribute in separate Experiments. We’ll keep the same data and use case as in the previous example, only this time we want to target many different cities of origin and not just visitors born in London. This would be possible with the setup previously described : you would create an Ingestion Task for each place of birth you wish to target. However this could be a bit tedious if you want to target 50 different cities.
Luckily Kameleoon allows you to also import attributes of the visitors in your warehouse audiences. This is achieved by adding extra fields to the SQL query after the visitor id field like so:

SELECT id, place_of_birth FROM user

You can then create a Custom Data that will this time contain the value of the attribute place_of_birth. For JavaScript SDK implementation the code looks like this:

import { KameleoonClient } from '@kameleoon/javascript-sdk';
const client = new KameleoonClient('my_site_code');
async function init() {
    await client.initialize();
    // -- Get the warehouse visitor id
    warehouseVisitorId = anyClient.getThisVisitorId();
    // -- 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 = your_index;
             const customData = new CustomData(customDataIndex, city);
             // -- Add custom data
             client.addData(warehouseVisitorId, customData); 
         }
     }
}
init();

Alternatively, the equivalent piece of code you can use when configuring the custom data with the acquisition method “Custom JavaScript code”: 

const warehouseVisitorId = anyClient.getThisVisitorId();
const taskId = "your_task_id";
const attributeName = "place_of_birth";

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

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 on the same custom data when building the segment.

Note that here the taskId is the unique number identifier of the Ingestion Task that can be found on the user interface where the task was defined.

This is just one example of what can be done with visitor attributes. You can add as many visitor attributes as you like in the SQL request and use these attributes in many ways with our SDKs.

Visitor identification

Modern apps and websites use many external tools and often many visitor identifiers. This may be the case for your business. For this feature to work, the visitor identifier you use in the above code examples to retrieve the JSON object must be the same identifier extracted from your warehouse.

How this visitor identifier is generated is up to you. There are many possibilities. You can use identifiers that are obtained only after the user logs into your solution, such as an email address. You can use more 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 they are logged in or not.

You are in charge of your data warehouse and managing the table that Kameleoon queries from so there are no limitations other than the fact that the identifier must also be available at some point on the tracking end.

The Kameleoon Customer Success Team can advise you on how to choose an identifier based on your specific setup, external tools, and business requirements.