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

Les onboardings sont dépréciés dans le SDK v4 et seront supprimés dans une prochaine version. Ils ne reçoivent plus de correctifs ni d’améliorations. Utilisez les flows à la place : contrairement aux onboardings, qui s’exécutent dans une WebView, les flows s’affichent nativement sur l’appareil — offrant des animations plus fluides, un rendu natif cohérent, des temps de chargement plus rapides, et aucune dépendance à un runtime WebView. Consultez Obtenir des flows & paywalls et Afficher des flows & paywalls pour commencer.

Avant de commencer, assurez-vous que :

Vous avez installé le SDK Adapty Unity version 3.14.0 ou 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 gérer ces événements.

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

Dans le SDK 4.0, les interfaces listener suivent la convention de préfixe C# I- : implémentez IAdaptyOnboardingsEventsListener plutôt que AdaptyOnboardingsEventsListener. Les méthodes restent inchangées. Consultez le guide de migration.

Actions personnalisées

Dans le builder, vous pouvez ajouter une action personnalisée à un bouton et lui attribuer un identifiant.

Ensuite, vous pouvez 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 OnboardingViewOnCustomAction sera déclenchée avec le paramètre actionId correspondant à l’Action ID défini dans le builder. Vous pouvez créer vos propres IDs, comme “allowNotifications”.

Pour gérer les événements d’onboarding, implémentez l’interface AdaptyOnboardingsEventsListener :

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    void Start()
    {
        Adapty.SetOnboardingsEventsListener(this);
    }

    public void OnboardingViewOnCustomAction(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        string actionId
    )
    {
        if (actionId == "allowNotifications") {
            // request notification permissions
        }
    }
    
    public void OnboardingViewDidFailWithError(
        AdaptyUIOnboardingView view,
        AdaptyError error
    )
    {
        // handle errors
    }

    // Implement other required interface methods (see examples below)
}

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.

Notez que 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.

Implémentez la méthode OnboardingViewOnCloseAction dans votre classe :

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewOnCloseAction(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        string actionId
    )
    {
        view.Dismiss((error) => {
            if (error != null) {
                // handle the error
            }
        });
    }
    
    // ... other interface methods
}

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

Gérez cet événement pour ouvrir un paywall si vous souhaitez l’ouvrir à l’intérieur de l’onboarding. Si vous souhaitez 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 faire correspondre l’ID d’action à l’ID de placement du paywall. Ainsi, après l’événement OnboardingViewOnPaywallAction, vous pouvez utiliser l’ID de placement pour récupérer et ouvrir immédiatement le paywall.

Notez que, pour iOS, une seule vue (paywall ou onboarding) peut être affichée à l’écran à la fois. Si vous affichez un paywall par-dessus un onboarding, vous ne pouvez pas contrôler l’onboarding en arrière-plan par programmation. Tenter de fermer l’onboarding fermera le paywall à la place, laissant l’onboarding visible. Pour éviter cela, fermez toujours la vue de l’onboarding avant d’afficher le paywall.

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewOnPaywallAction(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        string actionId
    )
    {
        // Dismiss onboarding before presenting paywall
        view.Dismiss((dismissError) => {
            if (dismissError != null) {
                // handle the error
                return;
            }

            Adapty.GetPaywall(actionId, (paywall, error) => {
                if (error != null) {
                    // handle the error
                    return;
                }

                AdaptyUI.CreatePaywallView(paywall, (paywallView, createError) => {
                    if (createError != null) {
                        // handle the error
                        return;
                    }

                    paywallView.Present((presentError) => {
                        if (presentError != null) {
                            // handle the error
                        }
                    });
                });
            });
        });
    }
    
    // ... other interface methods
}

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

Lorsque le chargement d’un onboarding se termine, implémentez la méthode OnboardingViewDidFinishLoading :

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewDidFinishLoading(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta
    )
    {
        // handle loading completion
    }
    
    // ... other interface methods
}

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 lorsque divers événements analytiques se produisent au cours du flow d’onboarding.

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

Type	Description
`AdaptyOnboardingsAnalyticsEventOnboardingStarted`	Quand l’onboarding a été chargé
`AdaptyOnboardingsAnalyticsEventScreenPresented`	Quand un écran est affiché
`AdaptyOnboardingsAnalyticsEventScreenCompleted`	Quand un écran est complété. Inclut un `ElementId` optionnel (identifiant de l’élément complété) et une `Reply` optionnelle (réponse de l’utilisateur). Déclenché quand l’utilisateur effectue une action pour quitter l’écran.
`AdaptyOnboardingsAnalyticsEventSecondScreenPresented`	Quand le deuxième écran est affiché
`AdaptyOnboardingsAnalyticsEventUserEmailCollected`	Déclenché quand l’e-mail de l’utilisateur est collecté via le champ de saisie
`AdaptyOnboardingsAnalyticsEventOnboardingCompleted`	Déclenché quand un utilisateur atteint un écran avec l’ID `final`. Si vous avez besoin de cet événement, assignez l’ID `final` au dernier écran.
`AdaptyOnboardingsAnalyticsEventUnknown`	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
`ScreensTotal`	Nombre total d’écrans dans le flow

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

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewOnAnalyticsEvent(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        AdaptyOnboardingsAnalyticsEvent analyticsEvent
    )
    {
        switch (analyticsEvent) {
            case AdaptyOnboardingsAnalyticsEventOnboardingStarted:
                // track onboarding start
                TrackEvent("onboarding_started", meta);
                break;
            case AdaptyOnboardingsAnalyticsEventScreenPresented:
                // track screen presentation
                TrackEvent("screen_presented", meta);
                break;
            case AdaptyOnboardingsAnalyticsEventScreenCompleted screenCompleted:
                // track screen completion with user response
                TrackEvent("screen_completed", meta, screenCompleted.ElementId, screenCompleted.Reply);
                break;
            case AdaptyOnboardingsAnalyticsEventOnboardingCompleted:
                // track successful onboarding completion
                TrackEvent("onboarding_completed", meta);
                break;
            case AdaptyOnboardingsAnalyticsEventUnknown unknownEvent:
                // handle unknown events
                TrackEvent(unknownEvent.Name, meta);
                break;
            // handle other cases as needed
        }
    }
    
    // ... other interface methods
}

La méthode TrackEvent est un espace réservé que vous devez implémenter vous-même pour envoyer des données analytiques à votre service d’analyse préféré.

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 Unity

Actions personnalisées

Fermeture de l’onboarding

Ouverture d’un paywall

Fin du chargement de l’onboarding

Suivi de la navigation