Skip to main content
Contentstack MCP profile hub is in general availability!

How Personalize resolves variants

•
6 min read

Before you write an edge function, you need to know what it is asking for. Personalize has its own vocabulary, and half of it shows up in the CMS under different names. Once you know which object lives where, the code in the next chapters reads like plumbing.

What you'll learn

  • What a Personalize project, attribute, audience, experience and variant are

  • How the CMS mirrors experiences as variant groups

  • What the user manifest contains

  • How a variant alias maps to an entry variant

  • Where people usually get confused

The object model

Project

Personalize concept: A project is the container for everything in Personalize, connected to one stack.

You need the 24-character project UID to initialize the SDK. Find it in Personalize under Settings, General, Project Details.

Attributes

Personalize concept: Attributes are key-value pairs that describe a visitor.

There are two kinds:

  • Preset attributes come for free: city, country, region, date and time, device type, operating system, query parameter and referrer. The Edge API derives them from the request.

  • Custom attributes are ones you create in the project, such as plan or age. Your code sets them with the SDK set() method, or as live attributes at initialization.

Audiences

Personalize concept: An audience is a set of rules over attributes, combined with Match All or Match Any.

country = US and device = mobile with Match All is an audience. Personalize audiences are evaluated at the edge on each request and are not stored. Lytics audiences are the other kind: built from unified customer profiles in Lytics and passed to Personalize.

Experiences

Personalize concept: An experience is the decision. It holds variants and the rules for picking one.

There are two types:

  • Segmented: each variant targets one or more audiences. The first variant in the list whose conditions match wins.

  • A/B test: traffic is split across variants (equal, custom split, or Multi-Armed Bandit). The target group decides who enters the test: everyone by default, or only selected audiences.

A visitor has at most one active variant per experience.

Variants

Personalize concept: A variant is one outcome of an experience, such as "EU shoppers" or "Variant B".

Each experience and each variant has a short UID, such as a and 0. Short UIDs keep URLs and cookies small, and you will see them everywhere in the SDK.

How the CMS mirrors experiences

When a Personalize project is connected to a stack, the two stay in sync:

Personalize

CMS

Experience

Variant group (same name)

Variant

Variant inside that group

Nothing

Entry variant: the field overrides for one entry and one variant

A variant group only shows up in the entry editor after you link it to content types. Then an editor picks a variant in the entry and changes fields. The first change creates the entry variant.

Contentstack concept: Entry variants are diffs. They store only the fields that differ from the base entry, and the CDA merges base and overrides at read time. When an editor fixes a typo in the base entry, every variant that did not override that field gets the fix.

If you are coming from Git, think of the base entry as main and each entry variant as a small patch that is applied on read, never merged.

Entry variants are published like entries. Activate the experience in Personalize and publish the entry variants to your environment, or the CDA has nothing to return.

The user manifest

When the Edge SDK initializes, it calls the Personalize Edge API, which evaluates every active experience for this visitor and returns the manifest:

{
  "experiences": [
    { "shortUid": "a", "activeVariantShortUid": "0" },
    { "shortUid": "b", "activeVariantShortUid": "1" },
    { "shortUid": "c", "activeVariantShortUid": null }
  ]
}

The list is sorted by experience priority, highest first. Experience c had no matching variant, so it is null.

From manifest to alias

The SDK turns the manifest into three shapes. You use each one in a different place:

SDK method

Value

Used by

sdk.getVariants()

{ a: '0', b: '1' }

Your own logic

sdk.getVariantParam()

'a_0,b_1'

The URL, from the edge function

sdk.getVariantAliases()

['cs_personalize_a_0', 'cs_personalize_b_1']

The Delivery SDK

getVariantParam() and getVariantAliases() skip experiences without an active variant. On the origin, the static helper Personalize.variantParamToVariantAliases('a_0,b_1') turns the URL value back into aliases without initializing the SDK.

The alias is the contract between Personalize and the CMS. cs_personalize_a_0 means "experience a, variant 0", and the CDA knows which entry variant that is.

DiagramMermaid

Where people usually get confused

Confusion 1: "Variant" means two things

In Personalize, a variant is an outcome of an experience. In the CMS, a variant is the same thing, but the content lives in an entry variant per entry. A variant with no entry variant on a given entry renders the base entry for that entry.

Confusion 2: Audiences do not decide content directly

An audience only matters when an experience's variant targets it. Creating an audience changes nothing on the site.

Confusion 3: The manifest is not the content

The manifest says which variant a visitor should see. It does not prove that an entry variant exists or was rendered. That matters for impression tracking in chapter 4.

Confusion 4: Personalize audiences are not analytics

Personalize audience membership is computed per request and thrown away. If you need audience reporting or cross-channel profiles, that is a Lytics job.

Limits to remember

The default plan limits per project are:

  • 100 experiences, 100 audiences, 100 custom attributes and 100 events

  • 50 rules per audience

  • 20 variants per experience

  • 10 metrics per A/B test experience

Support can raise each of these. The Personalize Edge API has no published rate limit; the Management API is limited to 10 requests per second per organization.

Key takeaways

  • A visitor resolves to at most one variant per experience.

  • Experiences map to variant groups in the CMS; link the group to content types before editors can create entry variants.

  • Entry variants store only overridden fields and are merged by the CDA at read time.

  • The alias format is cs_personalize_<experience>_<variant>, and the URL form is <experience>_<variant>.

  • The manifest is sorted by priority, which becomes important when experiences overlap.

Frequently asked questions

  • What is a variant alias?

    A string in the form cs_personalize_<experience short UID>_<variant short UID>. It is how Personalize tells the CMS which entry variant to deliver.

  • Does an entry variant copy the whole entry?

    No. It stores only the fields you changed. Every other field inherits from the base entry.

  • What happens if a visitor matches no variant?

    The experience has no active variant for that visitor, no alias is produced, and the CDA returns the base entry.

  • Are Personalize audience memberships stored?

    No. Personalize audiences are evaluated per request at the edge and not persisted, so there are no audience analytics for them.