# Understand why users leave onboarding unfinished Canonical: https://userreason.com/use-cases/onboarding-feedback/ Updated: 2026-11-09 A short survey after an explicit pause can tell you what that person needed at that moment. Ask one neutral question, offer an optional follow-up where it helps, and use the answers to choose what to investigate next. A pause is an observed action; it is not proof of abandonment or its cause. ## Start with a moment the person actually chose This recipe listens for an explicit Pause setup action. Keep the action useful on its own: someone may need information from a teammate, want to return later or decide the product is not right for them. The survey should not block leaving or require an explanation. | Observation | What it tells you | | --- | --- | | The person chooses Pause setup | They chose to pause at this step. You can offer a question while they are still present. | | The person closes a tab or becomes inactive | You have no answer about their reason. A missing later event can have several explanations. | | The person submits a survey answer | You have their reported reason, from a self-selected respondent at this moment. | If your product has no explicit pause action, choose another real, appropriate point in its flow before using this recipe. Do not name an inactivity timer onboarding_paused and interpret it as the same evidence. ## Ask one reason, with an optional follow-up The recipe asks “What led you to pause setup?” as a single-choice question. It keeps the question about the person’s current decision, without assuming the product was confusing or that they have abandoned it. It offers practical constraints as well as product problems; the person can close the survey without answering. | Answer option | Show the optional follow-up? | | --- | --- | | I don’t have time right now | No | | I need more information | Yes | | Something didn’t work as expected | Yes | | I’m not ready to continue | No | | Something else | Yes | The optional follow-up is “Is there anything else you’d like us to know?” It appears only for the three answers marked Yes. The recipe’s stable question IDs are pause_reason and pause_details. Review the wording and choices for your own flow before publishing; a person may have several reasons, even though this question asks them to select one. Save the complete definition below as survey.json and create a draft with the public CLI, following the paired Next.js guide. Alternatively, recreate its questions and conditions in the dashboard. This JSON is a survey definition for the CLI, not SDK initialization options or a dashboard import. survey.json — complete onboarding pause recipe ```json { "schema_version": 1, "name": "Onboarding pause feedback", "content": { "schema_version": 1, "title": "Before you pause setup", "description": null, "language": "en", "collect_partial_responses": true, "questions": [ { "id": "pause_reason", "kind": "single_choice", "prompt": "What led you to pause setup?", "required": true, "options": [ { "id": "time_now", "label": "I don't have time right now" }, { "id": "need_information", "label": "I need more information" }, { "id": "setup_problem", "label": "Something didn't work as expected" }, { "id": "not_ready", "label": "I'm not ready to continue" }, { "id": "other", "label": "Something else" } ] }, { "id": "pause_details", "kind": "text", "prompt": "Is there anything else you'd like us to know?", "required": false, "max_length": 2000, "logic": { "show_when": { "type": "answer", "question_id": "pause_reason", "comparison": { "operator": "one_of", "value": [ "need_information", "setup_problem", "other" ] } } } } ], "thank_you": "Thank you for sharing your feedback." }, "rules": { "schema_version": 1, "audience": { "type": "field", "source": "event_property", "key": "flow_version", "comparison": { "operator": "eq", "value": "nextjs-onboarding-v1" } }, "triggers": [ { "type": "event", "event_key": "onboarding_paused" } ], "frequency": { "mode": "custom", "max_shown": "1", "after_seen_seconds": 604800, "after_dismissed_seconds": 604800, "after_completed": { "type": "never" }, "after_screen_out": { "type": "never" } } }, "sampling_percent": 100, "priority": 0, "enrollment_epoch": "onboarding-pause-v1" } ``` - [Download the example and survey recipe](/examples/nextjs-onboarding.zip): Use the reviewed definition as a starting point for your development site. - [Writing useful surveys](https://docs.userreason.com/prompts/survey-quality/): Neutral wording, response options, timing and limitations. - [Survey definitions and conditional questions](https://docs.userreason.com/prompts/definition/): The current contract for the packaged survey definition. ## Report the pause with only the context you need After the explicit Pause setup action ```ts import userreason from '@userreason/js'; await userreason.event('onboarding_paused', { step: 'invite', flow_version: 'nextjs-onboarding-v1', }); ``` The example sends a step category and a stable flow version. These help you distinguish the workspace step from the invite step and avoid mixing answers from different onboarding designs. They do not need the person’s email, workspace name, invitation text, authentication token or full page URL. Browser-reported context is not a trusted account fact. Use it to describe this feedback opportunity, not to establish identity, billing eligibility or access. Warn people against including sensitive information in optional free text, and keep access to responses appropriate for their contents. The downloadable app uses memory storage and no visitor identification. Memory storage still permits network requests; choose the storage and consent behavior appropriate to your production app rather than assuming that this example settles those decisions. - [Implement this event in Next.js](/frameworks/nextjs/): Client lifecycle, environment variables, route navigation and saved-answer checks. - [Events and context](https://docs.userreason.com/sdk/events/): Choose a collection policy and understand browser-reported properties. ## Review the audience, frequency and published version - Use onboarding_paused as the trigger and the recipe’s flow_version = nextjs-onboarding-v1 event-property audience. Do not also show the same question on every onboarding page load. - Ask at a point where an interruption is acceptable, after the pause action has already succeeded. - Keep the event-property audience flow_version equal to nextjs-onboarding-v1 while testing this recipe, with 100% sampling on a development site. - Keep the recipe’s one-display limit per tracked visitor in this enrollment. Site-wide limits still apply, and a reload in memory mode creates a fresh visitor. - Preview every answer path and optional follow-up, then review and publish the intended version. Keep feedback optional. If the person dismisses it, let their pause stand. If you change the wording or targeting later, publish the reviewed revision; editing a draft does not change the survey already live. - [Targeting and frequency](https://docs.userreason.com/prompts/targeting/): Review delivery rules before exposing the survey to customers. ## Check which answers were actually saved Verify one complete response in the dashboard before using the answers to guide a decision. If partial collection is enabled, a visitor who advances past the reason question can leave a saved reason without completing the optional follow-up. Typing without advancing does not save the current answer. An open partial response means no close was recorded; it does not establish that the person is still in the survey. Keep partial and completed counts visible when reviewing results. - [Read partial responses](https://docs.userreason.com/prompts/partial-responses/): Saved-answer boundaries and response-status filters. ## Use reported reasons to choose the next investigation | Pattern in the answers | A practical next check | | --- | --- | | People need something they do not have yet | Check whether prerequisites are clear before setup begins and whether progress can be resumed. | | A step or instruction is unclear | Watch someone attempt that step and compare their explanation with the current interface. | | Something did not work | Try to reproduce the reported problem and review relevant product errors without treating survey text as a diagnosis. | | People are only exploring or plan to return | Check whether the flow supports that intent before classifying the pause as failure. | Read counts alongside the survey version, time period and step. Respondents are a subset of people who chose to pause and then answer. Their choices are not the abandonment rate for everyone who started onboarding, and a small set of answers cannot establish the prevalence or cause of a problem. Use recurring answers to prioritize a usability check, error investigation or small design change. To evaluate that change, define a separate behavioral outcome and compare the relevant groups or periods carefully. A better survey score alone does not prove that onboarding improved. ## Test the full path before asking customers The recipe’s schema and all five answer paths were checked on 18 October 2026. The paired example now pins SDK 0.5.0. Start with a development site, publish the recipe, choose Pause setup and check the saved response. Then adapt the moment and wording to your own product. - [Follow the Next.js implementation guide](/frameworks/nextjs/): Run the sample and verify both complete and partial responses. - [Download the Next.js onboarding example](/examples/nextjs-onboarding.zip): App code and a reviewable survey definition. - [Use your coding agent](/for-agents/): Ask for a draft and review it before publishing. The free allowance is 10,000 responses per workspace per UTC calendar month, across all its sites. A response counts once when its first answer is saved, including an unfinished response; later answers do not count again. The allowance resets at 00:00 UTC on the first day of the next month. At the limit, new responses are not recorded, while already-counted responses can still finish. - [See response allowances and pricing](/pricing/): Free workspace allowance and custom enterprise limits.