Survey Lifecycle Events

Every platform emits a set of events as a survey moves through its lifecycle — see each platform’s own Events page for exact names and payload shapes, since those diverge (web’s survey:step vs. the natives’ survey:question_answered, object vs. bare-string payloads, and so on — Platform Parity has the full table). This page covers the design that’s shared across all of them.

Lifecycle events don’t re-trigger themselves

Survey lifecycle events (survey shown/dismissed/closed, question answered, survey completed) are excluded from trigger candidacy: without that exclusion, a wildcard survey (one with no triggerEventNames, which matches any event) would match its own survey_dismissed and immediately re-show itself. This exclusion only applies at the trigger-candidacy gate — if you deliberately write an EVENT_FREQUENCY condition against survey_completed in a Stage 2 rule, it still sees those occurrences normally.

on() returns a handle, not a promise to call off() correctly

on(event, callback) returns a Registration; call .cancel() on it to unsubscribe. This works identically everywhere and makes cancel() idempotent: calling it twice, or after the listener already fired once, is always safe.

Web additionally keeps off(event, callback) as a second mechanism (removes the first match by reference) — mainly for compatibility with code written before Registration existed.

ready replays for late subscribers

The natives’ ready event fires once initialize fully settles. A listener that registers after that point still receives it, rather than requiring you to race the subscription against initialization. Web has no ready event at all — see each platform’s Events page for what to use instead.