Do this with AI
Install the personalize skill from Contentstack agent skills and connect the Personalization Strategist profile in MCP Profile Hub. Then ask your agent:
For a first-time visitor from the Netherlands on mobile, walk me through which audiences they match in my Personalize project and which variant aliases they would get.
New to this? Set up your AI workbench first.
How Personalize resolves variants
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.
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.