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 the GET Map endpoint. (Note that this step, uses an activation API method designed for Web experimentation, which wraps the Data API. For Feature experimentation, there is a similar method available across all of Kameleoon's SDKs, which simplifies the process, helping customers avoid writing 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 must 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 (optional). To learn more about authentication and rate limiting, see this article.

The cURL request must include the following parameters:

• siteCode: This is a string of letters and numbers related to the project for your experiment. See this article 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://eu-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

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

Fetch data using retrieveDataFromRemoteSource (Activation API)

With the data now stored on Kameleoon's servers, use custom data to access information for each individual visiting your site. Custom data can serve as a targeting condition within the segments for your experiments.

You must first create and configure your custom data in Kameleoon.

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

You will be redirected to the custom data dashboard. Click New custom data in the top-right corner.

You will be taken to the Edit the custom data window.

You may wish to establish a custom data called “Premium users,” aimed at users who have their "premium" status marked as true. This information was previously saved on Kameleoon's servers for each user in the earlier step.

"audiencesNames": {
  "premium": true
}

To get users with a premium status of true, adjust the retrieval method to Custom JavaScript and insert 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);
}});
return {"value": null};

This method lets you 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 in the custom data creation window, click Next.

The next window will present you with additional configuration options that are optional. Click 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 an experiment's segment

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

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

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

Then, on the left side of the Segment configuration window, under Conditions > Technical, 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 click Next > Edit segment.

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

To use New segment in an experiment, return to your experiments dashboard.

Click Edit next to the experiment you wish to associate New segment with.

Once you are redirected to the window below, select Targeting in the upper-left corner.

Under Targeting, choose Target a segment, then select New segment.

You will see the following on your screen:

Then, in the top-right corner, click Launch.

A summary of the experiment draft will be displayed.

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

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