Mobile Onboarding Flow: Branching, Recovery, and QA
Build a mobile onboarding flow with worked branching examples, interruption recovery, event definitions, and a practical QA matrix for apps and games.
A mobile onboarding flow needs a rule for every place a customer can continue, go back, leave, or return. Start with a first useful action, define the states needed to reach it, and decide what survives interruption. Then connect each transition to an observable result.
This guide is an implementation worksheet for product designers and mobile engineers. For choosing onboarding patterns and goals, start with the mobile app onboarding overview. Here, we turn a proposed journey into branches, recovery rules, events, and test cases. The fitness, productivity, and game examples below are illustrative designs, not customer results or claims of conversion lift.
1. Write the activation contract before drawing screens
Choose a behavior that shows the customer received value. “Finished the welcome slides” describes navigation. “Completed the first saved task” describes a product action. Keep both measurements if they are useful, but do not treat them as interchangeable.
Write five decisions in the brief:
- Eligible customer: Who should enter? Separate a genuinely new customer from someone reinstalling, returning after a break, or joining an existing account.
- First useful action: What exact app behavior counts as activation? Choose an outcome the app can observe.
- Required inputs: Which answers change the immediate result? Defer questions that only enrich a marketing profile.
- Exit and return: Where can the customer skip or leave, and what will they see on the next launch?
- Measurement window: How long after entry will you count the activation outcome? Choose this before comparing variants.
For a task app, a possible contract is: new solo customers can select a template, create a task, and complete it within their first day. Account creation is required only when they choose a capability that needs an account, such as synchronization. This is a product decision for that example, not a rule every app should follow.
2. Model states and transitions explicitly
A screen list describes what can appear. A transition table also describes why it appears and what happens when an operation fails. Use stable state identifiers that remain meaningful when you change the copy.
| State | Entry condition | Action and next state | Recovery rule |
|---|---|---|---|
| Resolve customer | App opens without a resolved route | Load identity and saved progress; route to goal selection, a resumable step, or the product | Use an explicit loading or retry state; unknown access is not confirmed lack of access |
| Select goal | No usable saved goal | Save a valid goal, then show its preview; a skip uses a documented default | Restore the selection after interruption; back navigation does not erase it silently |
| Preview result | A goal or default is available | Start the first useful action; offer editing if the result is unsuitable | Keep the last usable preview when a refresh fails |
| Perform first action | The app is ready to perform it | Record completion only after the app confirms success | Retry the operation without duplicating its result |
| Optional next step | First value reached, or a capability requires setup | Offer account setup, a contextual permission, or an eligible paid capability | Handle cancellation and denial with a usable return path |
| Finished | The defined onboarding requirement is satisfied | Open the appropriate product destination | Do not restart the whole introduction on every launch |
Define transition precedence when several conditions match. For example: restore the correct account first, resolve access next, resume compatible progress next, and start a new introduction only if needed. A returning subscriber should not enter a purchase branch merely because an asynchronous access lookup has not completed.
In the app's implementation, distinguish unknown, loading, allowed, not_allowed, and error where those states affect the route. These are suggested application states, not Nuxie API constants. A timeout belongs in recovery logic; it is not evidence that the customer should buy again.
3. Work through three concrete branching examples
Fitness app: ask only what changes the first session
Suppose the app offers guided workouts. Ask for a goal and available equipment, then show a matching session preview. The branch should change something tangible, such as the exercises or equipment requirements. If two answers produce the same preview, reconsider whether that question belongs before first value.
A candidate route is goal → equipment → session preview → begin session. Returning customers can resume a saved plan. Customers with access can begin the appropriate session; those without access can see an accurate offer if the selected session requires it. A purchase cancellation returns to the preview rather than discarding the answers. Completion of a session, choosing a plan, and starting a trial remain separate outcomes.
Productivity app: distinguish solo use from an existing invitation
A new solo customer can choose a starter template and create a first task. A customer arriving through a team invitation needs to validate that invitation and enter the right workspace. Asking the invited customer to name a new workspace creates an unnecessary competing path.
Write the expired-invitation case alongside the happy path: explain the failure, provide a way to request another invitation, and preserve a route to other accessible workspaces. Do not count a button tap as joining the team. Wait for the authoritative membership operation to succeed.
Game: checkpoint the tutorial around real play
For a puzzle game, a candidate first win is completing a short playable level. Teach the next mechanic at the moment it can be used. Persist a checkpoint after the game confirms progress, and make replay behavior explicit.
If the process ends after the player earns a reward but before the tutorial advances, resuming must not grant the reward twice. Keep reward ownership in the game's authoritative state and let the tutorial read it. The same principle applies to starter purchases: dismissing an offer is a navigation event, while ownership comes from the purchase system.
4. Specify interruption, identity, and version behavior
For every resumable step, decide which data is durable: a flow version, stable step identifier, confirmed answers, operation identifiers, and completion state may be sufficient. Store only what the app needs. Avoid placing sensitive free-text answers or credentials in general analytics events.
- Background and process exit: Reopen at a meaningful checkpoint. Confirm whether the underlying operation succeeded before replaying it.
- Offline launch: Choose a usable cached or built-in fallback where possible. If a required operation needs the network, explain that and offer retry instead of an indefinite spinner.
- Sign-in: Reconcile anonymous progress with the selected account. Do not overwrite established account progress with a fresh local introduction.
- Sign-out or account switch: Clear or partition customer-specific progress so the next person does not inherit another person's answers or access.
- Published flow change: Define whether existing sessions finish their version, migrate at a safe checkpoint, or restart with an explanation. Verify what your chosen delivery system actually supports.
Remote delivery does not remove these app integration responsibilities. A new camera capability, for example, still needs the appropriate app implementation and platform permission handling. Android's runtime permission guidance recommends asking in context and providing a degraded path after denial. Keep the permission result separate from onboarding completion.
5. Define events with a denominator and an owner
An event contract should say when an event is emitted, which system owns the truth, and how repeated delivery is handled. The names in this table are illustrative app events; they are not automatically collected SDK events.
| Event | Emit when | Useful context |
|---|---|---|
onboarding_entered | An eligible customer enters the measured journey | Attempt ID, flow version, eligibility cohort |
onboarding_step_shown | The step becomes visible | Attempt ID, stable step ID, branch, presentation ID |
onboarding_answer_confirmed | A valid answer is saved | Step ID, approved option key, answer revision |
onboarding_exited | The app observes an explicit skip or dismissal | Step ID and exit reason; do not invent an exit event for an unobserved process death |
first_task_completed | The task system confirms the first qualifying completion | Stable task ID, customer identity, completion time |
Define a deduplication key for each event. A network retry should retain the same event identity; a genuinely new presentation should have a new presentation identity. Preserve both occurrence and receipt time if your pipeline needs to distinguish delayed uploads from current behavior.
For an illustrative activation metric, use unique eligible customers who completed the qualifying action within 24 hours ÷ unique eligible customers who entered. This is a suggested cohort definition, not the definition of every analytics dashboard. Wait until each included customer has had the full window. An incomplete final-day cohort can make a recent version look worse simply because its customers had less time.
Track screen completion separately, and inspect step drop-off by branch. If the team wants a causal comparison, assign comparable eligible customers to variants and preserve that assignment. A before-and-after change can also reflect acquisition mix, seasonality, or tracking changes. The low-traffic experiment guide explains sample planning and stopping rules.
6. Use a QA matrix before changing live delivery
Run each relevant row on the app versions and platforms you support. Record the actual route, durable state, and emitted events, not just whether the screen looked correct.
| Scenario | Expected result |
|---|---|
| New customer, normal connection | Correct branch reaches first value; one qualifying activation is recorded |
| Back, skip, and answer edit | The next result reflects the confirmed answer or documented default |
| Process ends after a completed operation | Resume recognizes success without duplicating a task, reward, or purchase |
| Offline or slow access lookup | A bounded recovery path appears; unknown access does not become a forced purchase |
| Existing subscriber or restored purchase | Access is resolved through the owning system; restoration is not counted as a new sale |
| Permission denied or later revoked | The app explains the affected capability and preserves usable alternatives |
| Sign-out followed by a different account | Answers, access, and progress belong to the correct customer |
| New flow version during an active session | The chosen resume or migration policy works without a dead-end step |
| Large text, screen reader, and reduced motion | Actions remain understandable and reachable; animation is not required to understand the next step |
Applying the worksheet with Nuxie
Nuxie is a mobile app growth agent that creates, delivers, and improves in-app Experiences. Use the worksheet to describe the customer, desired action, branches, and recovery behavior when preparing an onboarding Experience. Keep app-owned state and operations explicit in the integration.
The iOS identity guide covers anonymous customers, identifying a signed-in account, and resetting on sign-out. The event guide explains recording app actions; your own event names should not use the reserved $ prefix. Follow those platform-specific contracts rather than assuming the example event table is collected automatically.
When measuring results, Nuxie's analytics guide distinguishes Experience presentation metrics from unique-customer Experiment metrics. Match the report's actual denominator to the question you are asking. A purchase-button action, a restored purchase, and a paid transaction are different evidence.
Finally, publish a reviewed version and verify it in the app. Editing the draft does not change the version customers receive; the existing live version remains active while an update builds. Keep the QA matrix and measurement contract beside the brief so the next change can be evaluated against the same intended behavior.