Storing and retrieving external data to target users

The Kameleoon Web and Feature Experimentation solutions allow you to target users based on external data stored on other systems (such as CRMs and CDPs ), using the Data API’s Map endpoint and custom data.

This tutorial will discuss:

• How to store external user data using the POST Map endpoint,
• How to read that user data using our GET Map endpoint. (Note that in Step 2, this tutorial will use an activation API method designed for web experimentation, which wraps the Data API. For Feature experimentation, there is a similar method available across all our SDKs. This design simplifies the process, helping customers avoid the need to write code for API calls and the associated logic.)
• How to leverage the stored data in a targeting segment by utilizing custom data feature with your experiments.

Post data to Kameleoon using the DATA API’s MAP endpoint

Since the Data API is a REST API, you will send a POST request to the MAP endpoint to store additional information linked to a specific key – which usually represents a visitor code or an internal User ID you must provide when a user visits the website.

note

You may obtain an authentication token to access the MAP endpoint, following the same flow as the Automation API with JSON web tokens. This is optional. To learn more about authentication and rate limiting, you may refer to this article.

To send the cURL request, you will need the following:

• siteCode: This is a string of letters and numbers related to the project for your experiment. Visit this link to learn how to retrieve it.
• JSON object: The request body will contain an object consisting of a list of keys and their relevant user data.
• User-agent: Requests from sources identified as bots or spiders will be rejected according to IAB/ABC user-agent filtering rules. Kameleoon uses a single-pass method, which means no action is required for requests from standard web browser libraries (like XHR). However, users should set a custom User-Agent value to override the library’s default in other cases.

curl -X POST -L 'https://data.kameleoon.io/map/maps?siteCode=f17c21u1ag' \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyCustomUserAgent/1.0' \
-d '{
	"myUserID1": {
        "audiencesNames": {
            "premium": true
        }
    },
    "myUserID2": {
        "audiencesNames": {
            "premium": false
        }
    },
    ...
}'

note

Note: Once the request is accepted and processed successfully, no content will be returned. To verify that the request has been successful, you may use this endpoint with the following URL: https://data.kameleoon.io/map/map?siteCode=f17c21u1ag&key=myUserID1

Fetch data using retrieveDataFromRemoteSource (Activation API)

Now that the data has been stored on our servers, Kameleoon offers a Custom Data feature that enables you to retrieve data for each user visiting your website. This custom data can be used as a targeting condition in the segments of your experiments.

To do that, you must first create and configure your custom data on the Kameleoon app.

From the left-hand menu of the Kameleoon dashboard click on Custom data under Configure:

You will be redirected to the Custom data dashboard, and from the top right corner of the screen click on New custom data:

You will be taken to Edit the custom data window:

For instance, you want to create a custom data called “Premium users” which targets users whose "premium" status is set to true. This data was stored on Kameleoon servers for each user in earlier, in Step 1:

"audiencesNames": {
  "premium": true
}

To fetch users whose premium status is set to true, you need to configure the retrieval method to Custom JavaScript method and paste the following code for the retrieveDataFromRemoteSource method under Paste a sample code:

Kameleoon.API.Data.retrieveDataFromRemoteSource(user_id, function (data) {
if (data && data.audiencesNames && data.audiencesNames.premium !== undefined) {
Kameleoon.API.Data.setCustomData("Premium users", data.audiencesNames.premium);
}});

This method enables you to retrieve the value stored for a specific user. In the sample code provided, it is assumed that the variable “user_id” contains the ID that identifies the user on your website.

note

If you are using Kameleoon Feature Experimentation, you can use the SDK method getRemoteData within your feature flag's code to retrieve the data of your choice.

Once you have populated all the information on the custom data creation window, click on Next:

The next window will present you with additional configuration options that you may skip. Click on Create:

You will be redirected to your custom data dashboard where you will find the Premium users custom data:

Utilize the Kameleoon editor to associate custom data with the segment of an experiment

Once you have established the custom data Premium users, you will use it for targeting purposes in an experiment.

To do so, click on Segments under Configure from the left side of the dashboard:

For instance, if you want to work with a New segment, click on Edit:

Then, on the left side of the Segment configuration window, under Conditions, select the Premium users custom data you created previously:

Then, under Definitions, configure the custom data to include visits with the Premium users custom data set to true:

Then Save.

You have now successfully configured the segment to include visits with the custom data Premium users.

To use the New segment above in an experiment, go back to your experiments dashboard.

Click on Edit on the experiment you wish to associate New segment to:

Once you are redirected to the window below, select Targeting from the top left of the screen:

Under Targeting, choose Target a segment, then, select the New segment created earlier.

You will see the following on your screen:

Then, from the top-right corner of the page, click on Launch:

A summary of the experiment draft will be displayed:

If you are satisfied with the existing configuration, click on Launch.

You will see the above message. Return to your dashboard and click on the experiment you associated the segment with. You will see that the New segment has been successfully added to the experiment: