Visit our new documentation site! This documentation page is no longer updated.

Personalization API

Personalization API enables you to dynamically change your content based on detailed customer information. This REST API returns customer data in real-time, updating the segment information that you create in the Segment Builder.

The Audience must be already built by Audience Builder. The audience is the basis for all data accessed by Personalization Tokens.

You can use Personalization API to personalize your customers experience on your website. You can combine Treasure Data’s personalization feature with A/B Testing tools such as Adobe Target, Optimizely, Google Optimize, to determine the version of your website that yields results.

Table of Contents


Step 1: Create Personalization API Token

First, click Generate New Token located under the Personalization Tokens menu.

Step 2: Configure the Personalization API Token

Complete the fields to configure the API token, including specifying a key column and the segments of customers to which you want to apply personalization.

When you click Save, the token is created.

You have the option of using a new version (V2) of the Personalization API token. You must complete migration steps to apply the V2 token to segments at are specified in existing personalization token configurations.

More about Personalization API Token V2

Click Use Personalization Token V2 to specify use of the token. The next time that the Personalization runs and the personalization data set is refreshed, the V2 token is applied.

Use of the V2 token improves processing when you have a large number of segments, and increases the number of customers attributes that you can view. There is no impact if you choose to continue using the original version (V1) of API token. If you have existing segments, you must complete migration steps in order to use API token V2 successfully with all your segments.

More about specifying a Key column to look up the customer

The internal key-value store is updated with the mapping from the key-column to the segment IDs that customers belongs to.

When you click Save, the lookup process begins. When the underlying personalization workflow completes, the personalization data set is refreshed. You can see a current list of the segments to which a specific customer belongs. And, with API token V2, you can also see a list of attributes associated with the specific customer.

Step 3: Use JavaScript SDK to fetch Segment IDs

Finally, you can use our JavaScript SDK to fetch customer segment IDs.

<!-- Treasure Data -->
<script type="text/javascript">
 !function(t,e){if(void 0===e[t]){e[t]=function(){e[t].clients.push(this),this._init=[]},e[t].clients=[];for(var r=function(t){return function(){return this["_"+t]=this["_"+t]||[],this["_"+t].push(,this}},s=["addRecord","set","trackEvent","trackPageview","trackClicks","ready","fetchGlobalID","fetchUserSegments"],a=0;a<s.length;a++){var c=s[a];e[t].prototype[c]=r(c)}var n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src=("https:"===document.location.protocol?"https:":"http:")+"//";var i=document.getElementsByTagName("script")[0];i.parentNode.insertBefore(n,i)}}("Treasure",this);
<script type="text/javascript">
var td = new Treasure({...})

var successCallback = function (key, segments) {
  // key => key column value
  // segments => array of segment IDs
var errorCallback = function (error) {};

  keys: {
    key_column_1: 'someValue',
    key_column_2: 'someOtherValue',
}, successCallback, errorCallback)
  • API Request
    • audienceToken: List of Personalization API Tokens
    • keys: List of key columns
  • API Response
    • segments: List of segment IDs
Personalization API is supported JavaScript SDK v1.9.1 or later. If you're using the old version, you must upgrade.

Here’s the example output with Google Chrome Developer Tools.

Step 4: Integrate with other Tools

To control the content that shows for specific customer segments, you can integrate Personalization API with other tools such as:

Last modified: May 07 2018 17:06:53 UTC

If this article is incorrect or outdated, or omits critical information, let us know. For all other issues, access our support channels.