Concepts

Core concepts

To use Contentful Personalization you must first understand its core concepts. These concepts form the foundation of our software and guide you in creating and managing personalized experiences.

Audiences

Audiences allow you to segment your users based on specific attributes, events, behaviors, or preferences. By grouping users into audiences, you can tailor experiences to match their unique needs and increase engagement. You can define audience criteria by demographics, browsing behavior, or past interactions.

Learn more about how to create Audiences.

Data buckets

A data bucket is a type of data grouping that contains your personalizations, experiments and audiences, similar to a Google Analytics 4 property.

You can connect your environment to a data bucket to run your personalizations and experiments in Contentful Personalization.

Learn more about how to connect to a data bucket.

Experiences

Experiences are the core building block for delivering personalized content. An experience connects a piece of content to one or more variants (alternative versions) and an audience (who should see each variant). You can run multiple experiences on the same content simultaneously.

Contentful Personalization offers two types of experiences:

  • Personalizations: Deterministic. Visitors who match the audience always see the targeted variant. Use these when you know which content is right for a specific audience.
  • Experiments: Random split. Visitors are randomly assigned to a variant based on traffic distribution weights. Use these for A/B testing when you want to compare which content performs better.

On the technical side, experiences are represented by the nt_experience content type. Your content types get an nt_experiences field that links them to the experiences that can personalize them. For details on how this works in code, see Architecture and how it works.

Learn more about how to create Experiences.

Experiments

Experiments enable you to test content variations or design variations to determine what resonates best with your audiences.

With experiments, you can set up A/B tests, test on multiple components simultaneously, or run more sophisticated experimentation strategies. The SDK randomly assigns each visitor to a variant based on your configured traffic split, and the Insights system tracks which variant performs better.

Unlike personalizations (which always show the same variant to the same audience), experiments deliberately randomize assignment to produce statistically valid comparisons.

Learn more about how to create Experiments.

Personalizations

Personalizations deliver targeted content based on audience membership. Unlike experiments (which randomly split traffic), personalizations are deterministic. If a visitor matches the audience, they always see the targeted variant.

Use personalizations when you already know what content is right for a specific audience. For example, showing a German-language hero banner to visitors from Germany, or displaying enterprise pricing to visitors with the plan: enterprise trait.

Learn more about how to create Personalizations.

Merge tags

Merge tags provide inline personalization by inserting visitor-specific values into your content. Each merge tag resolves a path in the visitor’s profile. For example, traits.firstName becomes “Sarah” or location.city becomes “Berlin”.

Merge tags are represented by the nt_mergetag content type. Content editors can embed them in rich text fields for dynamic inline content. Developers can also use the <MergeTag> React component directly in JSX without Contentful entries.

Learn more about how to create Merge Tags.

Metrics

Metrics measure conversions and other actions that your experiences are optimizing for. They connect to track events sent from the SDK. When a visitor performs a tracked action (like completing a signup or making a purchase), Contentful Personalization attributes that conversion to the experience variant the visitor was shown.

Metrics are essential for experiments. Without them, you cannot determine which variant performs better.

Learn more about metrics and how to set them up.