Segmentation

A segment is a named rule that decides who sees an experience. Segments live in Sunboard's control plane — not in your spec files — and at runtime Sunboard matches each user against them to choose what to show.

What a segment matches on

Every rule runs against the user you pass to the SDK, plus the events that user has completed:

• id, email, group — the top-level fields on the user object.
• Any custom attribute under user.properties — plan, role, signupDate, whatever you provide.
• Completed events — anything you've reported with useSunboard().track().

Rule types

A segment's rules are made of two kinds of clause.

Property rules

Match when a user property equals a value:

{ "property": "plan", "equals": "trial" }

property can be id, email, group, or any key under properties. Matching is exact equality, and the value is a string, number, or boolean.

Event rules

Match on whether the user has completed a tracked event:

{ "event": "workflow.created", "notCompleted": true }

notCompleted: true matches users who haven't fired the event yet (e.g. "hasn't activated"); false matches users who have.

Combining rules: all & any

Rules are grouped into all (every rule must match — AND) and any (at least one must match — OR):

{
  "all": [
    { "property": "plan", "equals": "trial" },
    { "event": "workflow.created", "notCompleted": true }
  ]
}

That targets trial users who haven't created a workflow yet.

• all → AND (every rule matches).
• any → OR (at least one matches).
• Both present → (all of all) and (any of any).
• Empty rules ({}) → matches everyone — useful as an "all users" catch-all.

How a user's experience is chosen

Segments only do something once routing binds them. A deployment is the tuple experience version × segment × environment. When a user loads your app:

1. The SDK sends the current user (and environment) to Sunboard.
2. Sunboard evaluates every active deployment's segment against that user.
3. For each experience, the most specific matching segment wins — the one with the most rules. A 2-rule "trial + admin" segment beats a 0-rule "everyone" segment.
4. Ties break to the higher version number.

So you can layer a broad catch-all and a narrow override on the same experience: the narrow segment wins for the users it matches, and everyone else falls back to the catch-all.

Targeting is strategy

Good segments map to a real cohort — role, plan, lifecycle stage, activation status, account size, acquisition channel. Name your exclusions too (already-activated users, internal admins, anyone missing a required entitlement), and expect targeting to evolve: pre-activation → post-activation → expansion. Reuse one canonical segment per cohort instead of creating parallel ones, which keeps analytics readable.

Managing segments

You never edit segments in your YAML specs — they're hosted. Create, update, and bind them by asking your agent for the Segment skill, or run the CLI commands directly.

Related