Onboarding

You download a new fitness app. Before you can log a single workout, it shows you three slides, asks your name and goal, and wants to send you notifications. That’s onboarding: everything an app shows a new user the first time, to explain its value and set it up.

Onboarding is only seen once (if it works), so it’s easy for a team to forget about it. But it’s also the first impression. If it crashes, loops, or forces a long-time customer through it again after an update, people give up before they ever reach the main app. Many apps lose a large share of new users in the first few minutes, and onboarding bugs are a big reason why.

How it works

Kinds of onboarding

• Skip

  Welcome carousel

  A few swipeable slides about the benefits. Easy to build, easy to skip.

• Swipe left to delete

  Interactive tutorial

  The user learns by doing: "Swipe left to delete this sample task."

• Tap + to log your first workout

  Contextual tips

  Small hints that appear the first time you reach a feature (coach marks, tooltips).

• No workouts yetLog your first one

  Empty-state onboarding

  An empty screen that teaches: "No workouts yet. Log your first one."

• STEP 2 OF 3BeginnerIntermediateAdvanced

  Setup wizard

  A few required steps (account, goal, preferences) with progress and Back.

• Welcome carousel. Two to five slides with a picture and a sentence each, plus Skip and Next (see Carousel). The most common, and the most skipped.
• Interactive tutorial. The user practices on sample data: “Swipe this task to delete it.” Great for apps with gestures people wouldn’t discover alone.
• Progressive or contextual tips. Small hints (coach marks, tooltips) that appear the first time the user reaches a feature, not all at once at the start.
• Empty-state onboarding. An empty stateEmpty stateThe screen a user sees when there is no content yet, like an empty cart or no search results.Open in glossary → that teaches: “No workouts yet. Tap + to log your first one.” Free onboarding on screens that would otherwise be blank (see Empty and error states).
• Account setup wizard. Required steps such as creating an account, choosing a goal or a home address. Unlike a carousel, these collect data the app needs.

The first-run flow

First-run detection: when should onboarding appear?

This is the most common source of onboarding bugs. The right answer depends on where the flag lives, so ask your team and test each row:

Situation	Usually expected	Why it breaks
First launch after install	Onboarding	No flag yet
Restart, or phone restart	Straight to Home	Flag not saved, or saved too late
App update	Home, maybe a short “What’s new”	Flag tied to the app version, or wiped by a data migration
Reinstall	Onboarding again (often), or log in	iOS Keychain and Android Auto Backup can bring old data back
Log out, then log in	Login screen, then Home	Logout clears the device flag too
Same account on a new phone	Login, no full tour	Flag only stored on the old device

Read Install, update and uninstall for how app data survives (or doesn’t) these events. On Android, Auto BackupAuto BackupAn Android feature that backs up app data to the user's Google account and can restore it on reinstall.Open in glossary → can restore the flag after a reinstall; on iOS, data in the keychainKeychainiOS secure storage for small secrets like tokens and passwords; items can survive uninstalling the app.Open in glossary → can survive an uninstall. Both surprise teams regularly.

Skip, Back and progress

• Skip should skip only what’s optional. Skipping the welcome slides is fine; skipping the account setup leaves the app without the data it needs. If something is required, Skip must not jump over it, or the app must handle the missing data gracefully.
• Back should go one step back and keep what the user already chose. Losing your answers because you pressed Back is one of the most annoying bugs there is.
• Progress indicators (dots, “Step 2 of 3”, a bar) must match the real number of steps. A fifth dot that never fills makes people think they’re stuck.
• The system Back button and back gesture on Android must behave like the on-screen Back, and must not close the app in the middle of setup without warning.

Permission priming: ask in context

For every permission type, the system dialogs and what happens after each answer, see App Permissions.

Many onboarding flows ask for permissions: notifications, location, camera, Health data. Both iOS and Android only let an app show the system permission dialog a limited number of times (on iOS just once). If the user says no, the app can’t ask again; only system Settings can change it.

That’s why good apps use permission primingPermission primingExplaining in the app why a permission is needed, at the right moment, before the system dialog.Open in glossary →: they first explain why in their own screen (or a modalModalA window that appears on top of the page and blocks the content behind it until it is closed.Open in glossary →, see Modal), at the moment it makes sense, and only then trigger the system dialog.

Things to test around permissions:

• The system dialog appears only after the explanation, never on launch.
• Not now doesn’t trigger the system dialog, so the app can still ask later.
• After Don’t Allow, the app keeps working, and offers a way back: a short explanation plus a button that opens the app’s page in system Settings.
• The app notices when the user turns the permission on in Settings and comes back.

