English 中文TürkçeРусскийEspañol日本語Tiếng Việt

Обработка событий онбординга в Kotlin Multiplatform SDK

Онбординги устарели в SDK v4 и будут удалены в одном из следующих релизов. Они больше не получают исправлений и улучшений. Используйте флоу вместо них: в отличие от онбордингов, работающих внутри WebView, флоу рендерятся нативно на устройстве — обеспечивая более плавные анимации, единый нативный внешний вид, быструю загрузку и отсутствие зависимости от WebView. Подробнее читайте в разделах Получение флоу и пейволов и Отображение флоу и пейволов.

Прежде чем начать, убедитесь, что:

  1. Вы установили Adapty Kotlin Multiplatform SDK версии 3.15.0 или выше.
  2. Вы создали онбординг.
  3. Вы добавили онбординг в плейсмент.

Онбординги, настроенные в билдере, генерируют события, на которые ваше приложение может реагировать. Ниже описано, как с ними работать.

Настройка обозревателя событий онбординга

Чтобы обрабатывать события онбординга, нужно реализовать интерфейс AdaptyUIOnboardingsEventsObserver и зарегистрировать его через AdaptyUI.setOnboardingsEventsObserver(). Это следует делать на ранних этапах жизненного цикла приложения — как правило, в главной activity или при инициализации приложения.


// In your app initialization
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())

Пользовательские действия

В конструкторе вы можете добавить к кнопке действие custom и назначить ему идентификатор. Затем этот идентификатор можно использовать в коде и обрабатывать как пользовательское действие.

ios-events-1.webp

Например, если пользователь нажимает кастомную кнопку — Login или Allow notifications — вызывается метод делегата onCustomAction с идентификатором действия из билдера. Идентификаторы задаёте вы сами, например "allowNotifications".


class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewOnCustomAction(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta,
        actionId: String
    ) {
        when (actionId) {
            "openPaywall" -> {
                // Показ пейвола из онбординга
                // Обычно здесь нужно получить и отобразить новый пейвол
                mainUiScope.launch {
                    // Пример: получение пейвола по ID плейсмента
                    // val paywallResult = Adapty.getPaywall("your_placement_id")
                    // paywallResult.onSuccess { paywall ->
                    //     val paywallViewResult = AdaptyUI.createPaywallView(paywall)
                    //     paywallViewResult.onSuccess { paywallView ->
                    //         paywallView.present()
                    //     }
                    // }
                }
            }
            "allowNotifications" -> {
                // Обработка разрешений на уведомления
            }
            else -> {
                // Обработка других пользовательских действий
            }
        }
    }
}

// Настройка наблюдателя
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())
Пример события (нажмите, чтобы развернуть)
{
    "actionId": "allowNotifications",
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
}
}

Закрытие онбординга

Онбординг считается закрытым, когда пользователь нажимает кнопку с назначенным действием Close. Вам нужно управлять тем, что происходит при закрытии онбординга. Например:

Вам нужно управлять тем, что происходит при закрытии онбординга. Например, нужно прекратить отображение самого онбординга.

Если вы используете createNativeOnboardingView, view.isStandaloneView имеет значение false — реализация по умолчанию не вызывает view.dismiss(). Вместо этого удалите представление из разметки и вызовите dispose() в данном колбэке.


class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewOnCloseAction(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta,
        actionId: String
    ) {
        // Dismiss the onboarding screen
        mainUiScope.launch {
            view.dismiss()
        }

        // Additional cleanup or navigation logic can be added here
        // For example, navigate back or show main app content
    }
}

// Set up the observer
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())
Пример события (нажмите, чтобы развернуть)
{
    "action_id": "close_button",
    "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
}
}

Открытие пейвола

Обработайте это событие, чтобы открыть пейвол внутри онбординга. Если вы хотите открыть пейвол после его закрытия, есть более простой способ — обработайте onboardingViewOnCloseAction и откройте пейвол, не опираясь на данные события.

Самый удобный подход — задать ID действия равным ID плейсмента пейвола. Тогда можно сразу использовать ID плейсмента, чтобы получить и открыть нужный пейвол:


class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewOnPaywallAction(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta,
        actionId: String
    ) {
        // Get the paywall using the placement ID from the action
        mainUiScope.launch {
            val paywallResult = Adapty.getPaywall(placementId = actionId)
            paywallResult.onSuccess { paywall ->
                val paywallViewResult = AdaptyUI.createPaywallView(paywall)
                paywallViewResult.onSuccess { paywallView ->
                    paywallView.present()
                }.onError { error ->
                    // handle the error
                }
            }.onError { error ->
                // handle the error
            }
        }
    }
}

