Audience targeting

Import audiences from your data warehouse into Kameleoon and target them with Kameleoon web and feature experiments.

Note: To use this feature, you must be a member of Kameleoon’s Early Adopter Program. If you are not yet a member, please contact your customer success manager.

To activate this feature, complete the instructions below and provide your customer success manager with the following information:

• Access credentials to your warehouse
• SQL queries that fetch the audiences you want to target in experiments
• The frequency you want Kameleoon to poll each audience from your warehouse

Kameleoon will provide you with a unique ID for this warehouse audience which you will use when configuring a Kameleoon custom data that will be populated at the beginning of each new visit with the targeting status or attributes of your warehouse audience. You can then create Kameleoon experiments that target visitors according to the value contained in this custom data.

Create access credentials

To create access credentials for your warehouse, implement the Set up Kameleoon read authorization and Set up Kameleoon write database sections of our documentation for your specific warehouse provider.

Currently Kameleoon supports the following provider:

• BigQuery

Support for the following providers is coming soon:

• Snowflake
• Redshift
• Microsoft Azure

BigQuery

Create the SQL query that fetches the user IDs to target in your experiment

The SQL query must have the following format:

SELECT {visitor_id_field}, {attribute_1}, {attribute_2}, ..., {final_attribute} FROM table_containing_audience WHERE {condition_1} AND … AND {final_condition}

The field containing the visitor identifier you wish to use must be placed directly after the SELECT keyword. After that, you can add as many extra attributes as you wish to extract from your table. Your SQL query can end with as many conditions as you need.

Polling interval

The polling interval is the time between each consecutive poll. This interval should reflect the frequency with which your visitors return to your app. The idea is that if a visitor becomes part of your target audience, Kameleoon polls this information before that visitor’s next session. Do not set the polling interval lower than necessary as this can induce unnecessary warehouse compute costs for your company. Kameleoon allows polling intervals as low as once per hour.

Configuring and populating a custom data

Once the Kameleoon platform has started polling your warehouse, the data will be available right away for targeting your users in Kameleoon campaigns. You can use the polled data using our Activation API for web experiments, and using our SDKs for feature experimentation.

To target a visitor according to this data in your experiments, first set up a Kameleoon Custom Data entry:

• Provide a name for your custom data.
• Choose the acquisition method Kameleoon SDK method or Custom code (we will give details on both methods further down)
• Choose a String Type and validate to create the custom data.

Once you have created the custom data, this integration requires some additional custom code alongside your usual experiment configuration. This custom code will be run for every new visitor session to retrieve any data that may have been polled from your warehouse for the current visitor identifier. The code then populates your newly created custom data with this data.

We start by describing the format with which Kameleoon stores your polled data. Let’s say you have set up the following simple polling query from your warehouse and Kameleoon has attached it to the unique identifier 1234 :

SELECT user_id FROM users WHERE condition1 AND condition2;

If your current visitor has been polled, here is the JSON format returned by our Activation API or SDKs if the requested visitor identifier was retrieved when polling your warehouse.

{
     "warehouseAudiences":
         {
             "1234": {}
         }
 }

Having entry “1234” means that the visitor is in the audience. Kameleoon returns an empty map for this entry because no extra field is being retrieved with the SQL query.

Let’s now consider a more complex example using the following SQL query to poll your warehouse:

SELECT user_id, place_of_birth, subscription_plan FROM users WHERE condition1 AND condition2;

The response JSON will look like this, for a polled visitor born in London with a FREEMIUM subscription plan:

{
     "warehouseAudiences":
         {
             "1234": 
               {
                   "place_of_birth": "London",
                   "subscription_plan": "FREEMIUM"
               }
         }
 }

The custom code you need to integrate with your Kameleoon tracking retrieves the above JSON, parses it, and puts the value into the custom data you created. Here are two examples:

• Web experiment via Activation API

If you chose the acquisition method Kameleoon SDK method when creating your custom data, add the following code snippet to the Global custom script section of your Kameleoon project as explained here. 

// -- Get the visitor identifier used in you warehouse, for example a log in identifier like an email, or an auto-generated anonymous visitor identifier
const visitorId = your_company_client.getCurrentVisitorIdentifier();
// Unique query identifier that you can find on your Kameleoon platform. Use string type.
const queryIdentifier = "1234";
// Name you chose for the custom data
const customDataName = "name_of_custom_data";
Kameleoon.API.Data.retrieveDataFromRemoteSource(visitorId, function (data) {
         if (queryIdentifier in data.warehouseAudiences)
           Kameleoon.API.Data.setCustomData(customDataName, "true");
         });

Alternatively, if you selected Custom code as the acquisition method when creating your custom data and add the following code snippet (Custom JavaScript code acquisition method example):