The Push notifications lesson covers the notification permission in detail.

Personalization steps

Setup wizards often ask questions that shape the app: goal, level, interests, home city, preferred language. Test that:

• Every answer is really used afterwards (the plan matches the goal, the feed matches the interests).
• Answers can be changed later in Settings, and changing them has the same effect.
• Required questions are validated (no empty name, at least one day), and optional ones can really be left empty.
• Answers are saved to the account, so they’re still there on a new phone or after a reinstall and login.

Onboarding on the web

Websites use the same ideas: a welcome modal, a product tour with tooltips that point at buttons (“This is where you create a project”), checklists like “3 of 5 steps done”, and empty states. The “already seen” flag is usually stored in a cookieCookieA small piece of data a website stores in your browser, for example to keep you logged in.Open in glossary → or local storageLocal storageBrowser storage where websites keep data that survives closing the tab, like settings or a cart.Open in glossary →, or on the server for logged-in users. So test:

• A private/incognito window and clearing site data: does the tour come back? (Fine for visitors, annoying for logged-in users if the flag should be on the account.)
• A second browser or computer with the same account.
• Tooltips on small screens: does the tour point at a button that’s hidden in a menu on mobile? Does it go off-screen?
• Keyboard and screen readers: can you reach Next and Close with Tab, and does Esc close the tour?

Example requirements

What usually goes wrong

#	Bug	What you see	Typical severity
1	Onboarding comes back	Shown on every launch, or again after an update for existing users	High
2	Skip skips too much	Required setup skipped, app in a broken state (“Hi, undefined”)	High
3	Back loses data	Back jumps to the start and clears all choices	Medium
4	Wrong progress	4 dots for 3 slides, “Step 3 of 2”	Low
5	Permission asked too early	System dialog before any explanation; no recovery after “Don’t Allow”	High (business)
6	Text cut off	Slides unreadable with large text or in German	Medium–High
7	Interruption breaks the flow	A phone call or rotation sends the user back to step 1	Medium
8	Answers not used	Chose “Beginner”, got an advanced plan	Medium
9	Missing or duplicate analytics	onboarding_completed never fires, or fires twice	Medium
10	Not accessible	Carousel only works by swiping; screen reader can’t reach Skip	High (for affected users)

Find the bug

Pulse, a fitness app, has a first-run onboarding with six bugs. Use the device controls to restart, update, reinstall and log out, and watch what the app stores on the device. Try this:

• Read the system dialog that appears at launch. Was it explained? Deny it, then look for a way back.
• Count the slides and the dots.
• Tap Skip (then Reinstall to start over).
• Fill in setup, go forward to step 3, then press Back.
• Finish onboarding, then Restart, Update and Log out.
• Turn on Larger text and look at every screen.

🐞 Bug hunt: Pulse onboarding

This demo has 6 hidden bugs. Explore it like a tester, then check your findings.

Found0/6

9:41

Skip

Track every workout

Log runs, rides and gym sessions in one place. Pulse adds up your weekly minutes for you.

Next

“Pulse” Would Like to Send You Notifications

Notifications may include alerts, sounds, and icon badges. These can be configured in Settings.

Don’t AllowAllow

Device

Restart app Update app Reinstall Log out

Larger text (accessibility)

App storage on device

• app_version = 2.3.0
• session = —
• notification permission = not asked yet

From the spec

• Onboarding shows once, on the first launch after install.
• Skip skips the intro slides. Setup (name, goal, level, days) is required.
• Explain reminders before asking for notification permission.
• Text must stay readable with the largest text sizes.

1. 1

   Hint: Finish onboarding, tap Restart (fine), then tap Update app.

   Onboarding shows again after an app update

   Restart correctly goes to Home, but after updating to 2.4.0 a logged-in user sees the whole onboarding again. The storage panel shows why: the flag is saved as onboarding_done_v2.3.0, tied to the app version. Expected: existing users go straight to Home (at most a short "What's new").

   Reveal answer✓ I found this
2. 2

   Hint: On a fresh install, tap Skip on the first slide.

   Skip jumps over the required setup

   Skip marks onboarding as done and logs the user in without a name, goal or plan. Home says "Hi, undefined", the plan is "undefined · undefined", and Start today's workout fails with plan_not_found. There is no way back to setup. Expected: Skip skips the slides only and leads to setup.

   Reveal answer✓ I found this
3. 3

   Hint: Tap Next until the last slide and look at the dots.

   Progress dots show 4 pages for 3 slides

   There are three slides, but four dots. On the last slide ("Get started") the fourth dot is still empty, so it looks like there's one more page. Screen readers announce "Page 3 of 4" too. Expected: the number of dots matches the number of slides.

   Reveal answer✓ I found this
