Was this page helpful?

Optimizely App

WARNING: Alpha apps are going to be deprecated by the 30th of November 2019. We highly recommend migrating any alpha app installations using our migration guide. We'd like to thank all participants for their feedback. If you have any questions please reach out.


The Optimizely app makes it easier to power experiments with structured content. It is connecting your content in Contentful with experiments in Optimizely. This enables practitioners to easily experiment with their content and run more experiments and create better insights faster.


Powering experiments with content from Contentful is a matter of connecting both APIs together. During rendering we can ask Optimizely to choose a variation based on targeting criteria which then allows to pick matching content from Contentful for that user.

However, this setup is fairly manual and tricky to manage as it usually requires manual copying of configuration between interfaces.

Optimizely app flow

The Optimizely app removes many of the hurdles for the user by integrating the two products. Practitioners can focus on the creation of great content and effective experiments instead of configuration.

The Optimizely app provides the following functionality:

  • add content variations to reference fields
  • assign content variations to experiments
  • monitor experimentation status


To use this app, you will need:

  • a website:
    • rendered on a server
    • pulling content from Contentful
    • pulling experiments from Optimizely Fullstack
  • a Contentful setup:
    • at least one content type with a reference field to link variations
    • the Optimizely app installed and configured
  • an Optimizely setup:
    • an Optimizely plan with access to the REST API
    • at least one project with one experiment in fullstack
    • experiment configured with variations and matching targeting / audiences assigned


Step 1: Install and configure

First you need to provide a personal access token. Visit app.optimizely.com/v2/profile/api to generate a Personal Token. As the app only needs read-access, it's advised to generate the PAT for a user with read-access only.


After a click on "Connect account" the lower dropdown can be used to select a project.

The last step is to enable reference fields for experimentation. Choose a content type from the list and then activate all reference fields which should be activated.

content type

Step 2: Understanding the changes to the content model

The app is creating a new content type: variation container. Let's compare an example content model with and without support for variations:

A content model with a reference field to hold "blocks":

Static content model

A content model transformed by the app with a reference field to hold "blocks" and variations of "blocks":

Experimentable content model

The variation container is used to manage variations of content. Entries of Variation Container use a fully custom UI which is powered by an Entry extension. Note the highlighted part to the right where the entry extension was assigned to the variation container.

The UI of the Variations Container

Furthermore the app is updating the validations of the fields which are meant for experimentation. In our example it looks like this:

Updated validations

NOTE: All reference fields without validation are implicitely enabled for the variation container as these fields allow linking of any content type.

Step 3: Creating content variations

Your space is now ready to serve content variations via Contentful's APIs. Navigate to the (activated) content type where an experiment is planned and find the reference field to add a new entry of content type variation container.

Updated validations

When the entry loads, please note its custom UI which uses the provided personal access token through a backend proxy to communicate with Optimizely's REST API. In the top dropdown choose the experiment:

Chose experiment

The variations are fetched from the experiment. All we need to do now is assign entires to the variations. The app is only listing content types which are allowed in the parent reference field.

Chose experiment

Conclusion and next steps

We have seen how the app can be used to create content variations and assign them to experiments. This enables your client applications to integrate with two services: Experimentation from Optimizely and structured content from Contentful.

To learn more about how to deal with variation containers and successfully leverage an Optimizely experiment, see the A/B testing tutorial.


Which changes is the app doing to my environment?

The app is:

  • creating a new content type "variation container"
  • customizing the editor_interface of that content type
  • adding the "variation container" to validations of all reference fields that were chosen during installation
  • a UI Extension replacing the entry UI and assigned to the sidebar of "variation container"

When will experiments be activated?

We vouch for clear separation of concerns. That means Contentful controls the content and Optimizely controls the experiment. The app is offering deeplinks into Optimizely to reduce friction when navigation between the two services.