Personalization Quickstart

This guide gives you a working personalization path: a visitor records a preference, ACI evaluates that consented event, and a later request can receive the matching compiled experience. Visitors without a matching membership continue to receive the base page.

Access: Must be enabled for your organization. Contact your Gradial team to get access.

Prerequisites

Node.js 22 or newer
npm 10 or newer
A personalization-enabled ACI site for hosted preview

Local development does not require an ACI account. It verifies content, contracts, overlays, and rendering. Hosted preview is required to verify consented identity and request-time selection.

1. Create the starter site

Astro is the shortest path to a new ACI project:

npx @gradial/aci init my-site \
  --template astro-starter \
  --with-starter-content

cd my-site
npm install
npm run dev

Open the local URL printed by Astro. The starter compiles .content/ on startup and refreshes the page when content changes.

2. Find the personalization resources

The starter includes one complete example:

.content/
├── audiences/
│   └── preference-blue/_index.json
├── segments/
│   └── preference-blue/_index.json
├── overlays/
│   └── audience/preference-blue/pages/home/_index.json
├── pages/home/_index.json
└── config/site.json

The base homepage contains a component block with a stable ID:

{
  "$type": "component",
  "id": "personalization-choice",
  "component": "personalization_choice",
  "props": {
    "title": "Choose your connection preference",
    "description": "Select a preference, allow the update to process, then refresh personalization.",
    "redLabel": "Choose Red",
    "blueLabel": "Choose Blue",
    "refreshLabel": "Refresh personalization"
  }
}

The rendered buttons record a custom event without application-specific analytics code:

<button
  data-aci-event="preference"
  data-aci-prop-color="blue">
  Choose Blue
</button>

ACI normalizes that event to custom.preference.

3. Understand the segment

.content/segments/preference-blue/_index.json defines the behavior that qualifies:

{
  "$type": "segment",
  "props": {
    "id": "preference-blue",
    "displayName": "Latest preference is Blue",
    "status": "enabled",
    "priority": 100,
    "criteria": {
      "all": [
        {
          "type": "event_latest",
          "event": "custom.preference",
          "properties": {
            "color": "blue"
          }
        }
      ]
    }
  }
}

event_latest evaluates the most recent event with that name. Here, the color property must be blue.

4. Connect the segment to an audience

.content/audiences/preference-blue/_index.json gives that membership a stable target:

{
  "$type": "audience",
  "props": {
    "id": "preference-blue",
    "displayName": "Blue preference",
    "status": "enabled",
    "priority": 100,
    "membershipSource": "segment",
    "segmentRef": "$ref:segments/preference-blue"
  }
}

The segment decides membership. The audience decides which experience can be selected. Keeping them separate lets you reuse targeting logic across content.

5. Inspect the experience overlay

.content/overlays/audience/preference-blue/pages/home/_index.json patches the base block by its ID:

{
  "$type": "page-overlay",
  "regions": {
    "main": {
      "personalization-choice": {
        "props": {
          "title": "Blue preference active",
          "description": "Your latest preference is Blue. Choose Red to replace it."
        }
      }
    }
  }
}

Only the two changed fields appear in the overlay. ACI retains the remaining props from the base component and validates the resolved experience against the same contract.

6. Confirm site configuration

The starter’s .content/config/site.json includes the audience dimension and enables collection:

{
  "overlayResolution": ["locale", "audience"],
  "personalization": {
    "collect": true,
    "consentPreset": "c15t",
    "consentCategories": "measurement,marketing"
  }
}

The preset connects to an existing consent manager; it does not define your privacy policy. See Collection and Consent before using real traffic.

7. Run the local gates

npm run content:compile
npm run typecheck
npm test
npm run build

A successful compile proves that the segment, audience reference, overlay, base page, and component contract resolve together. A successful local render does not prove hosted identity or edge selection.

8. Preview the selected experience

Push the reviewed content to an ACI branch, then open the branch preview supplied for your site:

npm exec -- aci branch create personalization-preference \
  --source-ref main

npm exec -- aci content push \
  --branch personalization-preference \
  --dry-run

npm exec -- aci content push \
  --branch personalization-preference

On the ACI preview surface, compare:

<preview-url>/
<preview-url>/?aci_audience=preference-blue

The first request must show the base experience. The second explicitly selects the compiled audience variant for preview. The aci_audience selector is a preview control; production selection follows authored targeting and consented membership. When both paths are correct, continue with Preview, Publish, and Roll Back.

Next: Audiences and Segments →

​Prerequisites

​1. Create the starter site

​2. Find the personalization resources

​3. Understand the segment

​4. Connect the segment to an audience

​5. Inspect the experience overlay

​6. Confirm site configuration

​7. Run the local gates

​8. Preview the selected experience

Prerequisites

1. Create the starter site

2. Find the personalization resources

3. Understand the segment

4. Connect the segment to an audience

5. Inspect the experience overlay

6. Confirm site configuration

7. Run the local gates

8. Preview the selected experience