We often encounter situations where a new user opens an app and doesn't know where to start. Walk-through onboarding isn't a tour of screens—it's a controlled first experience: users perform real actions, receive context precisely when needed, and move to the next step only after completing it. Technically, this is more complex than just showing a few screens. Our experience shows that a quality implementation increases conversion to the target action by 20–40%. In this article, we'll break down how to properly implement walk-through onboarding on iOS and Android using modern frameworks: SwiftUI, Combine, Jetpack Compose, and Kotlin Flow. We'll propose a ready-to-use architecture that easily scales and maintains.
How to Properly Design Onboarding Architecture?
The key design decision is to isolate the onboarding logic from the app's screens. The most common mistake: scattered if isOnboardingActive { ... } checks across all view controllers. This turns every change to onboarding into a refactoring nightmare.
Onboarding Coordinator. A separate object OnboardingCoordinator / OnboardingManager knows the current step, manages overlay display, and listens to app events. Screens publish events ("user tapped button X", "element Y became visible"), and the coordinator decides whether to advance to the next step.
On iOS — use Combine or NotificationCenter for events. The coordinator subscribes to a PassthroughSubject<OnboardingEvent, Never>. When a step condition is met, it calls advanceToNextStep().
On Android — a ViewModel with SharedFlow<OnboardingEvent>. Fragments/Composable functions emit events via viewModel.onboardingEvents.emit(...).
Configuration from Data. Each step is a data structure:
struct OnboardingStep { let id: String let targetElementId: String // accessibility identifier of the target element let highlightShape: HighlightShape // .circle, .rectangle(cornerRadius:) let tooltipText: String let tooltipPosition: TooltipPosition // .above, .below, .auto let completionTrigger: CompletionTrigger // .tap(elementId:), .swipe, .timer(seconds:) let canSkip: Bool } This structure allows storing the onboarding configuration in JSON and loading it from the server—enabling A/B testing without a deployment. Local storage is simpler, but server-side configuration allows A/B tests without releasing a new version, accelerating iteration by 3x.
How to Implement an Overlay with a Cutout?
A semi-transparent overlay with a cutout over the target element is the technical foundation of walk-through onboarding.
On iOS with UIKit: create a UIView covering the entire screen with alpha 0.7, add it to the window. The cutout is made via CAShapeLayer as a mask: UIBezierPath(rect: overlayBounds) minus UIBezierPath(roundedRect: targetFrame, cornerRadius: 8). The mask with fillRule = .evenOdd creates a hole of the desired shape.
Get the target element's coordinates via targetView.convert(targetView.bounds, to: nil)—conversion to window coordinates. If the element is inside a UIScrollView, add the scroll offset: scrollView.convert(targetView.frame, to: nil).
In SwiftUI — use Canvas with GraphicsContext.blendMode(.clear) for the cutout, or a ZStack with Rectangle().fill(Color.black.opacity(0.7)).mask(...) via GeometryReader + anchorPreference. The latter is simpler, but anchorPreference is a non-trivial API requiring understanding of SwiftUI's preference system.
On Android Compose: a Canvas composable with drawRect for the dark background and drawRect with BlendMode.Clear for the cutout. Obtain target element coordinates via the onGloballyPositioned { coordinates -> ... } modifier with LocalDensity for pixel conversion.
| Approach | Platform | Advantages | Disadvantages |
|---|---|---|---|
| UIKit CAShapeLayer | iOS | Simplicity, reliability | Not suitable for SwiftUI |
| SwiftUI Canvas | iOS (SwiftUI) | Works with reuse | More complex, requires blendMode |
| Compose Canvas | Android | Consistent style | Working with views via onGloballyPositioned |
Animation Between Steps
When transitioning to the next step, the highlight should smoothly move to the new element—not jump instantly. On iOS — UIView.animate(withDuration: 0.3) updating the CAShapeLayer. In SwiftUI — withAnimation(.easeInOut(duration: 0.3)) around state changes.
If the next step is on a different screen: first dismiss the overlay (fade out), perform navigation, wait for viewDidAppear / onAppear, and only then show the overlay for the new step (fade in). Do not attempt to animate the overlay through the navigation transition—z-order and coordinate space will be incorrect.
Managing Completion State
Store onboarding status in UserDefaults / DataStore Preferences. Not just isOnboardingCompleted: Bool, but completedStepIds: Set<String>—this allows adding new steps to existing onboarding without resetting progress.
On first launch after an update: if a new step is added, show only that step, not the entire onboarding again. If the app changes significantly—store onboardingVersion in UserDefaults; when versions mismatch, restart the onboarding.
Analytics and Optimization
Log each step: start time, completion time, whether skipped. Use Firebase Analytics event onboarding_step_completed with parameters step_id, duration_seconds, skipped. Build a funnel—where users drop off indicates a problem.
A typical finding: step 3 is skipped by 60% of users—either too obvious or the tooltip blocks important content. The latter is fixed by adjusting tooltipPosition.
What's Included
- Onboarding architecture (coordinator, configuration, storage)
- Overlay implementation with transition animation
- Analytics integration (Firebase, Mixpanel, etc.)
- API and configuration documentation
- Team training and post-launch support
Our team has 5+ years of experience in mobile development and over 50 successful onboarding projects. We guarantee quality implementation using best practices and code review. Contact us to evaluate your project—we'll prepare a commercial proposal within 2 business days.
Timeline: 2–3 days. Basic walk-through with 3–5 steps and fixed configuration—2 days. Dynamic server-side configuration, A/B testing, analytics, and multi-platform support—3 days.