Contentful integration

Overview

This topic explains how to use the integration between LaunchDarkly and Contentful. The integration connects LaunchDarkly feature flagging with Contentful’s content management platform so that content editors and developers can manage experiments and flag-based content directly inside Contentful.

You can use the integration to:

• Create new LaunchDarkly feature flags from Contentful
• Map Contentful entries to specific flag variations
• Search and select existing flags from your LaunchDarkly project
• Coordinate feature and content launches
• Preview and manage variation content in Contentful

This integration lets you map Contentful entries to LaunchDarkly variation values so you can control which content displays to each audience. Editors create and map flags in Contentful, while developers evaluate flags using LaunchDarkly SDKs and render the mapped content at runtime.

How the integration works

The Contentful app adds a custom Entry Editor and Sidebar extension. These extensions let you:

• Create feature flags in LaunchDarkly using the API token you configure
• Store flag metadata and variation mappings on Contentful entries
• Retrieve LaunchDarkly projects, environments, and flag from Contentful
• Map variation values to Contentful entries so your application can resolve content at runtime

The integration writes only the data required to map flags to entries. All flag targeting rules and environments remain managed in LaunchDarkly.

Prerequisites

To use the integration, you must have:

• A Contentful account with permission to install apps and update content types
• A LaunchDarkly account with access to API tokens, projects, and environments
• A LaunchDarkly API access token that includes the createFlag and viewProject actions, which allow the integration to create and read feature flags.

You can create or manage API access tokens on the Authorization page. To learn more, read API access tokens.

Example API token policy

Use this JSON policy to create a custom role for the Contentful integration. It grants only the permissions required to create and view flags and projects:

1
[
2
  {
3
    "resources": [
4
      "proj/*:env/*:flag/*"
5
    ],
6
    "actions": [
7
      "createFlag"
8
    ],
9
    "effect": "allow"
10
  },
11
  {
12
    "resources": [
13
      "proj/*"
14
    ],
15
    "actions": [
16
      "viewProject"
17
    ],
18
    "effect": "allow"
19
  }
20
]

Configure the Contentful integration

Install and configure the integration to connect Contentful to your LaunchDarkly project and environment.

Install the integration

To install the LaunchDarkly app in Contentful:

1. In Contentful, navigate to Apps > Marketplace.
2. Search for “LaunchDarkly + Contentful.”
3. Select the app and click Install.
4. In the configuration screen, enter your LaunchDarkly API access token. The integration retrieves your available projects and environments.
5. Select the project and environment you want to use.
6. Click Create LaunchDarkly Feature Flag to generate the content type used for flag entries.
7. Click Save configuration.

Contentful encrypts your API key and uses it only during requests.

Enable the integration in the Entry Editor

The configuration screen includes an option that automatically applies “Entry Editor” settings. After configuration, confirm the following:

• LaunchDarkly is set as the “Entry Editor” for the LaunchDarkly Feature Flag content type.
• The default Contentful editor is removed.

You can also add the Sidebar to other content types that you plan to use for variation content. The Sidebar shows which entries are linked to LaunchDarkly flags.

To add the Sidebar:

1. In Contentful, navigate to Content model for content types that you may use for LaunchDarkly feature flags or experiments.
2. Select the content type you use for variation content.
3. Under “Sidebar,” click Add app and select LaunchDarkly.
4. Click Save.

Do not add the sidebar to the LaunchDarkly feature flag content model. The sidebar exists to display content entries that may be linked to a LaunchDarkly feature flag, not to modify the feature flag model itself.

Use the Contentful Entry Editor

The Entry Editor provides two workflows for connecting Contentful entries to LaunchDarkly feature flags:

• Create a new feature flag
• Map content to an existing flag

Create a new feature flag

To create a new feature flag inside Contentful:

1. Create an entry using the LaunchDarkly Feature Flag content type.
2. In the LaunchDarkly section, click Create New Flag.
3. Enter a flag name and verify the autogenerated key.
4. Add a description if needed.
5. Choose boolean, string, number, or JSON for your Variation type.
6. Define at least two variations with unique names and values.
7. Click Create flag in LaunchDarkly.
8. Click Start content mapping to begin mapping entries to flag variations.

After you create the flag, a confirmation card appears with links to view the flag in LaunchDarkly or continue mapping content.

Map content to an existing flag

To map Contentful entries to an existing LaunchDarkly flag:

1. In the LaunchDarkly section, click Map content to existing flag.
2. Search for the flag by name or key.
3. Click the flag to load its variations.
4. For each variation, click Select content to choose a Contentful entry.
5. Use Preview to review the content for each variation.
6. Click Save mapping.

The mapping order matches the variation order defined in LaunchDarkly.

Stored fields on entries

The integration stores the following fields on each LaunchDarkly feature flag entry:

The meta field exists so applications can perform stable lookups even if the variation order changes. Boolean flags resolve to true or false as the first two variations.

Implementation examples

These examples show how to evaluate feature flags and retrieve mapped content in an application.

Resolve mapped content using contentMapping

This example shows how an application identifies the active variation and selects the Contentful entry associated with that variation. The integration depends on the variation order defined in LaunchDarkly.

1
const activeVariation = await ldClient.variation(key, user, variations[0].value)
2
const variationIndex = variations.findIndex(v => v.value === activeVariation)
3
const mappedEntry = contentMapping[variationIndex]

Resolve mapped content using the meta field

This example shows how an application uses the meta field to look up the entry identifier for the active variation. The variation values become the keys for retrieving mapped content.

1
const activeVariation = await ldClient.variation(key, user, variations[0].value)
2
const entryId = meta[activeVariation]
3
const mappedEntry = await contentfulClient.getEntry(entryId)

Permissions and security

The integration maintains strict access controls and data handling practices. It:

• Uses your configured LaunchDarkly API key to create and read feature flags
• Stores only the flag name, key, description, variations, and mapped entry references in Contentful
• Encrypts and securely handles API keys
• Uses HTTPS for all communication
• Validates requests before processing

The integration does not allow editing of existing flags or variations. All targeting rules must be managed in LaunchDarkly.

Troubleshooting

If you encounter issues with the LaunchDarkly Contentful integration, try these common solutions.

The LaunchDarkly panel does not appear

If the LaunchDarkly section does not appear in the Entry Editor:

1. Confirm that LaunchDarkly is added to the Entry Editor.
2. Refresh the Contentful app after updating the content model.

Flags do not appear in the search list

If flags are missing when mapping content:

1. Verify that the API key has access to the selected project and environment.
2. Confirm that the flag exists and is active.
3. Ensure that the key includes createFlag and viewProject actions.

Mapped content does not appear correctly

If mapped content does not appear as expected:

1. Confirm that the LaunchDarkly variation order matches the Contentful mapping order index.
2. Ensure that variation names and values are unique.
3. Verify that mapped entries are published.

API key errors

If the integration cannot connect or displays an invalid API key message:

1. Re-enter your LaunchDarkly API key.
2. Confirm required permissions.
3. Verify that the key is active.

Next steps

• Learn more about feature flags
• Read about experimentation
• Explore other LaunchDarkly integrations