Gestionar eventos de onboarding en el SDK de Kotlin Multiplatform

Antes de empezar, asegúrate de que:

1. Tienes instalado el SDK de Adapty para Kotlin Multiplatform 3.15.0 o posterior.
2. Has creado un onboarding.
3. Has añadido el onboarding a un placement.

Los onboardings configurados con el builder generan eventos a los que tu app puede responder. Aprende cómo hacerlo a continuación.

Configurar el observador de eventos del onboarding

Para gestionar los eventos del onboarding, necesitas implementar la interfaz AdaptyUIOnboardingsEventsObserver y configurarla con AdaptyUI.setOnboardingsEventsObserver(). Esto debe hacerse en una etapa temprana del ciclo de vida de tu app, normalmente en tu actividad principal o en la inicialización de la app.

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

Acciones personalizadas

En el builder, puedes añadir una acción personalizada a un botón y asignarle un ID. Luego, puedes usar ese ID en tu código y gestionarlo como una acción personalizada.

Por ejemplo, si un usuario pulsa un botón personalizado, como Login o Allow notifications, el método delegado onCustomAction se activará con el ID de acción del builder. Puedes crear tus propios IDs, como “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
}
}

Cierre del onboarding

El onboarding se considera cerrado cuando el usuario pulsa un botón con la acción Close asignada. Debes gestionar qué ocurre cuando el usuario cierra el onboarding. Por ejemplo:

Si usas createNativeOnboardingView, view.isStandaloneView es false — la implementación por defecto no llama a view.dismiss(). En su lugar, elimina la vista de tu layout y llama a dispose() en este callback.

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

Abrir un paywall

La forma más sencilla de trabajar con paywalls en onboardings es hacer que el ID de acción coincida con el ID de placement del paywall. Así puedes usar el ID de placement para obtener y abrir el paywall directamente:

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

Finalizar la carga del onboarding

Cuando un onboarding termina de cargarse, se invocará este método:

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

Eventos de navegación

El método onboardingViewOnAnalyticsEvent se llama cuando ocurren distintos eventos de analítica durante el flow de onboarding. El objeto event puede ser uno de los siguientes tipos:

A continuación, un ejemplo de cómo usar los eventos de análisis para el seguimiento:

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