Experiences and Overlays

An ACI experience is an overlay applied to a base page, fragment, or data document. The base stays complete and publishable. The overlay contains only what changes for an audience or experiment arm.

Audience overlay paths

.content/overlays/audience/{audience-id}/pages/{page-id}/_index.json
.content/overlays/audience/{audience-id}/fragments/{fragment-id}/_index.json
.content/overlays/audience/{audience-id}/data/{data-path}/_index.json

The target document must exist in the base tree, and the audience must exist and be enabled.

Patch a component block

Suppose .content/pages/home/_index.json contains this base block:

{
  "$type": "component",
  "id": "hero",
  "component": "home_hero",
  "props": {
    "eyebrow": "Agentic Content Infrastructure",
    "headline": "Build better digital experiences.",
    "description": "Validated content, delivered safely.",
    "ctaLabel": "Learn more",
    "ctaHref": "/platform/"
  }
}

Create .content/overlays/audience/enterprise/pages/home/_index.json:

{
  "$type": "page-overlay",
  "metadata": {
    "title": "Enterprise Content Infrastructure"
  },
  "regions": {
    "main": {
      "hero": {
        "props": {
          "eyebrow": "For enterprise teams",
          "headline": "Governed content operations at enterprise scale."
        }
      }
    }
  }
}

hero is the base block’s id, not its component contract name. ACI patches that block in place and retains the base description and call to action.

Keep block IDs stable and unique within a region. Renaming a base block without updating its overlays leaves those patches without a target.

Merge behavior

Overlay value	Result
Object	Deep-merges into the corresponding base object
Region object keyed by block ID	Patches matching blocks in place
Region array	Replaces the complete region
`null`	Removes that field or region from the resolved experience

Prefer narrow field patches. Replace a full region only when the personalized experience needs a different composition and you intend to own the complete replacement. Only remove optional fields. The resolved result must still satisfy its component and layout contracts.

Personalize a shared fragment

Fragments use the same pattern. To personalize .content/fragments/navigation/_index.json, create:

.content/overlays/audience/enterprise/fragments/navigation/_index.json

{
  "$type": "fragment-overlay",
  "props": {
    "utilityLabel": "Enterprise support",
    "utilityHref": "/enterprise/support/"
  }
}

Every page that references the fragment can receive the resolved audience variant without duplicating the navigation content.

Combine locale and audience

When site configuration includes:

{
  "overlayResolution": ["locale", "audience"]
}

ACI can apply a locale overlay, an audience overlay, and a more specific combined overlay. A combined Spanish enterprise page uses:

.content/overlays/locale/es/audience/enterprise/pages/home/_index.json

The combined overlay applies after the individual dimensions and only needs to express what is different from the already resolved result.

Validate and review

npm run content:compile
npm run typecheck
npm run build

Then compare the base and selected experience on an ACI preview:

<preview-url>/
<preview-url>/?aci_audience=enterprise

Review the full result, including metadata, shared fragments, responsive layout, links, and fallback—not only the fields changed by the overlay.

Troubleshooting

The overlay compiles but nothing changes

Confirm the audience is enabled, audience appears in overlayResolution, the target page ID is correct, and the region key matches the base block’s id.

The whole region changed

Check whether the overlay supplies an array. Arrays replace regions; an object keyed by block ID patches selected blocks.

Removing a field fails compilation

A null value removes the field. If the component contract requires it, provide a valid replacement instead.

The locale and audience result is unexpected

Review the locale-only overlay, audience-only overlay, and combined overlay in that order. The combined path is most specific and applies last.

Next: Collection and Consent →

​Audience overlay paths

​Patch a component block

​Merge behavior

​Personalize a shared fragment

​Combine locale and audience

​Validate and review

​Troubleshooting

Audience overlay paths

Patch a component block

Merge behavior

Personalize a shared fragment

Combine locale and audience

Validate and review

Troubleshooting