Gérer les événements d'onboarding dans le SDK Kotlin Multiplatform

Warning

Les onboardings sont dépréciés à partir du SDK Adapty v4. Créez des flows à la place : contrairement aux onboardings, qui s’exécutent dans une WebView, les flows s’affichent nativement sur l’appareil — animations plus fluides, aspect natif cohérent, temps de chargement réduits et aucune dépendance à l’environnement WebView.

Avant de commencer, assurez-vous que :

Vous avez installé le SDK Adapty Kotlin Multiplatform 3.15.0 ou version ultérieure.
Vous avez créé un onboarding.
Vous avez ajouté l’onboarding à un placement.

Les onboardings configurés avec le builder génèrent des événements auxquels votre application peut réagir. Découvrez ci-dessous comment y répondre.

Configurer l’observateur d’événements d’onboarding

Pour gérer les événements d’onboarding, vous devez implémenter l’interface AdaptyUIOnboardingsEventsObserver et la configurer avec AdaptyUI.setOnboardingsEventsObserver(). Cette opération doit être effectuée tôt dans le cycle de vie de votre application, généralement dans votre activité principale ou lors de l’initialisation de l’application.


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

Actions personnalisées

Dans le builder, vous pouvez ajouter une action personnalisée à un bouton et lui attribuer un ID. Vous pouvez ensuite utiliser cet ID dans votre code et le gérer comme une action personnalisée.

Par exemple, si un utilisateur appuie sur un bouton personnalisé, comme Login ou Allow notifications, la méthode delegate onCustomAction sera déclenchée avec l’ID d’action défini dans le builder. Vous pouvez créer vos propres IDs, comme “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())

Exemple d’événement (cliquez pour développer)

{
    "actionId": "allowNotifications",
    "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
}
}

Fermeture de l’onboarding

L’onboarding est considéré comme fermé lorsqu’un utilisateur appuie sur un bouton auquel l’action Close est assignée. Vous devez gérer ce qui se passe lorsqu’un utilisateur ferme l’onboarding. Par exemple :

Important

Vous devez gérer ce qui se passe lorsqu’un utilisateur ferme l’onboarding. Par exemple, vous devez arrêter d’afficher l’onboarding lui-même.

Si vous utilisez createNativeOnboardingView, view.isStandaloneView est false — l’implémentation par défaut n’appelle pas view.dismiss(). Retirez la vue de votre layout et appelez dispose() sur celle-ci dans ce callback à la place.


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())

Exemple d’événement (Cliquez pour développer)

{
    "action_id": "close_button",
    "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
}
}

Ouvrir un paywall

Tip

Gérez cet événement pour ouvrir un paywall si vous souhaitez l’ouvrir à l’intérieur de l’onboarding. Si vous voulez ouvrir un paywall après sa fermeture, il existe une méthode plus directe : gérez onboardingViewOnCloseAction et ouvrez un paywall sans vous appuyer sur les données de l’événement.

La façon la plus fluide de travailler avec les paywalls dans les onboardings est de définir l’ID d’action égal à l’ID de placement d’un paywall. Ainsi, vous pouvez utiliser l’ID de placement pour récupérer et ouvrir le paywall directement :


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())

Exemple d’événement (Cliquez pour développer)

{
    "action_id": "premium_offer_1",
    "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "pricing_screen",
    "screen_index": 2,
    "total_screens": 4
}
}

Fin du chargement de l’onboarding

Lorsqu’un onboarding finit de se charger, cette méthode est invoquée :


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())

Exemple d’événement (cliquez pour développer)

{
    "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "welcome_screen",
    "screen_index": 0,
    "total_screens": 4
}
}

La méthode onboardingViewOnAnalyticsEvent est appelée lors de divers événements analytiques survenant pendant le flow d’onboarding.

L’objet event peut être de l’un des types suivants :

Type	Description
`AdaptyOnboardingsAnalyticsEventOnboardingStarted`	Lorsque l’onboarding a été chargé
`AdaptyOnboardingsAnalyticsEventScreenPresented`	Lorsqu’un écran est affiché
`AdaptyOnboardingsAnalyticsEventScreenCompleted`	Lorsqu’un écran est complété. Comprend un `elementId` optionnel (identifiant de l’élément complété) et un `reply` optionnel (réponse de l’utilisateur). Déclenché lorsque l’utilisateur effectue une action pour quitter l’écran.
`AdaptyOnboardingsAnalyticsEventSecondScreenPresented`	Lorsque le deuxième écran est affiché
`AdaptyOnboardingsAnalyticsEventUserEmailCollected`	Déclenché lorsque l’adresse e-mail de l’utilisateur est collectée via le champ de saisie
`AdaptyOnboardingsAnalyticsEventOnboardingCompleted`	Déclenché lorsqu’un utilisateur atteint un écran avec l’ID `final`. Si vous avez besoin de cet événement, attribuez l’ID `final` au dernier écran.
`AdaptyOnboardingsAnalyticsEventUnknown`	Pour tout type d’événement non reconnu. Comprend `name` (le nom de l’événement inconnu) et `meta` (métadonnées supplémentaires)

Chaque événement inclut des informations meta contenant :

Champ	Description
`onboardingId`	Identifiant unique du flow d’onboarding
`screenClientId`	Identifiant de l’écran actuel
`screenIndex`	Position de l’écran actuel dans le flow
`screensTotal`	Nombre total d’écrans dans le flow

Voici un exemple d’utilisation des événements d’analytics pour le tracking :


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())

Exemples d’événements (Cliquez pour développer)

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

Gérer les événements d'onboarding dans le SDK Kotlin Multiplatform

Configurer l’observateur d’événements d’onboarding

Actions personnalisées

Fermeture de l’onboarding

Ouvrir un paywall

Fin du chargement de l’onboarding

Événements de navigation