Surveys

Multi-step questionnaires. Use surveys when you need structured, comparable data — onboarding, churn reasons, pricing sensitivity, post-purchase CSAT.

1. 1 · Build

   Content & questions
2. 2 · Design

   Theme & layout
3. 3 · Target

   Audience · trigger · schedule · caps
4. 4 · Analyze

   Performance & responses

Stage 1 — Build

The Build stage is a question rail (left) + per-question settings + a live phone preview. Drag a question type into the flow, edit it, re-order.

Question types (8 in the dashboard palette)

The composer palette exposes 8 types:

Per-question settings

Every question has the same three core fields, plus type-specific extras:

• Title — the question your user reads.
• Subtitle (optional) — secondary line beneath the title.
• Required — checkbox. Blocks continue until answered.

Beyond that, the editor is intentionally minimal — schema-level fields like short_text validation modes (email/url/number/regex), nps/rating low/high labels, multi_choice min/max selections, and likert custom labels exist in the API but aren't yet in the composer. Reach the editor mock-room if you need any of these surfaced.

End screen

Surveys always end on an end screen. The editor exposes a headline (required, defaults to "Thanks!"). The schema additionally accepts a body, CTA, and follow-up CTA — those are API-only today.

Branching

The data model supports per-question branch rules (flow.branches) but the question editor doesn't yet expose a branching UI. Build branched surveys by POST-ing the survey JSON with the branches array — schema in apps/api/src/schemas/surveys.ts.

Stage 2 — Design

Same shape as the Build stage minus the editor — three panes: question rail · theme gallery + custom tokens · phone preview reflecting the selected question.

The theme tokens are identical to Feedback: primary, background, text, subtext, border, accent, button, borderRadius, fontFamily. Themes are shared across prompts, surveys, and in-app messages.

Stage 3 — Target

The flow is Audience → Platforms → Trigger. Platform choices come from the app's settings: React Native, Expo and Flutter offer iOS and Android, and Web is shown only when enabled. Select both native options to reach both app versions. See platform targeting.

Audience

Same builder as every other channel — see Segments for the 8 condition kinds and their operators. Combine with All / Any matching, preview the audience size live.

Trigger

Surveys use the shared composer trigger builder with 3 kinds:

The event kind exposes the same sub-controls as feedback:

• Event name — autocomplete from registered events.
• Property filters — narrow which events count (property + op + value).
• Trigger occurrence — Every time · First occurrence · After Nth occurrence (with a numeric N).

All three kinds share:

• Delay — in minutes.
• Once only — checkbox.
• Active window — date-range toggle with Start / End.

Frequency caps

The editor exposes 3 knobs:

The schema also accepts perGlobalDays and maxPerUser — those are API-only today.

Stage 4 — Analyze

After publish, the editor flips to a read-only Analyze view with:

• Funnel — Impressions → Started → Q1 answered → … → Completed.
• Per-question drop-off — which question loses the most respondents.
• Time-to-complete distribution.
• Per-question distribution — bars / histograms / counts depending on type.
• Raw responses export — CSV / JSON.

Status lifecycle

Save-resume

The SDK persists partial answers in encrypted on-device storage. If a user backgrounds your app mid-survey, the next open resumes at the unanswered question. Cleared on submit, on dismiss, and on UserGist.reset().

SDK side

const surveys = await UserGist.getAvailableSurveys()
const onboarding = surveys.find((s) => s.tag === 'onboarding')
if (onboarding) UserGist.openSurvey(onboarding.id, { language: 'en' })
 
// Deep-link surveys (API-only mode today)
UserGist.handleSurveyDeepLink(url)
 
// React to responses
UserGist.onResponse((info) => { /* … */ })

API

• GET /v1/apps/:appId/surveys — list
• POST /v1/apps/:appId/surveys — create
• PATCH /v1/apps/:appId/surveys/:surveyId — update
• DELETE /v1/apps/:appId/surveys/:surveyId — permanently delete
• GET /v1/apps/:appId/surveys/:surveyId/analytics — analytics rollup
• GET /v1/apps/:appId/surveys/:surveyId/responses — paginated raw responses

Canonical schemas: apps/api/src/schemas/surveys.ts.

Personalized questions and delivery

Use Insert field in supported survey content for saved user fields, latest activity or the triggering event. Each attempt keeps its resolved question snapshot, so a later watch event does not change a survey already in progress. See Personalize messages for source selection, fallbacks and Preview as user.

With the immediate-delivery API and SDK release, triggered surveys can include their authorized attempt in the delivery response. React Native also supports local starts for eligible cached, repeatable, uncapped, non-personalized surveys. These use a ten-minute signed permission and durable progress saving; new personalized surveys still need an online decision. See survey delivery and recovery for persistence, consent and offline limits.

What's next

• Guides → Run an NPS survey
• Features → Segments
• Features → In-app messages

Surveys on websites

The Web SDK supports opening surveys, listing available surveys, survey links, and save/resume. Activate a user and grant survey consent; tracked-event delivery also needs analytics consent. Select Web in Target and configure the browser dialog or side panel under Design → Web presentation, below themes. Narrow browsers use a full-height survey layout. Preview with Web desktop or Web mobile; only desktop offers enlargement.