Migration considerations for the Contentful integration

The Optimizely app in Contentful supports experiments in Optimizely Feature Experimentation and legacy Full Stack Experimentation. For existing customers using the Optimizely app in Contentful with Full Stack Experimentation, you should remember these considerations when migrating your legacy Full Stack Experimentation projects to Feature Experimentation.

A/B test differences between Full Stack Experimentation and Feature Experimentation

An A/B tests in Full Stack Experimentation has the following components:

1. Experiment name – Display name for the A/B test.
2. Experiment key – Unique identifier for the A/B test used with the Optimizely SDKs to make decisions.
3. Environments – Each environment has a unique SDK key. You can run or pause environments independently in Full Stack Experimentation. You can then use the appropriate environment’s SDK key in the code of the respective environment.
4. Variations – You can define variations and configure the percentage of traffic distributed to them. Variations are shared across environments.

You will notice a few differences when you migrate a Full Stack Experimentation project to Feature Experimentation. A/B tests in Feature Experimentation are converted to flag rules, which are built on top of feature flags:

1. Flag name – Display name for the feature flag. After migration, this matches the name of the A/B test you defined in Full Stack Experimentation.
2. Flag key – After migrating, an UUID for the flag key is generated for uniqueness. This flag key is used with the Optimizely SDKs, specifically the decide API, to make decisions.
   No code changes to the Optimizely SDKs are required to migrate to Feature Experimentation. After your project is migrated, legacy SDK methods such as activate still work with the A/B tests in the migrated project.
3. Environments – In Feature Experimentation, you can independently create rules in each flag's environment. After migrating an A/B test, a flag rule is created under each environment of the flag (previously, environments were shared across an A/B test). Each flag rule shares the identical settings you previously configured in Full Stack Experimentation, such as variations and traffic distributions, but can be independently changed.
4. Variations – The overall set of variations you created are shared across a flag, but you can configure different subsets of variations to use with each A/B test rule.

See Migrate legacy A/B test for more.

Optimizely app in Contentful

The differences in A/B tests between Full Stack Experimentation and Feature Experimentation affect how you configure experiments in Contentful with the Optimizely app.

Use with Full Stack Experimentation projects

The Optimizely app in Contentful lets you select an A/B test from a Full Stack Experimentation project. When you select an A/B test in Contentful, the variations you define in Optimizely for the A/B test are automatically populated in Contentful, and you can choose which content you want to show visitors for each variation:

Use with Full Stack Experimentation projects migrated to Feature Experimentation

The Optimizely app in Contentful also lets you use A/B tests from Feature Experimentation. However, after migrating a project to Feature Experimentation, there are some important considerations to remember.

After migrating a Full Stack (Legacy) project already connected in Contentful to a Feature Experimentation project, the first time you go to the project's variation container in Contentful, you must refresh the page in your web browser to continue editing. You are prompted to do so with a window like the following:

After migrating from Full Stack Experimentation, you can independently manage and change the settings of individual A/B tests across each environment in your flag, such as status (running or paused), audiences, metrics, variations, and so on (previously in Full Stack Experimentation, A/B test settings were shared across environments):

When using the Optimizely app in Contentful with Feature Experimentation projects, you can select which A/B test flag rule to use in Contentful. Unlike with Full Stack Experimentation projects, you can select which environment’s rule to use:

A/B tests of primary environments in Feature Experimentation

After migrating from Full Stack Experimentation to Feature Experimentation, your existing experiments continue to run. The content you configured for each variation in Contentful continues to display to your visitors, regardless of the environment of each A/B test flag rule.

For A/B tests from Full Stack Experimentation projects migrated to Feature Experimentation, the Optimizely app in Contentful automatically selects the A/B test flag rule from the primary environment to use with your existing variation container post-migration. Any changes to variations for the A/B test flag rule of the primary environment in Feature Experimentation automatically reflect in Contentful.

A/B tests of non-primary environments in Feature Experimentation

If you change variations of an A/B test flag rule of a non-primary environment in Feature Experimentation post-migration, Contentful does not reflect these changes. For flag rules in non-primary environments, you must take additional steps to configure Contentful depending on your situation.

Option 1:

This option is best if you have already launched the experiment in your primary environment to avoid any disruptions in Production.

Complete these steps in Contentful:

1. Create a variation container.
2. Select the A/B test flag rule from the non-primary environment of interest.
3. Add content to each variation. See the note below Option 2.

After completing the steps in Contentful, a developer must update the references of the existing variation container in your non-primary environment's code to the entry ID of the variation container created in step 1. The existing variation container will remain linked to the A/B test of the primary environment in Feature Experimentation:

Option 2:

This option is best if you are still working on your experiment in a non-primary environment and have not implemented it in your primary environment.

Complete these steps in Contentful:

1. Update the existing variation container to use the A/B test rule from the non-primary environment of interest.
   • This unlinks the variation container from the primary environment's A/B test rule. The variations defined in Feature Experimentation for the A/B test rule in the selected non-primary environment are automatically updated in Contentful instead of the variations from the primary environment's A/B test rule.
2. Add content to each variation. See the following note.

If you already implemented the existing variation container in your non-primary environment, then no code changes are needed because the the entry ID of the variation container has not changed.