Реалізація walk-through онбординга з пошаговими підсказками в мобільному додатку
Walk-through онбординг — це не тур по додатку. Це контролюване перше знайомство: користувач виконує реальні дії, отримує контекст ровно тоді, коли він потрібен, переходить до наступного кроку лише після виконання поточного. Зробити це технічно правильно складніше, ніж здається.
Архітектура системи онбординга
Головне проектне рішення — ізолювати логіку онбординга від екранів додатку. Найчастіша помилка: розкидані if isOnboardingActive { ... } перевірки по всіх контролерах. Це перетворює кожну зміну онбординга в рефакторинг.
Координатор онбординга. Окремий об'єкт OnboardingCoordinator / OnboardingManager знає поточний крок, управляє показом оверлею та слухає події додатку. Екрани публікують події («користувач натиснув кнопку X», «елемент Y став видимим»), координатор вирішує — переходити до наступного кроку або ні.
На iOS — Combine або NotificationCenter для подій. Координатор підписується на PassthroughSubject<OnboardingEvent, Never>. При виконанні умови кроку — викликає advanceToNextStep().
На Android — ViewModel з SharedFlow<OnboardingEvent>. Фрагменти/Composable функції emit події через viewModel.onboardingEvents.emit(...).
Конфігурація з даних. Кожен крок — структура даних:
struct OnboardingStep {
let id: String
let targetElementId: String // accessibility identifier цільового елемента
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
}
Така структура дозволяє зберігати конфігурацію онбординга у JSON та завантажувати з сервера — A/B тест онбординга без деплою.
Реалізація overlay з highlight
Напівпрозорий overlay з вирізом над цільовим елементом — технична основа walk-through онбординга.
На iOS через UIKit: створюємо UIView на весь екран з альфа 0.7, додаємо в window. Виріз робимо через CAShapeLayer як маску: UIBezierPath(rect: overlayBounds) мінус UIBezierPath(roundedRect: targetFrame, cornerRadius: 8). Маска з fillRule = .evenOdd дає діру потрібної форми.
Координати цільового елемента отримуємо через targetView.convert(targetView.bounds, to: nil) — конвертація у window-координаты. Якщо елемент усередині UIScrollView, додаємо scroll offset: scrollView.convert(targetView.frame, to: nil).
У SwiftUI — Canvas з GraphicsContext.blendMode(.clear) для вирізання, або ZStack з Rectangle().fill(Color.black.opacity(0.7)).mask(...) через GeometryReader + anchorPreference. Другий варіант простіший, але anchorPreference — нетривіальний API, вимагає розуміння preference system SwiftUI.
На Android Compose: Canvas composable з drawRect для тьмяного фону та drawRect з BlendMode.Clear для виріза. Координати target-елемента — через onGloballyPositioned { coordinates -> ... } модифікатор з LocalDensity для переведення у піксели.
Анімація переходу між кроками
При переході до наступного кроку highlight повинен плавно переміщатися до нового елемента. Не миттєво стрибати — саме анімовано переміщатися. На iOS — UIView.animate(withDuration: 0.3) з оновленням CAShapeLayer'я. У SwiftUI — withAnimation(.easeInOut(duration: 0.3)) навколо зміни state.
Якщо наступний крок на іншому екрані — спочатку закриваємо overlay (fade out), виконуємо навігацію, чекаємо viewDidAppear / onAppear та лише потім показуємо overlay для нового кроку (fade in). Не пробуйте анімовати overlay через навігаційний перехід — z-order та coordinate space будуть неправильними.
Управління станом прохідження
Статус онбординга — у UserDefaults / DataStore Preferences. Не просто isOnboardingCompleted: Bool, а completedStepIds: Set<String> — тоді можна додавати нові кроки до існуючого онбординга без скидання прогресу.
При першому запуску після оновлення: якщо додали новий крок — показуємо лише його, не весь онбординг заново. Якщо істотно змінили додаток — onboardingVersion у UserDefaults, при невідповідності версій перезапускаємо онбординг.
Аналітика та оптимізація
Логуємо кожен крок: час початку, час завершення, був ли пропущений. Firebase Analytics event onboarding_step_completed з параметрами step_id, duration_seconds, skipped. Будуємо воронку — де користувачі випадають, там проблема.
Типова знахідка: крок 3 пропускають 60% користувачів — або занадто очевидно, або tooltip перекриває важливий контент на екрані. Друге лікується пересмотром tooltipPosition.
Терміни: 2–3 дні. Базовий walk-through з 3–5 кроками та фіксованою конфігурацією — 2 дні. Динамічна конфігурація з сервера, A/B тестування, аналітика та підтримка кількох платформ — 3 дні.