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

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 Android Adapty 3.8.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épondre. Découvrez ci-dessous comment y répondre.

Pour contrôler ou surveiller les processus qui se déroulent sur l’écran d’onboarding dans votre application Android, implémentez l’interface AdaptyOnboardingEventListener.

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 déléguée onCustomAction sera déclenchée avec l’ID d’action défini dans le builder. Vous pouvez créer vos propres IDs, par exemple “allowNotifications”.

class YourActivity : AppCompatActivity() {
    private val eventListener = object : AdaptyOnboardingEventListener {
        override fun onCustomAction(action: AdaptyOnboardingCustomAction, context: Context) {
            when (action.actionId) {
                "allowNotifications" -> {
                    // Request notification permissions
                }
            }
        }
        
        override fun onError(error: AdaptyOnboardingError, context: Context) {
            // Handle errors
        }
        
        // ... other required delegate methods
    }
}

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

{
  "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.

Par exemple :

override fun onCloseAction(action: AdaptyOnboardingCloseAction, context: Context) {
    // Dismiss the onboarding screen
    (context as? Activity)?.onBackPressed()
}

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

Ouverture d’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 AdaptyOnboardingCloseAction 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’identifiant d’action égal à l’identifiant de placement du paywall. Ainsi, après l’événement AdaptyOnboardingOpenPaywallAction, vous pouvez utiliser l’identifiant de placement pour récupérer et ouvrir le paywall directement :

override fun onOpenPaywallAction(action: AdaptyOnboardingOpenPaywallAction, context: Context) {
    // Get the paywall using the placement ID from the action
    Adapty.getPaywall(placementId = action.actionId) { result ->
        when (result) {
            is AdaptyResult.Success -> {
                val paywall = result.value
                // Get the paywall configuration
                AdaptyUI.getViewConfiguration(paywall) { result ->
                    when(result) {
                        is AdaptyResult.Success -> {
                            val paywallConfig = result.value
                            // Create and present the paywall
                            val paywallView = AdaptyUI.getPaywallView(
                                activity = this,
                                viewConfig = paywallConfig,
                                products,
                                eventListener = paywallEventListener
                            )
                            // Add the paywall view to your layout
                            binding.container.addView(paywallView)
                        }
                        is AdaptyResult.Error -> {
                            val error = result.error
                            // handle the error
                        }
                    }
                }
            is AdaptyResult.Error -> {
                val error = result.error
                // handle the error
            }        
        }
    }
}

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 termine son chargement, cette méthode est invoquée :

override fun onFinishLoading(action: AdaptyOnboardingLoadedAction, context: Context) {
    // Handle loading completion
}

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 onAnalyticsEvent est appelée lors de différents événements analytiques survenant au cours du flow d’onboarding.

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

Type	Description
`OnboardingStarted`	Lorsque l’onboarding a été chargé
`ScreenPresented`	Lorsqu’un écran est affiché
`ScreenCompleted`	Lorsqu’un écran est complété. Inclut 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.
`SecondScreenPresented`	Lorsque le deuxième écran est affiché
`UserEmailCollected`	Déclenché lorsque l’adresse e-mail de l’utilisateur est collectée via le champ de saisie
`OnboardingCompleted`	Déclenché lorsqu’un utilisateur atteint un écran avec l’ID `final`. Si vous avez besoin de cet événement, assignez l’ID `final` au dernier écran.
`Unknown`	Pour tout type d’événement non reconnu. Inclut `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
`totalScreens`	Nombre total d’écrans dans le flow

Voici un exemple illustrant comment utiliser les événements analytiques pour le tracking :

override fun onAnalyticsEvent(event: AdaptyOnboardingAnalyticsEvent, context: Context) {
    when (event) {
        is AdaptyOnboardingAnalyticsEvent.OnboardingStarted -> {
            // Track onboarding start
            trackEvent("onboarding_started", event.meta)
        }
        is AdaptyOnboardingAnalyticsEvent.ScreenPresented -> {
            // Track screen presentation
            trackEvent("screen_presented", event.meta)
        }
        is AdaptyOnboardingAnalyticsEvent.ScreenCompleted -> {
            // Track screen completion with user response
            trackEvent("screen_completed", event.meta, event.elementId, event.reply)
        }
        is AdaptyOnboardingAnalyticsEvent.OnboardingCompleted -> {
            // Track successful onboarding completion
            trackEvent("onboarding_completed", event.meta)
        }
        is AdaptyOnboardingAnalyticsEvent.Unknown -> {
            // Handle unknown events
            trackEvent(event.name, event.meta)
        }
        // Handle other cases as needed
    }
}

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

// OnboardingStarted
{
  "name": "onboarding_started",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "welcome_screen",
    "screen_index": 0,
    "total_screens": 4
  }
}

// ScreenPresented

{
    "name": "screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "interests_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

// ScreenCompleted

{
    "name": "screen_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    },
    "params": {
        "element_id": "profile_form",
        "reply": "success"
    }
}

// SecondScreenPresented

{
    "name": "second_screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// UserEmailCollected

{
    "name": "user_email_collected",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// OnboardingCompleted

{
    "name": "onboarding_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "final_screen",
        "screen_index": 3,
        "total_screens": 4
    }
}

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

Actions personnalisées

Fermeture de l’onboarding

Ouverture d’un paywall

Fin du chargement de l’onboarding

Événements de navigation