English 中文TürkçeРусскийFrançaisTiếng ViệtEspañol日本語

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

Warning

Онбординги устарели начиная с Adapty 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" -> {
                // Display paywall from onboarding
                // You would typically fetch and present a new paywall here
                mainUiScope.launch {
                    // Example: Get the flow by placement ID
                    // Adapty.getFlow("your_placement_id").onSuccess { flow ->
                    //     AdaptyUI.createFlowView(flow).onSuccess { view ->
                    //         view.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. Вам нужно управлять тем, что происходит при закрытии онбординга. Например:

Important

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

Если вы используете 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
}
}

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

Tip

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

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


class MyAdaptyUIOnboardingsEventsObserver : AdaptyUIOnboardingsEventsObserver {
    override fun onboardingViewOnPaywallAction(
        view: AdaptyUIOnboardingView,
        meta: AdaptyUIOnboardingMeta,
        actionId: String
    ) {
        // Get the flow using the placement ID from the action
        mainUiScope.launch {
            Adapty.getFlow(placementId = actionId)
                .onSuccess { flow ->
                    AdaptyUI.createFlowView(flow)
                        .onSuccess { view ->
                            view.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
}
}