Audiences and Segments - Gradial Docs

An audience names who an experience is for. A segment describes the first-party behavior that qualifies a visitor for that audience. For targeting that depends only on the current request, an audience can reference a request rule instead.

Resource locations

.content/
├── audiences/{audience-id}/_index.json
├── segments/{segment-id}/_index.json
└── rules/{rule-id}/_index.json

Each resource ID must be one path-safe segment and match its directory name.

Define a behavior-based segment

This segment qualifies a visitor who viewed /pricing at least three times in the last seven days but has not completed the demo-request goal:

{
  "$type": "segment",
  "props": {
    "id": "high-intent",
    "displayName": "High-intent visitors",
    "status": "enabled",
    "priority": 200,
    "criteria": {
      "all": [
        {
          "type": "event_count",
          "event": "rum.page_view",
          "path": "/pricing",
          "minCount": 3,
          "withinDays": 7
        }
      ],
      "none": [
        {
          "type": "event_exists",
          "event": "custom.demo-request"
        }
      ]
    }
  }
}

Criteria groups use these rules:

every condition in all must match;
at least one condition in any must match;
no condition in none may match; and
the segment must include at least one positive all or any condition.

Condition types

Type	Use it when	Required fields
`event_count`	An event must occur a minimum number of times	`event`, `minCount`
`event_exists`	At least one matching event is enough	`event`
`event_latest`	The latest matching event must satisfy the filters	`event`

All three types can filter by path, referrer, scalar properties, an experiment and arm, or a positive withinDays window. A trailing * performs prefix matching for path, referrer, and string property values.

Use canonical event names in criteria: built-in events use namespaces such as rum.*; custom events use custom.*.

Connect the segment to an audience

{
  "$type": "audience",
  "props": {
    "id": "high-intent",
    "displayName": "High-intent visitors",
    "status": "enabled",
    "priority": 200,
    "membershipSource": "segment",
    "segmentRef": "$ref:segments/high-intent"
  }
}

Both resources must be enabled for the audience to participate in selection. A draft or disabled resource remains versioned but is not eligible for live delivery.

Define a request-based audience

Request rules are useful when the current request provides everything needed for a decision, such as campaign parameters. They do not require a stored behavior history. Create .content/rules/enterprise-campaign/_index.json:

{
  "$type": "audience_rule",
  "props": {
    "id": "enterprise-campaign",
    "status": "enabled",
    "description": "Enterprise campaign traffic",
    "expression": {
      "all": [
        {
          "field": "utm.campaign",
          "operator": "startsWith",
          "value": "enterprise-"
        }
      ]
    }
  }
}

Then reference it from an audience:

{
  "$type": "audience",
  "props": {
    "id": "enterprise-campaign",
    "displayName": "Enterprise campaign visitors",
    "status": "enabled",
    "priority": 100,
    "membershipSource": "rule",
    "ruleRef": "$ref:rules/enterprise-campaign"
  }
}

Request rules support query.*, utm.*, header.*, cookie.*, trusted geo.* facts, and referrer. Supported operators are equals, contains, startsWith, and exists.

Header, geographic, and device facts depend on the configured hosting adapter. Confirm the available trusted facts for your deployment before using them in customer-facing targeting.

Priority and fallback

When several audiences match the same request, the higher audience priority wins. Give overlapping audiences distinct priorities so the intended result is easy to review. ACI uses the base experience when no audience matches or when a required fact, reference, or consented identity is unavailable. Build the base page as a complete, valid experience and test it alongside every audience variant.

Validate a change

npm run content:compile
npm run typecheck
npm test

Compilation validates criteria shapes, resource status, references, overlay targets, and each resolved variant before the change reaches a release.

Next: Experiences and Overlays →

​Resource locations

​Define a behavior-based segment

​Condition types

​Connect the segment to an audience

​Define a request-based audience

​Priority and fallback

​Validate a change

Resource locations

Define a behavior-based segment

Condition types

Connect the segment to an audience

Define a request-based audience

Priority and fallback

Validate a change