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

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

  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" -> {
                // Display paywall from onboarding
                // You would typically fetch and present a new paywall here
                mainUiScope.launch {
                    // Example: Get paywall by placement ID
                    // val paywallResult = Adapty.getPaywall("your_placement_id")
                    // paywallResult.onSuccess { paywall ->
                    //     val paywallViewResult = AdaptyUI.createPaywallView(paywall)
                    //     paywallViewResult.onSuccess { paywallView ->
                    //         paywallView.present()
                    //     }
                    // }
                }
            }
            "allowNotifications" -> {
                // Handle notification permissions
            }
            else -> {
                // Handle other custom actions
            }
        }
    }
}

// Set up the observer
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 и откройте пейвол без привязки к данным события.

Если пользователь нажимает кнопку, открывающую пейвол, вы получите идентификатор действия кнопки, который вы задали вручную. Удобнее всего сделать идентификатор действия равным идентификатору плейсмента пейвола — тогда по нему сразу можно получить и открыть пейвол:


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
}
}