Integrate Kameleoon with Segment

With this integration you can seamlessly connect Kameleoon with Segment to:

1. Use Kameleoon as a Source to push campaign exposure event data (campain name and variation name) to Segment, which can then be used by other platforms available in Segment marketplace;
2. Use Kameleoon as a Destination to:
   • import Segment events, which you can use in Kameleoon experiments and web personalizations;
   • import Segment personas, traits and groups and use them in our Segment Builder throughout custom data.

Push Kameleoon exposure events into Segment

Enable Segment integration on Kameleoon

Log in to your Kameleoon App, click on Administrate and then Integrations in the sidebar.

For more information on this page, see our dedicated article.

By default, the tool is not installed. This is signaled by this icon:

With a click on Install the tool, you will be able to select the projects on which you want to activate it.

Once you have configured the tool, click on Validate in the bottom-right corner: the configuration panel closes. You will then see a ON toggle on the right of the tool’s line, as well as the number of projects the tool is configured on.

Note: make sure the Segment script (analytics.js) is installed on your pages as Kameleoon will use Segment API methods to send campaign exposure events to Segment by using the Segment JavaScript API.

Associate Segment as reporting tool in a Kameleoon experiment or personalization

Once the integration is activated on the Integrations page, you can select it as a reporting tool at the Integrations step of the finalization panel of the Graphic/Code editor).

As soon as Segment has been activated and defined as a reporting tool in a campaign, an event called “Experiment viewed” will be sent automatically every time a visitor sees a variation of an active Kameleoon A/B experiment.

Note: if you need to send exposure events for feature flags, you need to enable Hybrid capabilities.

Import Segment events, traits, groups and personas into Kameleoon

Note: This section is about the non-Actions Kameleoon destination, which will soon be deprecated. We recommend the use of the Actions-framework Kameleoon Segment destination, which is documented here.

With this Segment x Kameleoon integration:

• Every event that is triggered by Segment will be automatically sent to Kameleoon, saving developers from having to re-implement an existing Segment Tracking plan in Kameleoon. Page, Screen and Track events will be automatically collected as a Kameleoon custom goal and you will be able to use any of them in your campaigns or to target users doing a specific action on your website or mobile app.
• Track events of type Audience Entered or Audience exited will be collected as a Kameleoon custom data to be used in our Segment builder to target personas of users.
• Track events of type identify with traits will be collected as Kameleoon custom datas to to be used in our Segment builder to target users having specific traits.
• Track events of type group will be collected as Kameleoon custom data to to be used in our Segment builder to target a group ID.

Step 1: Generate API Credentials

First, you will have to enable API Credentials in order to use this integration. To generate your API Key:

1. Get your client ID and client secret. You can find them in your profile page.
2. Use your client ID and client secret with the following URL to generate your API Key:

https://customers.kameleoon.com/kameleoon/segmentio/getapikey?id=[CLIENT_ID]&secret=[CLIENT_SECRET]

Step 2: Get your project sitecode

You will also need to get your sitecode in your Kameleoon account.

To learn how to find your sitecode, please read this documentation.

Step 3: Enter this information when setting up the Kameleoon as a destination in your Segment app

• From the Destinations catalog page in the Segment app, click Add Destination.
• Search for Kameleoon in the Destinations Catalog, and select the Kameleoon destination.

• Click on Configure Kameleoon.
• Choose which Source (app, website, etc.) should send data to the Kameleoon destination.
• Enter the APIKey and the sitecode in the Kameleoon destination settings in Segment.

Step 4: Matching Users between Kameleoon and Segment

The integration requires that you use the same system of identifiers for both tools, meaning the userId value you pass to Segment should be the same value as Kameleoon uses to identify a “visitor”.

If you use Kameleoon Web Experiment, Kameleoon places a cookie that contains an anonymous unique identifier, called the Kameleoon visitorcode, randomly assigned to a visitor. This ID is used to uniquely identify a user in a browser. You have several options available:

• You can pass our visitorcode in the userId property of the Segment identify call to ensure Kameleoon can attribute all events data received from Segment to the right visitor.