// Set up the observer
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())
Пример события (нажмите, чтобы развернуть)
{
    "action_id": "premium_offer_1",
    "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "pricing_screen",
    "screen_index": 2,
    "total_screens": 4
}
}

Завершение загрузки онбординга

Когда онбординг завершает загрузку, вызывается этот метод:


class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewDidFinishLoading(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta
    ) {
        // Handle loading completion
        // You can add any initialization logic here
    }
}

// Set up the observer
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())
Пример события (нажмите, чтобы развернуть)
{
    "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "welcome_screen",
    "screen_index": 0,
    "total_screens": 4
}
}

Метод onboardingViewOnAnalyticsEvent вызывается при возникновении различных аналитических событий во время флоу онбординга. Объект event может быть одного из следующих типов:

ТипОписание
AdaptyOnboardingsAnalyticsEventOnboardingStartedОнбординг загружен
AdaptyOnboardingsAnalyticsEventScreenPresentedПоказан любой экран
AdaptyOnboardingsAnalyticsEventScreenCompletedЭкран завершён. Включает необязательный elementId (идентификатор завершённого элемента) и необязательный reply (ответ пользователя). Срабатывает, когда пользователь выполняет любое действие для выхода с экрана.
AdaptyOnboardingsAnalyticsEventSecondScreenPresentedПоказан второй экран
AdaptyOnboardingsAnalyticsEventUserEmailCollectedСрабатывает, когда email пользователя собран через поле ввода
AdaptyOnboardingsAnalyticsEventOnboardingCompletedСрабатывает, когда пользователь достигает экрана с идентификатором final. Если вам нужно это событие, присвойте идентификатор final последнему экрану.
AdaptyOnboardingsAnalyticsEventUnknownДля любого нераспознанного типа события. Включает name (название неизвестного события) и meta (дополнительные метаданные)
Каждое событие содержит мета-информацию meta со следующими полями:
ПолеОписание
onboardingIdУникальный идентификатор флоу онбординга
screenClientIdИдентификатор текущего экрана
screenIndexПозиция текущего экрана во флоу
screensTotalОбщее количество экранов во флоу

Вот пример того, как можно использовать события аналитики для отслеживания:


class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewOnAnalyticsEvent(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta,
        event: AdaptyOnboardingsAnalyticsEvent
    ) {
        when (event) {
            is AdaptyOnboardingsAnalyticsEventOnboardingStarted -> {
                // Track onboarding start
                trackEvent("onboarding_started", event.meta)
            }
            is AdaptyOnboardingsAnalyticsEventScreenPresented -> {
                // Track screen presentation
                trackEvent("screen_presented", event.meta)
            }
            is AdaptyOnboardingsAnalyticsEventScreenCompleted -> {
                // Track screen completion with user response
                trackEvent("screen_completed", event.meta, event.elementId, event.reply)
            }
            is AdaptyOnboardingsAnalyticsEventOnboardingCompleted -> {
                // Track successful onboarding completion
                trackEvent("onboarding_completed", event.meta)
            }
            is AdaptyOnboardingsAnalyticsEventUnknown -> {
                // Handle unknown events
                trackEvent(event.name, event.meta)
            }
            // Handle other cases as needed
        }
    }

    private fun trackEvent(eventName: String, meta: AdaptyUIOnboardingMeta, elementId: String? = null, reply: String? = null) {
        // Implement your analytics tracking here
        // For example, send to your analytics service
    }
}

// Set up the observer
AdaptyUI.setOnboardingsEventsObserver(MyAdaptyUIOnboardingsEventsObserver())
Примеры событий (нажмите, чтобы развернуть)
// OnboardingStarted
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "welcome_screen",
    "screenIndex": 0,
    "screensTotal": 4
}
}

// ScreenPresented
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "interests_screen",
    "screenIndex": 2,
    "screensTotal": 4
}
}

// ScreenCompleted
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 1,
    "screensTotal": 4
},
    "elementId": "profile_form",
    "reply": "success"
}

// SecondScreenPresented
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 1,
    "screensTotal": 4
}
}

// UserEmailCollected
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 1,
    "screensTotal": 4
}
}

// OnboardingCompleted
{
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "final_screen",
    "screenIndex": 3,
    "screensTotal": 4
}
}