Contentful

Contentful is a headless CMS: a composable content platform that meets the unique demands of digital content and all the teams that produce and work with it.

With the Contentful integration, you can bring experimentation capabilities to your CMS and run experiments on content directly from Contentful. You can also use Kameleoon’s powerful analytics solution to analyze the performance of Contentful experiments.

Key benefits:

• Run advanced no-code experiments on structured content.
• Eliminate the flicker effect with server-side instant bucketing and no latency.
• Reduce your reliance on developer resources for experimentation.
• Reduce the manual work needed to build experiments in Contentful and use Kameleoon’s powerful experimentation engine and analytics capabilities to measure the performance of your experiments.

Considerations

Keep these things in mind when using this integration:

• You can only use this integration with feature experiments.
• You must enable the Feature Experimentation solution in your Kameleoon account.

Prerequisites

To configure this integration, you need the following information from Kameleoon:

• Login credentials: Your Kameleoon login credentials are the email address and password combination that let you access your Kameleoon account. This integration uses the OAuth authentication to log in your Kameleoon account.
• Sitecode: You must provide your project's Sitecode. See the dedicated Kameleoon documentation to learn where to find your Sitecode.

Installation

1. Go to your Contentful account.
2. Click Apps > Marketplace, and search for Kameleoon.

3. Install the Kameleoon app and authorize access.
4. Select your project's Sitecode.
5. Click Install at the top right corner.

The Kameleoon app is now fully installed and ready-to-use.

Usage

Create a feature experiment in Kameleoon

To create a new feature experiment:

1. Log in to your Kameleoon account
2. Navigate to the feature flag dashboard.
3. Click New feature flag.
4. Enter a name, project, and feature key.
5. Validate.
6. Click Add a rule > Experiment to add an Experiment Delivery Rule.
7. Configure the rule however you wish.

Create a Kameleoon Container entry in Contentful

1. Log in to your Contentful account
2. Click Content.

3. Click Add Entry > Kameleoon Container.
4. Add an Entry Name and select an experiment in the Kameleoon experiments dropdown.
   • The variations associated with the experiment you selected will be automatically displayed, along with the allocated traffic percentage.

5. For each variation, click Create entry and link to create a new entry and use it as your variation content, or click Link an existing entry if you want to use an existing entry as the variation's content.

Get ready to publish your content

Your Kameleoon Container is ready to publish when you have completed these four steps:

Here's how you can complete each step:

• Select experiment: You can complete this step by selecting an experiment in the Kameleoon experiments dropdown.
• Add content: You can complete this step by associating an entry for each variation.
• Publish variations: This step is marked as complete when all the entries associated with the variations will be published.
• Start experiment: To complete this step, go to your Kameleoon account and use the manual toggle to turn the feature flag ON in the production environment.

Integration with your front-end

Kameleoon Container is a new content type that is introduced into the Contentful response. It is a container that points to two or more actual values that we'd like to test. You now need to integrate your front-end with Kameleoon and the Kameleoon Container. You will need the help of a developer to change how your front-end works to accept and programmatically handle the Kameleoon Container entries.

Programmatically handling the Kameleoon Container is something you only need to do once. Then, the code used to handle the Kameleoon Container can be reused every time you receive a Kameleoon Container entry from Contentful.

From here, we need to take a more technical dive into the client's setup and how it integrates with Kameleoon. It is beneficial for developers to get acquainted with the content we outlined above before moving on to the technical guide below.

The goals of the setup are:

• Enabling server side experimentation without pushing new code per experiment
• Controlling content in Contentful and experiments in Kameleoon
• Server side selection of variations for fast delivery and to avoid the flicker effect

How the Kameleoon App changes the Contentful API response

As mentioned above, the Kameleoon app creates a new content type: the Kameleoon Container.

The Kameleoon Container is a content type that nests the possible values for the experiment and holds metadata about the Kameleoon experiment and the variation names.

Using Kameleoon to pick the right variation

We are going to create a pseudo-back-end which takes the Contentful API response and uses our NodeJS SDK to determine which variation to show to the user.

Let's start by looking at the Kameleoon Container JSON response returned by Contentful. Notice that the content type exposes several fields related to the Kameleoon experiment: a featureKey and a meta with variation keys.