• You can pass our visitor code in an additional Segment call as follow: analytics.track('Kameleoon identifier', {'k_visitorCode': Kameleoon.API.Visitor.code}). Kameleoon will automatically link the Segment user ID or anonymous ID to our own visitorCode. Make sure to call it only once per session. For instance, if you use Kameleoon Web Experimentation or have implemented our Kameleoon application file (kameleoon.js) to benefit from hybrid experimentation capabilities, you can use the code example below in the Global custom script section of the Kameleoon Project property.

Kameleoon.API.Core.runWhenConditionTrue(
     () => window.analytics && window.analytics.track && window.analytics.user,
     () => {
         const kSegmentioIdentifier = window.localStorage.getItem('k_segmentio_identifier');
         if(kSegmentioIdentifier && kSegmentioIdentifier === window.analytics.user().anonymousId()) return;
         window.localStorage.setItem('k_segmentio_identifier', window.analytics.user().anonymousId());
         window.analytics.track('Kameleoon identifier', {'k_visitorCode': Kameleoon.API.Visitor.code})
     }
 );

If you use Kameleoon Feature Experimentation, please refer to the Kameleoon SDK documentation as you would be able to set your own ID instead of using a generated Kameleoon Visitor Code and so have the exact same one between Segment and Kameleoon. For instance, if you’re using the GO SDK, you can refer to its documentation for detailed instructions.

Step 5: Supported Segment events and Personas

Kameleoon supports the following methods (Track, Identify, Page, Screen, Group), as specified in the Segment Spec.

Behind the scenes, if the Segment event name matches exactly the name of an existing goal in your Kameleoon account, a conversion for this goal will be associated to the visitor. If the goal does not exist, Kameleoon will create a custom goal by using the Segment event name and associate the conversion to the visitor. The goal will appear in the Kameleoon goals page with the name convention ‘SegmentIO [eventType] – [eventName]’. Once the goal has been created, you can use them in any of your campaign.

Segment track calls of type Audience Entered, Audience Exited, Identify and Group“will be collected as a Kameleoon custom data.

Underneath, Segment uses our Data API map endpoint to send the data to Kameleoon.

Personas, traits and group

Kameleoon allows you to target users based on their belonging to a Segment persona, a group or who have specific traits of properties.

In order to be able to use personas, traits and group IDs in our Segment builder, you will need to set up a custom data in your Kameleoon account for the project of your choice.

Personas

You can choose the name of your choice (eg. SegmentIO personas) and the custom data must be of type List of string.

Please follow the guidelines below for Web Experimentation only

You can use the code below in the custom data acquisition method:

window.k_segmentIO = window.k_segmentIO || {};
 if(!window.k_segmentIO.runtime)
 {
     window.k_segmentIO.runtime = true;
 
// Depending on your setup, you'll need to determine the appropriate logic for obtaining the user ID.   

// If you've been using a track event call to send our visitor code, use the following line:  
const user_id = Kameleoon.API.Visitor.code;  

// Alternatively, if you use our Visitor Code as the Segment user ID or need to retrieve the user ID from Segment's analytics object, use the following line:  
const user_id = window.analytics.user().id() || window.analytics.user().anonymousId(); 


Kameleoon.API.Data.retrieveDataFromRemoteSource(`COHORTS_${user_id}`, cohorts => {     window.k_segmentIO.cohorts = cohorts && cohorts !== '{}' ? Object.keys(cohorts).filter(key => cohorts[key]) : []; });
 }
 if(!window.k_segmentIO.cohorts || !window.k_segmentIO.cohorts.length) return;
 return {"value": window.k_segmentIO.cohorts, "overwrite": true};

To use Segment personas in server-side experiments or feature flags, you can consult the guidelines outlined in the documentation for each respective SDK. For instance, if you’re using the GO SDK, you can refer to its documentation for detailed instructions.

The GO SDK, like our other SDKs, employs the GetRemoteData method, which is accessible across all our SDKs. This method enables you to fetch data stored by Segment on our servers and make it accessible within your backend code.

The “key” value to use as the first parameter should follow this format: “COHORTS_{user_id}”.

Fetch Segment Persona names in Kameleoon

Click on Next and activate the Save the values for the targeting condition associated with the custom data point option. Add the JS code below and replace XXXXXXXXX by the Kameleoon Sitecode. To find it, please follow this documentation.

