Skip to Content
ConceptsHow Triggering Works

How Triggering Works

Every platform runs the same two-stage check before a survey can show. Nothing here is platform-specific — web, iOS, Android, and Flutter all agree on this behavior.

Stage 1: Trigger Check

The cheap eligibility check, run first, with no script execution:

  • Does the Trigger (a named event, or a DOM condition on web) match?
  • Is the survey allowed to resurvey this user (see Frequency below)?
  • Is the Cooldown or Daily Cap satisfied? (Every event frequency skips this — see Frequency.)
  • Is another survey already active? (Only one survey evaluation runs at a time — see Trigger Queue below.)

A survey with no triggerEventNames matches any event (a wildcard). Otherwise the incoming event name must be a member of that list.

Frequency

Stage 1’s resurvey check reads the survey’s Display frequency (Configure → Frequency & Scheduling):

  • Once — shown at most once. A display counts, not only a completion.
  • Until completed — re-shows until the user completes it.
  • Recurring — re-shows after N minutes, hours, or days.
  • Every event — shows on every matching trigger, including after completion. Bypasses the project cooldown and daily cap; a permanent dismiss (“Don’t show again if dismissed”) still blocks it. Another survey already on screen still wins.

Because Every event already bypasses cooldown, the per-survey Override global cooldown toggle is unused for that frequency — the dashboard hides it and notes that a custom cooldown is not used.

Stage 2: Rules Engine

Only runs if a survey passes Stage 1 and defines trigger rules. Executes a filter script fetched from the backend, evaluated against the user’s traits, context, and the triggering event — evaluated identically across all platforms.

EVENT_FREQUENCY/EVENT_RECENCY/EVENT_ABSENCE rules read a user’s eventHistory (capped at 90 days / 100 timestamps per event / 50 distinct event names). If a client’s local history doesn’t have an entry for a given event name at all, that’s treated as “never happened” and evaluated normally.

Trigger Queue

Concurrent trigger evaluations are serialized — only one survey evaluation runs at a time, in submission order. This prevents two events firing in quick succession from racing to show two surveys at once.

See Throttling for Cooldown/Daily Cap mechanics, and Survey Lifecycle Events for what fires once a survey does show.

TroubleshootingIdentity