
aem-eds-personalization
Section-based personalization for AEM Edge Delivery Services (DA) pages: rules, a decision API, an A/B split or Adobe Target pick the EDS fragment a section shows, with the authored content as default; client runtime plus an optional Cloudflare edge worker.
- version
- 1.0.0
- GitHub stars
- 332
Install
/plugin install aem-eds-personalization@adobe-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.
Contents
Discovered from sourceSkills 1
personalize: sections → fragments
A personalized section is an authored section with Personalization rows in its Section
Metadata. Its content is the default. A variant is an EDS fragment that replaces that content
for the visitors it is chosen for. The browser, the edge and the scripts all run the same grammar
and decision code. Its JSON Schemas and pilot scenarios are in assets/contract/.
| Section Metadata | |
| Personalization | home-hero |
| Personalization Source | rules (default) | split | api | target |
| Personalization Variants | /fragments/personalization/home-hero/india |
| | /fragments/personalization/home-hero/na-mobile |
| Personalization Rule India | geo: IN |
| Personalization Rule NA Mobile | geo: US, CA & device: mobile |
The other sources add their own rows:
split:Personalization Split | 40, 30.api: optionalPersonalization HintandPersonalization Description <Variant>, plus Rule rows as the written fallback.target: an optionalPersonalization Location, and aPersonalization Triggerto make a popup.
The grammar is in reference/authoring-model.md.
When to Use
- Show a different section per country/region, device, new or returning visitor, URL/UTM param, page state, or custom audience.
- Let a decision engine (any v1 engine, or OF1) choose, with the Rule rows as its fallback.
- A/B test a section against its authored content (
split), or through Target. - Let Adobe Target pick a section's offer, inline or as a popup.
- Decide at the Cloudflare edge for above-the-fold sections.
Do NOT use for:
- Creating Target activities, audiences or offers, or AJO journeys: decline. The skill only wires sections to activities the Target user creates.
- Text tokens such as
{name}: not this skill. - Page-level experiments run with AEM Experimentation: keep them there. A page that runs one gets no personalized sections.
Critical Rules
- Paths.
scripts/andassets/are this skill's directories: resolve them against the folder holding this SKILL.md and use absolute paths. Run them from the project root. Every script answers--help. - The authored content is the default. Never delete, rewrite or reorder it. Personalization adds Section Metadata rows, variant fragments and, when needed, a section break or a new section.
- Never touch
scripts/aem.js, existing block code or the vendoredaem-worker.mjs. - Consent. The policy is no consent, no personalization. Never add a
withoutConsentexception on your own: exceptions need the site's privacy/legal approval and apolicyRef(reference/consent.md). - Choices, not gates. Ask only where there is a real choice (Step 2), always with its default.
No reply, or a hands-off run (
--hands-off, "no approval gates", non-interactive): take the defaults and list them as named assumptions in the summary. The only yes/no questions are the delivery confirmations below. - Local by default; delivery asks each time. Pushing the code branch, the DA upload and preview, and publishing are visible outside this machine. Each runs only after the user confirms that step, every time, even when the prompt asked for it. A hands-off run or no reply does none of them: it hands off the commands (Step 8).
- Off unless chosen:
wrangler deployandwrangler secret put(the site owner runs them), overrides on production, a third-party geo endpoint, andconfig.mockoutside tests. - Never:
- invent marketing copy (variants are
TODO:scaffolds unless the user gives the copy); - put API keys or tenant ids in browser code;
- send personal data to an engine or in events;
- list a variant named
default; - report a check as passed when it didn't run.
- invent marketing copy (variants are
Step 1: Preflight
node scripts/detect-project.mjs <project>
| Result | Action |
|---|---|
projectType: da | Continue |
xwalk / doc (exit 3) | Stop: "personalize supports DA projects only for now." |
sectionMetadata.renderedBy | pipeline: needs rendering v2 (Step 6 proves it). aem.js: works as is |
content.pagesWithExperiments, integrations.experimentation | Never personalize those pages or sections |
integrations.consentTools, consent.ask | Input for the consent choice (Step 2) |
integrations.atjs / websdk / launch / target | Ask which regions Target already owns (Step 2). Web SDK pages use target.transport: 'websdk' |
edge.cloudflare | The default mode becomes client + edge |
fragmentBlock.exportsLoadFragment: false | The installer adds the stock fragment block when it is missing; warn if one exists without loadFragment |
Step 2: Choices
Take what the prompt already says. Ask the rest as one grouped list, each with its default. No reply, or a hands-off run, takes the defaults.
| Choice | Default |
|---|---|
| Page and section | The section the prompt names; if only a page is named, its first section |
| Source per section | rules. api when the prompt names an engine: ask for the endpoint and a sample request and response. split for "A/B" or "50/50". target when Target should pick |
Display (target) | inline. popup with a trigger (scroll: 70%) when the prompt says popup, modal or scroll |
| Variant content | TODO: scaffolds copied from the section (user copy only when given) |
Consent (reference/consent.md) | A tool found: cmp, wired to it, and the category named. None found: deny (every section shows its default until a tool is connected); the alternatives are cmp with the user's tool, or allow if owner and legal confirm |
| Exceptions without consent | None. Only what privacy/legal approved, with where the approval is recorded |
| Regions Target owns | None of the requested sections |
| Mode | Client + edge when edge.cloudflare is reported or the prompt says so; otherwise client. A first section decided in the browser stays hidden for up to 800 ms, so recommend the edge, a later section or a popup. A slow engine (of1) on the first section requires the edge |
| Geo source | The edge meta tag, or the pzn-geo cookie when present; ?pzn-geo= in preview. No third-party endpoint |
| DA delivery | Local only. Push, DA upload + preview, and publish are each confirmed before they run (Step 8) |
Step 3: Install the Runtime
node scripts/install-runtime.mjs <project> --apply-hook
- It copies
scripts/personalization/*. If they are missing, it also creates the site-ownedconfig.js,styles/target-popup.cssandblocks/fragment/fragment.js; it never overwrites them. --apply-hookadds the two hooks inscripts.js: afterdecorateMain(main)inloadEager, and afterawait loadSections(main)inloadLazy. A hook reportednot-foundis placed by hand (reference/client-mode.md). Show the diff in the summary.- The report's
configlists whatconfig.jsstill needs (Step 5).
Step 4: Author Section Metadata and Fragments (local first)
For each section, in content/<page>.html (reference/authoring-model.md,
reference/da-content.md):
- Rows. Add the
Personalization …rows to the section's Section Metadata, creating the block at the end of the section if needed. Give the section a unique id. Leave its content exactly as authored.- To change part of a section: split it, and copy its
Stylerow. - For content only some visitors see: a new section with only the rows.
- To change part of a section: split it, and copy its
- Fragments. Write one fragment per variant at
content/fragments/personalization/<id>/<variant>.html, scaffolded from the section's content: same blocks, images and buttons, with the copy replaced byTODO:. - Rules. One condition per row. Repeat a variant with
Personalization Rule <Variant> 2. apisections. Add aDescriptionrow per variant andDescription Defaultwhen the engine uses them (OF1). They are public text.targetsections. The Target user needs JSON offers{ "fragment": "<path>" }or{ "control": true }on the section's location (reference/target.md).
Keep the H1 in the default and in every variant. Everything stays local until Step 8.
Step 5: Configure config.js
scripts/personalization/config.js is site-owned (reference/client-mode.md § Configuration):
consent:mode, plustoolforcmp, pluswithoutConsentandpolicyRefonly when approved. WirehasConsentto the tool, and have the tool's change callback callwindow.hlx.personalization.refresh()(reference/consent.md).api: a same-originendpoint(the edge route/pzn/decide, or the engine's proxy) andengine(genericorof1). Adapters for other engine formats go inedge-config.jsand are checked offline against the user's samples (reference/decision-api.md).target:transport,clientCode,propertyToken(reference/target.md).audiences, whenaudience:rules are used.mock: only for tests and demos; revert it before handover. Keepoverrides: 'preview'.
Step 6: Validate
With aem up running, run the checks in order (reference/preview-and-testing.md § Required
checks). Each prints PASS or FAIL. Fix and re-run until all pass; a check that couldn't run is
reported as not run.
node scripts/validate-placeholders.mjs content --repo <project>
node scripts/simulate.mjs content/<page>.html --page-url http://localhost:3000/<page>
npm run lint
node scripts/verify-preview.mjs --page http://localhost:3000/<page> --file content/<page>.html --consent-flow
Per source, add these (simulate takes only --api-decisions and --target; it ignores the
other flags, so pass them to verify-preview alone):
api:--api-decisions decisions.json(mock table) to both;--faultsand--refreshtoverify-preview.target:--target activities.jsonto both;--faultstoverify-preview.split:--split-runs 30toverify-preview.- A personalized first section, or layout changes:
--perf --baseline <url before>toverify-preview. - The OF1 pilot page:
--scenarios assets/contract/pilot-scenarios.json.
If verify-preview reports section not found, the hooks are missing or Section Metadata isn't
rendered as attributes (reference/authoring-model.md § Rendering prerequisite).
Step 7: Edge Worker (only if chosen)
node scripts/install-edge.mjs <project> [--route <host>/*] [--account <id>]
Or pass --existing <dir> and apply the printed wrap. Then follow
reference/edge-cloudflare.md:
- Copy
consentandfragmentPrefixesintoedge-config.js, and the engine adapters (OF1:adapters/of1.js). - Check with
simulate.mjs content/<page>.html --edge --repo <project> --consent --country US, again without--consent, and with--ua Googlebot. - Run
npx wrangler dev --local-protocol https.
Deploying and setting secrets are handed off to the site owner.
Step 8: Deliver (each step confirmed)
Only once every required check passes (reference/da-content.md). Ask before each numbered step, saying what it
changes and where; no answer means stop there and hand off the rest.
-
Commit the runtime, hooks, config and styles. Confirm, then push the code branch.
-
Confirm, then upload and preview only the personalized pages and their variant fragments, through the DA Source API with a
DA_TOKEN, or a DA MCP server's source and preview tools. -
Verify on
<branch>--<repo>--<owner>.aem.page(verify-preview.mjs). -
Publish only when both pass, then confirm:
node scripts/validate-placeholders.mjs content --repo <project> --publish(noTODO:);node scripts/install-runtime.mjs <project> --check-live https://main--<repo>--<owner>.aem.live(mainserves this runtime and both hooks).
Either one failing: stay at preview and say why.
With no DA access (token or MCP), a failed push, or no confirmation, deliver nothing more and hand off the commands.
Summary
Report the following:
- the files changed and the
scripts.jsdiff; - the per-variant
?pzn=<id>:<variant>preview URLs; - the consent setup (mode, tool and category, exceptions and their
policyRef); - named assumptions: every Step 2 default, and the mode with its reason;
- every
TODO:; - the check results (PASS, FAIL or not run);
- the delivery steps confirmed and run, and the ones handed off with their commands;
- the launch checklist (
reference/cross-cutting.md).
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Section never personalizes | Hooks missing; rows not rendered as data-personalization* (rendering v2); code not on the branch |
Always the default, data-pzn-outcome="no-consent" | Consent not given or not wired (consent.mode is deny, or hasConsent returns undefined), or no exception |
| Always the default, another outcome | data-pzn-outcome and data-pzn-reason say why: no geo source, rule order, low-confidence, fallback (HTTP 500, not listed: x), timeout |
| A rule disappeared | Two rows with the same name: number them (Rule India 2) |
| First section blank for a moment | Held for its decision (LCP): use the edge, a later section, or a popup |
| Popup never opens | No consent (waiting for consent), no offer, a trigger beyond the page; check the ?pzn-debug popup status |
| Events sent twice or missing | Same decision identity means no new events (reference/decisions-and-measurement.md) |
| Variant 404 locally | Fragment missing under content/fragments/..., or aem up needs a restart |
| Worker 500 locally | Run wrangler dev --local-protocol https; the origin must be main--<repo>--<owner>.aem.live |
?pzn-debug prints the decisions table. For anything else, hand back the page URL and that table.
References
reference/authoring-model.md: grammar, sources, attributes, rendering, placement, fragmentsreference/criteria.md: condition syntax, built-in criteria, custom audiencesreference/consent.md: consent modes, wiring the consent tool, exceptions, consent changesreference/decisions-and-measurement.md: outcomes,pzn:*events, decision identity, analysisreference/client-mode.md: installed files, hooks, lifecycle, budgets, public API,config.jsreference/decision-api.md: engine API v1, outcomes per answer, caching, server route, OF1, adapters, mockreference/split.md: section A/B, weights, assignment, reportingreference/target.md: Target mapping, popups, Delivery API and Web SDK transportsreference/edge-cloudflare.md: worker generation, request flow, the three edge results, deploy handoffreference/cross-cutting.md: fallback, SEO and bots, privacy, sharing, analytics, launch checklistreference/preview-and-testing.md: overrides, scripts, required checks, verify-preview, recipesreference/da-content.md: local content, DA upload, preview, publish onmain, noindex
Sponsors
Details
- Marketplace
- adobe/skills
- Source
- plugins/aem/edge-delivery-services-personalization
- Category
- Aem
More from adobe/skills
All 19- aem-forms-edge-delivery-servicesv1.0.1
- aem-project-managementv1.0.1
- app-builderv1.0.0
- commerce-app-management
- commerce-app-migration
- commerce-app-reviewv1.0.0
- run-workflowv1.0.0
- semrushv1.0.0
- stardustv0.39.4
- webv1.0.0
- workfrontv2.0.0
- adobe-analyticsv1.0.0
- adobe-cjav1.0.1
- adobe-for-developersv1.0.0
- aem-6-5-ltsv1.0.0
- aem-cloud-servicev1.4.4
- aem-edge-delivery-servicesv1.3.2
- aem-eds-content-opsv1.3.1