{
    "metadata":{
       "tags":[
 `  ]`
 },
    ……
    "fields":{
       "entryName":{
          "en-US":"Black Friday - CTA"
       },
       "experimentName":{
          "en-US":"Black Friday - CTA - Experiment"
       },
       "experimentId":{
          "en-US":"229925"
       },
       "featureKey":{
          "en-US":"contentful_black_friday_cta"
       },
       "siteCode":{
          "en-US":"kqfwz0rys3"
       },
       "meta":{
          "en-US":{
             "off":"5IF12vtaKcFJXtj8ljaDVr",
             "variation_1":"2UrVZemBoltsxHKcqRgjKk",
             "variation_2":"73GxfiNActyOZvP9Hn3sEC"
          }
       },
       "variations":{
          "en-US":[
             {
                "sys":{
                   "type":"Link",
                   "linkType":"Entry",
                   "id":"5IF12vtaKcFJXtj8ljaDVr"
                }
             },
             {
                "sys":{
                   "type":"Link",
                   "linkType":"Entry",
                   "id":"2UrVZemBoltsxHKcqRgjKk"
                }
             },
             {
                "sys":{
                   "type":"Link",
                   "linkType":"Entry",
                   "id":"73GxfiNActyOZvP9Hn3sEC"
                }
             }
          ]
       }
    }
 }

Before we can choose which entry to pick out of our Kameleoon Container, we need to see how to get the right variation from Kameleoon. Below is an example with the hard-coded feature key contentful_black_friday_cta in the Kameleoon method getFeatureFlagVariationKey(), which gets a variation for the user.

import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';

 const client = new KameleoonClient({
   siteCode: 'a8st4f59bj',
   credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' },
   configuration: { domain: 'www.example.com' },
 });
 async function init(): Promise {
   await client.initialize();

 // -- Get visitor code using server `request` and `response`
   const visitorCode = client.getVisitorCode({
     request: req,
     response: res,
   });

 // -- Get visitor feature flag variation key
   const variationKey = client.getFeatureFlagVariationKey(
     visitorCode,
     'contentful_black_friday_cta',
   );
 }
 init();

In the code above, the method getFeatureFlagVariationKey() determines if the user (or visitor) should see one of the variations or the original content. The value corresponds to a variation we can get from the Kameleoon Container meta field.

"meta":{
          "en-US":{
             "off":"5IF12vtaKcFJXtj8ljaDVr",
             "variation_1":"2UrVZemBoltsxHKcqRgjKk",
             "variation_2":"73GxfiNActyOZvP9Hn3sEC"
          }
       }

Now we will update our code to include pulling the Kameleoon Container automatically and using its values to populate the Kameleoon experiment so you don't need to do it every time you create and run a new experiment.

note

This is a one time setup that will work for all subsequent experiments that you create.

import { KameleoonClient, CustomData } from '@kameleoon/nodejs-sdk';
 import sdk from 'contentful-sdk';

  const client = new KameleoonClient({
    siteCode: 'a8st4f59bj', // Your Kameleoon project sitecode
    credentials: { clientId: 'my_client_id', clientSecret: 'my_client_secret' }, // Your Kameleoon API credentials 
    configuration: { domain: 'www.example.com' },
  });

  async function init(): Promise {
    await client.initialize();
  // -- Get visitor code using server request and response
    const visitorCode = client.getVisitorCode({
      request: req,
      response: res,
    });

We are using the Kameleoon Container's ID from the JSON sample above. In a real-world implementation, the ID would be set dynamically through a slug, for example.

const kameleoonContainerEntry = await
sdk.getEntry('5XJ5TWDvAzPh7QgWN4ysaV');

We get the feature key from the Kameleoon Container entry:

const featureKey = kameleoonContainerEntry.featureKey;

We get the variation's key:

const variationKey = client.getFeatureFlagVariationKey(
    visitorCode,
    featureKey,

    );

We get the Contentful entry associated with the variation using the variation key:

const variationEntry = kameleoonContainerEntry.meta[variationKey];
}
 init();

From here, you can make minimal changes to your display logic to show the correct entry.

Using Kameleoon to target a segment of users

You can target a specific segment of users in Kameleoon. You can read this documentation that explains how to create segments of users and include/exclude them from your experiment.