var xhr = new XMLHttpRequest();
xhr.open("GET", 'https://api-data.kameleoon.com/data?key=common&siteCode=XXXXXXXXX', false);
var SegmentIOPersonas = [];
xhr.onreadystatechange = function() { 
   if(this.readyState === 4) {
     var segmentIOcohorts = JSON.parse(xhr.response);
	  if (segmentIOcohorts && segmentIOcohorts.cohorts) {
		  segmentIOcohorts.cohorts.forEach(persona => SegmentIOPersonas.push({value: persona, label: persona}) );

	   }
   }
}
xhr.send();
return SegmentIOPersonas;

Click on Validate to create the Custom Data.

That’s it! You will now be able to use Segment Personas in our Segment Builder. The list of available personas will be available when you choose the operator is among the values.

Traits

To use traits properties in our segment builder to target your campaigns, you will need to create one custom data per trait type. Let’s say for instance that you want to target users based on the plan they have subscribed on your website and that you have 3 different plans : freemium, scale and enterprise. You will need to set up a custom data “Subscribed Plan” and the custom data must be of type “string”.

Please follow the guidelines below for Web Experimentation only

You can use the code below in the custom data acquisition method:

window.k_segmentIO = window.k_segmentIO || {};
 if(!window.k_segmentIO.runtime)
 {
     window.k_segmentIO.runtime = true;
     
// Depending on your setup, you'll need to determine the appropriate logic for obtaining the user ID.   

// If you've been using a track event call to send our visitor code, use the following line:  
const user_id = Kameleoon.API.Visitor.code;  

// Alternatively, if you use our Visitor Code as the Segment user ID or need to retrieve the user ID from Segment's analytics object, use the following line:  
const user_id = window.analytics.user().id() || window.analytics.user().anonymousId(); 
   
  Kameleoon.API.Data.retrieveDataFromRemoteSource(`IDENTIFY_${user_id}`, segment_identify_properties => {
         if(segment_identify_properties && segment_identify_properties.traits && segment_identify_properties.traits.plan){
             window.k_segmentIO.plan = segment_identify_properties.traits.plan;
         }
     });
 }
 if(!window.k_segmentIO.plan) return;
 return {"value": window.k_segmentIO.plan, "overwrite": true};

To use traits in server-side experiments or feature flags, you can consult the guidelines outlined in the documentation for each respective SDK. For instance, if you’re using the GO SDK, you can refer to its documentation for detailed instructions.

The GO SDK, like our other SDKs, employs the GetRemoteData method, which is accessible across all our SDKs. This method enables you to fetch data stored by Segment on our servers and make it accessible within your backend code.

The “key” value to use as the first parameter should follow this format: “IDENTIFY_{user_id}”.

You can follow the same guidelines for every trait property you would like to use in the segment builder of Kameleoon.

Group IDs

To use group IDs in our segment builder to target your campaigns, you will need to need to set up a custom data “Group ID” and the custom data must be of type string.

Please follow the guidelines below for Web Experimentation only

You can use the code below in the custom data acquisition method:

window.k_segmentIO = window.k_segmentIO || {};
 if(!window.k_segmentIO.runtime)
 {
     window.k_segmentIO.runtime = true;
     
// Depending on your setup, you'll need to determine the appropriate logic for obtaining the user ID.   

// If you've been using a track event call to send our visitor code, use the following line:  
const user_id = Kameleoon.API.Visitor.code;  

// Alternatively, if you use our Visitor Code as the Segment user ID or need to retrieve the user ID from Segment's analytics object, use the following line:  
const user_id = window.analytics.user().id() || window.analytics.user().anonymousId(); 
  
   Kameleoon.API.Data.retrieveDataFromRemoteSource(`IDENTIFY_${user_id}`, segment_identify_properties => {
         if(segment_identify_properties && segment_identify_properties.groupId){
             window.k_segmentIO.groupId = segment_identify_properties.groupId;
         }
     });
 }
 if(!window.k_segmentIO.groupId) return;
 return {"value": window.k_segmentIO.groupId, "overwrite": true};

To use group IDs in server-side experiments or feature flags, you can consult the guidelines outlined in the documentation for each respective SDK. For instance, if you’re using the GO SDK, you can refer to its documentation for detailed instructions.

The GO SDK, like our other SDKs, employs the GetRemoteData method, which is accessible across all our SDKs. This method enables you to fetch data stored by Segment on our servers and make it accessible within your backend code.

The “key” value to use as the first parameter should follow this format: “IDENTIFY_{user_id}”.