Реализация 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 дня.