4. 4

   Hint: Fill in steps 1 and 2, go to step 3, then press Back.

   Back on step 3 jumps to step 1 and clears every choice

   Back on step 2 correctly returns to step 1 with the answers kept. Back on step 3 jumps straight to step 1 and empties the name, goal, level and days. Expected: Back goes to step 2 and keeps all answers.

   Reveal answer✓ I found this
5. 5

   Hint: Look at the very first screen after install. Tap "Don't Allow", finish setup, then tap "Turn on reminders".

   Permission asked on launch, and no recovery after denial

   The system notification dialog appears before the user knows what the app does or why it wants to send notifications. After Don't Allow, the Reminders step offers "Turn on reminders", but iOS won't show the dialog a second time, and the app shows nothing: no explanation, no link to Settings. Expected: ask on the Reminders step after the explanation; after a denial, explain how to enable it in Settings and link there.

   Reveal answer✓ I found this
6. 6

   Hint: Turn on Larger text and look at the welcome slides.

   Carousel text is cut off with larger text

   The slide text sits in a fixed-height box with hidden overflow, so with large text the description is cut off mid-sentence (setup screens scroll correctly). People who need large text can't read what the app is about. Expected: the text box grows or scrolls, nothing is clipped.

   Reveal answer✓ I found this

Test scenarios

Functional

• Fresh install: onboarding appears, every slide and step can be completed, and the user lands on Home.
• Next, Back and Skip do exactly what the spec says on every screen.
• Every answer from setup is saved and used (plan, name, reminders).
• Completing onboarding sets the flag: restarting goes to Home.
• Permission is asked in context, and both Allow and Don’t Allow lead to a working app.

Install, update, reinstall and logout

This is where onboarding bugs hide, so it deserves its own group. It’s also part of upgrade testingUpgrade testingChecking that updating from an older app version keeps the user's data and settings working.Open in glossary →:

• Restart the app and the phone after finishing onboarding: no onboarding.
• Update from the previous version (install the old build, finish onboarding, then install the new build over it): no onboarding.
• Kill the app halfway through onboarding, then open it: it continues or restarts cleanly, never half-broken.
• Reinstall: check what the team expects (onboarding or login), especially with iOS Keychain and Android Auto Backup.
• Log out and log in, and log in as a different user on the same device.
• Same account on a second device.

Negative

• Required fields empty or invalid: Continue is disabled or shows a clear error messageError messageText that tells the user something went wrong and, ideally, how to fix it.Open in glossary →.
• Skip on every screen: nothing required is skipped.
• Deny every permission: the app still works and explains how to enable it later.
• No internet during setup: the answers aren’t lost, and there’s a clear retry.

Edge cases and interruptions

• InterruptionsInterruptionAnything that takes the user away from the app mid-task: a call, an alarm, a notification, low battery.Open in glossary →: a phone call, a notification, switching apps, locking the phone in the middle of step 2. Coming back, the user is on the same step with the same answers.
• Rotation (orientationOrientationWhether the device is held upright (portrait) or sideways (landscape).Open in glossary →) and split screen: the step and the answers stay. On Android this is a configuration changeConfiguration changeAn Android event like rotation, folding, dark mode, font size or language that recreates the screen by default.Open in glossary → that can reset screens.
• Double tap on Next or Get started: no skipped steps, no double account.
• Very long names, emoji and accents (Zoë, José).
• Dark mode: illustrations and text stay visible.

UI & usability

• The whole flow is short (ideally under a minute) and every slide says something useful.
• Skip and Back are easy to find; the progress indicator matches the real number of steps.
• Swiping works on the carousel, and there are buttons for people who don’t swipe.
• Nothing is cut off on small phones, with the keyboard open, or in other languagesLocalizationAdapting an app to a language and region, including translations, dates, currency and layout.Open in glossary → (German text is often 30% longer).

Accessibility

• With a screen readerScreen readerSoftware that reads the screen aloud for blind and low-vision users, like VoiceOver or TalkBack.Open in glossary → (VoiceOver, TalkBack), every slide is read, buttons have names, and the carousel can be moved without swiping (“Page 2 of 3”).
• Large textDynamic TypeThe phone setting that lets users make text bigger or smaller across apps.Open in glossary → (iOS Dynamic Type, Android font size): nothing is clipped, buttons stay reachable (scrolling is fine).
• Auto-advancing carousels can be paused, or don’t auto-advance at all.
• Animations respect Reduce Motion (iOS) and Remove animations (Android).
• On the web: keyboard only, a visible focus ring, a logical focus orderFocus orderThe order in which the Tab key moves through interactive elements.Open in glossary →, and Esc closes a tour.