// -- Get the visitor identifier used in you warehouse, for example a log in identifier like an email, or an auto-generated anonymous visitor identifier
const visitorId = your_company_client.getCurrentVisitorIdentifier(); // Do not use an asynchronous method here
const queryId = "1234";
if (typeof window.kameleoon_query_1234_value === 'undefined') {
   window.kameleoon_query_1234_value = null;
   Kameleoon.API.Data.retrieveDataFromRemoteSource(visitorId, function(data) {
     if (queryId in data.warehouseAudiences) {
       window.kameleoon_query_1234_value = "true";
     }
   });
}
if (window.kameleoon_query_1234_value === null) {
   return null;
}
return {"value": window.kameleoon_query_1234_value};

Make sure to use a unique variable name for the dedicated window object attribute for each custom data (here you can see we used “kameleoon_query_1234_value”).

• Feature Experiment via SDK (JavaScript SDK example)

import { KameleoonClient } from '@kameleoon/javascript-sdk';
// Initializing any instances of SDK or code specific to your company, that will retrieve the visitor id
const your_company_client = new YourCompanyClient();
await your_company_client.initialize();
const client = new KameleoonClient('my_kameleoon_site_code');
await client.initialize();
async function checkWarehouseAudience(custom_data_id) {
    // -- Get the visitor identifier used in you warehouse, for example a log in identifier like an email, or an auto-generated anonymous visitor identifier
   const company_visitor_id = your_company_client.getCurrentVisitorIdentifier();
    // -- Get Kameleoon visitor code
    const kam_visitor_code = KameleoonUtils.getVisitorCode("www.mycompany.com"
    // -- Get remote data
    const jsonData = await getRemoteData(company_visitor_id);
    const data = JSON.parse(jsonData);
    const query_id = "1234";
    const custom_data_id = 37 // Id of the custom data you created
    if (query_id in data.warehouseAudiences)
    {
        // -- Add custom data
        client.addData(kam_visitor_code, new CustomData(custom_data_id, "true"));
    }
 }
 checkWarehouseAudience(11);

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. Kameleoon also has solutions such as Cross Device History reconciliation that may be helpful here as well. Contact the Customer Success Team for more information.

Full example

This following example demonstrates audience polling. Let’s say you have a user table in your warehouse and a sample that looks like this:

Each row of this sample data represents a user with a unique ID field, and two other fields containing the place of birth and the type of subscription plan for the user. Let’s say you want to design a Kameleoon experiment that targets your “freemium” users and tries to upsell their plan to “enterprise”. Let’s also assume you want to implement two separate experiments; one specifically for users born in London, and the other for the rest of the world.

You need to compose an SQL query that extracts the user IDs and the place of birth for the target audience from this warehouse table. In this example, your query would be:

SELECT user_id,place_of_birth FROM users WHERE subscription_plan="FREEMIUM"

You create a new custom data entry called “warehouse_freemium_users” for this use case and Kameleoon assigns this custom data to the ID value 11.

You also create two Kameleoon segments:

• The londonners that targets visitors with a custom data entry 11, set to value “LONDON”
• The rest of the world that targets visitors with a custom data entry 11 set to any other value.

Finally, you create two experiments, each targeting one of the two above segments.

The custom tracking code examples for this use case are slightly different from the examples above. This time we are no longer setting “true” as the value of the custom data, but the content of the JSON at the key “place_of_birth”. 

• Web experiment via Activation API

// -- Custom data name that you can find on your Kameleoon platform
const customDataName = "name_of_custom_data";
// -- Identifier of your warehouse audience query that you can find on your Kameleoon platform
const queryId = "1234";
Kameleoon.API.Data.retrieveDataFromRemoteSource(visitorId, function (data) {
         if (queryId in data.warehouseAudiences)
           Kameleoon.API.Data.setCustomData(customDataName, data.warehouseAudiences[queryId]["place_of_birth"]);
         });

• Feature Experiment via SDK (JavaScript SDK example)

import { KameleoonClient } from '@kameleoon/javascript-sdk';
// Initializing any instances of SDK or code specific to your company, that will retrieve the visitor id
const your_company_client = new YourCompanyClient();
await your_company_client.initialize();
const client = new KameleoonClient('my_kameleoon_site_code');
await client.initialize();
async function checkWarehouseAudience(custom_data_id) {
    // -- Get the visitor identifier used in you warehouse, for example a log in identifier like an email, or an auto-generated anonymous visitor identifier
    const company_visitor_id = your_company_client.getCurrentVisitorIdentifier();
    // -- Get Kameleoon visitor code
    const kam_visitor_code = KameleoonUtils.getVisitorCode("www.mycompany.com"
    // -- Get remote data
    const jsonData = await getRemoteData(company_visitor_id);
    const data = JSON.parse(jsonData);
    // -- Identifier of your warehouse audience query that you can find on your Kameleoon platform
    const query_id = "1234";
    // -- Id of the custom data you created that you can find on your Kameleoon platform
    const custom_data_id = 37;
    if (query_id in data.warehouseAudiences)
    {
        // -- Add custom data
        client.addData(kam_visitor_code, new CustomData(custom_data_id, data.warehouseAudiences[query_id]["place_of_birth"]));
    }
}
checkWarehouseAudience(11);

Don’t forget to send your customer success manager the warehouse credentials you have set up for Kameleoon along with your SQL query and polling interval.