Segments

A segment is a reusable audience — a saved query over user properties and behaviour. Every targeted channel (feedback, surveys, in-app, push, requests) uses this same builder, the same row UI, and the same DSL.

How conditions compose

A segment is a flat list of rows under one Match selector:

Click Add criteria to add rows. Each row is Field · Operator · Value. The dashboard supports a flat list today (no nested groups in the UI).

The pillar (feedback / survey / in-app) builders use the same row but add a top-level Everybody vs Send only to radio — segments skip that since "everyone" is just the absence of any criteria.

The 8 condition kinds

Field labels and hints match the dashboard verbatim.

1. Segment — "Pick from saved segments"

Reuse a saved segment as a row inside another segment.

Value: a list of segment IDs (multi-select from your saved segments).

{ "kind": "segment", "op": "is", "segmentIds": ["seg_paying_users"] }

2. Country — "Match by ISO country code"

ISO 3166-1 alpha-2 codes.

Value: list of country codes.

{ "kind": "country", "op": "is_any_of", "values": ["DE","FR","IT","ES","NL","BE","SE","DK","FI"] }

3. Last active — "When the user was last seen"

Recency on activity.

{ "kind": "last_active", "op": "before_days", "days": 14 }

4. Install date — "When the user first appeared"

Cohort by first-seen timestamp.

{ "kind": "install_date", "op": "within_days", "days": 7 }

5. Platform — "iOS / Android / Web"

Value: list of one or more platforms (ios / android / web).

{ "kind": "platform", "op": "is", "values": ["ios"] }

6. User property — "Custom user attribute"

The most flexible row. Match against anything you've sent via identify. The UI exposes 8 operators:

{ "kind": "user_property", "key": "plan", "op": "in", "value": ["pro", "enterprise"] }

7. Performed event — "Has / has not done X"

Behavioural matcher.

Plus fields:

• eventName — autocomplete from registered events.
• windowDays — 1–365. Defaults to 30.
• minCount (optional, for did) — only count if the user did it at least N times.

{
  "kind": "event_performed",
  "op": "did",
  "eventName": "session_started",
  "windowDays": 7,
  "minCount": 5
}

{
  "kind": "event_performed",
  "op": "did_not",
  "eventName": "subscription_canceled",
  "windowDays": 365
}

8. App version — "What version of your app the user is on"

Semver-aware matching against the SDK's reported appVersion.

{ "kind": "app_version", "op": "gte", "version": "2.4.0" }

Reserved properties (auto-attached)

Every event ingest carries an SDK-attached context. These keys are queryable from user_property rows without you having to set them.

Preview & audience size

As you edit, an audience badge updates with the current size + a small user sample. The preview hits POST /v1/apps/:appId/audience/preview and computes from ClickHouse in a single query.

Storage model

The DSL on disk, verbatim from @usergist/sdk-core:

interface AudienceSpec {
  version: 1
  mode: 'everyone' | 'match'
  combinator: 'all' | 'any'
  conditions: ReadonlyArray<AudienceCondition>
}
 
type AudienceCondition =
  | SegmentCondition
  | CountryCondition
  | LastActiveCondition
  | InstallDateCondition
  | PlatformCondition
  | UserPropertyCondition
  | EventPerformedCondition
  | AppVersionCondition

evaluateSegment(dsl, user, now) is exported from @usergist/sdk-core for server logic, previews, and parity tests. Production delivery eligibility remains server-authoritative.

Worked examples

Power users

{
  "version": 1,
  "mode": "match",
  "combinator": "all",
  "conditions": [
    { "kind": "user_property", "key": "plan", "op": "in", "value": ["pro", "enterprise"] },
    { "kind": "event_performed", "op": "did", "eventName": "session_started", "windowDays": 7, "minCount": 5 }
  ]
}

Trial day 3

{
  "version": 1,
  "mode": "match",
  "combinator": "all",
  "conditions": [
    { "kind": "install_date", "op": "within_days", "days": 3 },
    { "kind": "install_date", "op": "before_days", "days": 2 }
  ]
}

Churn risk

{
  "version": 1,
  "mode": "match",
  "combinator": "all",
  "conditions": [
    { "kind": "user_property", "key": "plan", "op": "in", "value": ["pro", "enterprise"] },
    { "kind": "last_active", "op": "before_days", "days": 14 },
    { "kind": "event_performed", "op": "did_not", "eventName": "subscription_canceled", "windowDays": 365 }
  ]
}

More: Guides → Targeting recipes.

API

• GET /v1/apps/:appId/segments — list
• POST /v1/apps/:appId/segments — create
• PATCH /v1/apps/:appId/segments/:segmentId — update
• POST /v1/apps/:appId/audience/preview — size + sample

Canonical schemas: apps/api/src/schemas/segments.ts. Evaluator: packages/sdk-core/src/evaluate/segment.ts.

What's next

• Guides → Targeting recipes
• Features → Events
• Features → Users