Analytics

Product teams measure onboarding closely (“how many people finish step 2?”). Check with your developers or an analytics debug view that:

• Each event (onboarding_started, onboarding_step_viewed, onboarding_skipped, onboarding_completed) fires once, at the right moment, with the right step number.
• No personal data (like the name the user typed) is sent in the events.

Example test cases

Mobile vs web

Mobile appWebsite

• Where the flag lives: on iOS, simple settings are deleted on uninstall, but the Keychain can survive. Android stores them in app data, which Auto Backup may restore after a reinstall. Test reinstall on both, and ask the team what’s expected.
  Dev note

  iOS stores simple settings in UserDefaults.
• Updates: install the previous build from TestFlight, Firebase App Distribution or the store, complete onboarding, then update. Repeat for a jump of several versions.
• Permissions: iOS shows each system dialog once; Android 11+ stops asking after two denials (see App Permissions). Test Allow, Don’t Allow and “Allow once” (location and camera on newer OS versions).
• System Back (Android): must go one step back in setup, not quit the app or skip ahead.
• Text size and display size: iOS Dynamic Type including the extra accessibility sizes; Android font size and display size.
• Tablets and foldables: the carousel images and buttons still look right in landscape and on large screens.

• Where the flag lives: a cookie, localStorage, or the user’s account on the server. Test incognito windows, clearing site data and a second browser.
• Product tours: tooltips must point at the right element at every breakpointBreakpointA screen width where a responsive layout changes, for example from one column to two.Open in glossary →. On a phone, the target may be hidden in a menu.
• Modals: a welcome modal needs a visible close button, Esc to close, and a focus trapFocus trapKeeping keyboard focus inside an open modal so users can't tab into the hidden page behind it.Open in glossary → while it’s open.
• Browser permissions: location or notification prompts should follow a click on an explaining button, not appear on page load (some browsers block or hide prompts that appear without a click).
• Logged-out vs logged-in: a tour for visitors shouldn’t reappear for a customer who already finished it on another device.
• Keyboard and screen readers: the whole tour works without a mouse.

Checklist

Onboarding checklist

0 of 12 checked

Copy

• Onboarding appears on the first launch after install
• Restart, phone restart and app update go straight to Home
• Reinstall, logout and a second device behave as the team expects
• Skip skips only optional parts; required setup cannot be bypassed
• Back goes one step back and keeps every answer
• Progress dots or "Step X of Y" match the real number of steps
• Permissions are asked in context after an explanation; denial has a recovery path
• Answers are saved to the account and actually used
• Interruptions and rotation keep the current step and answers
• Readable with the largest text size and in long languages like German
• Works with VoiceOver/TalkBack and (web) keyboard only
• Analytics events fire once each, without personal data

Check your understanding

Quick quiz

0/5 answered · 0 correct

1. 1.After updating the app, existing users see the welcome slides again. What is the most likely cause?

   AThe users cleared their cacheBThe "onboarding done" flag is tied to the app version or was lost in the updateCThe server is downDIt is expected after every update

2. 2.Which is the best moment to ask for notification permission in a fitness app?

   AOn the very first screenBRight after the user chooses workout days, with an explanation firstCNever, notifications are on by default everywhereDAfter the user deletes the app

3. 3.The user taps Skip on the welcome carousel and lands on Home with "Hi, undefined". What kind of bug is it?

   AA cosmetic typoBSkip bypassed required setup and left the app in a broken stateCA performance bugDExpected behavior

4. 4.On iOS the user tapped "Don't Allow" for notifications. What should the app do when they later tap "Turn on reminders"?

   AShow the system dialog againBExplain that reminders are off and open the app's page in SettingsCDo nothingDRestart the onboarding

5. 5.Which of these is NOT a typical onboarding test?

   AReinstall the app and check whether onboarding appearsBGo through onboarding with the largest text sizeCMeasure the server CPU during checkoutDGet a phone call during setup and come back

Key takeaways

• Onboarding is the first impression: carousels, interactive tutorials, contextual tips, empty states and setup wizards.
• The biggest risk is first-run detection: test install, restart, update, reinstall, logout and a second device.
• Skip must never skip required setup; Back must keep answers; progress indicators must match the real steps.
• Ask for permissions in context after an explanation, and always offer a way back after a denial.
• Test with interruptions, rotation, large text, screen readers and other languages, and check the analytics events.