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

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

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 corrections 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 aspect natif cohérent, des temps de chargement plus rapides et aucune dépendance à l’exécution WebView. Consultez Obtenir des flows et des paywalls et Afficher des flows et des paywalls pour démarrer.

Les onboardings configurés avec le builder génèrent des événements auxquels votre application peut réagir. La façon de gérer ces événements dépend de l’approche de présentation utilisée :

  • Présentation plein écran : nécessite la mise en place d’un observateur d’événements global qui gère les événements pour toutes les vues d’onboarding
  • Widget intégré : gère les événements via des paramètres de rappel en ligne directement dans le widget

Avant de commencer, assurez-vous que :

  1. Vous avez installé le SDK Flutter Adapty 3.8.0 ou une version ultérieure.
  2. Vous avez créé un onboarding.
  3. Vous avez ajouté l’onboarding à un placement.

Événements de présentation plein écran

Configurer l’observateur d’événements

Pour gérer les événements des onboardings en plein écran, implémentez AdaptyUIOnboardingsEventsObserver et configurez-le avant la présentation :

AdaptyUI().setOnboardingsEventsObserver(this);

try {
  await onboardingView.present();
} on AdaptyError catch (e) {
  // handle the error
} catch (e) {
  // handle the error
}

Gérer les événements

Implémentez ces méthodes dans votre observateur :

void onboardingViewDidFinishLoading(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
) {
  // Onboarding finished loading
}

void onboardingViewDidFailWithError(
  AdaptyUIOnboardingView view,
  AdaptyError error,
) {
  // Handle loading errors
}

void onboardingViewOnCloseAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Handle close action
  view.dismiss();
}

void onboardingViewOnPaywallAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Dismiss onboarding before presenting paywall
  view.dismiss().then((_) {
    _openPaywall(actionId);
  });
}

void onboardingViewOnCustomAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Handle custom actions
}

void onboardingViewOnStateUpdatedAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String elementId,
  AdaptyOnboardingsStateUpdatedParams params,
) {
  // Handle user input updates
}

void onboardingViewOnAnalyticsEvent(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  AdaptyOnboardingsAnalyticsEvent event,
) {
  // Track analytics events
}

Événements du widget intégré

Lorsque vous utilisez AdaptyUIOnboardingPlatformView, vous pouvez gérer les événements via des paramètres de rappel en ligne directement dans le widget. Notez que les événements seront envoyés à la fois aux rappels du widget et à l’observateur global (s’il est configuré), mais l’observateur global est optionnel :

AdaptyUIOnboardingPlatformView(
  onboarding: onboarding,
  onDidFinishLoading: (meta) {
    // Onboarding finished loading
  },
  onDidFailWithError: (error) {
    // Handle loading errors
  },
  onCloseAction: (meta, actionId) {
    // Handle close action
  },
  onPaywallAction: (meta, actionId) {
    _openPaywall(actionId);
  },
  onCustomAction: (meta, actionId) {
    // Handle custom actions
  },
  onStateUpdatedAction: (meta, elementId, params) {
    // Handle user input updates
  },
  onAnalyticsEvent: (meta, event) {
    // Track analytics events
  },
)

Types d’événements

Les sections suivantes décrivent les différents types d’événements que vous pouvez gérer, quelle que soit l’approche de présentation utilisée.

Gérer les actions personnalisées

Dans le builder, vous pouvez ajouter une action custom à un bouton et lui attribuer un ID.

ios-events-1.webp

Vous pouvez ensuite utiliser cet ID dans votre code et le traiter 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 onboardingController sera déclenchée avec le cas .custom(id:) et le paramètre actionId correspond à l’Action ID du builder. Vous pouvez créer vos propres IDs, comme « allowNotifications ».

// Full-screen presentation
void onboardingViewOnCustomAction(
    AdaptyUIOnboardingView view,
    AdaptyUIOnboardingMeta meta,
    String actionId,
) {
    switch (actionId) {
        case 'login':
            _login();
            break;
        case 'allow_notifications':
            _allowNotifications();
            break;
    }
}

// Embedded widget
onCustomAction: (meta, actionId) {
    _handleCustomAction(actionId);
}
Exemple d’événement (Cliquer pour développer)
{
  "actionId": "allowNotifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}

Fin du chargement de l’onboarding

Lorsqu’un onboarding finit de se charger, cet événement est déclenché :

// Full-screen presentation
void onboardingViewDidFinishLoading(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
) {
  print('Onboarding loaded: ${meta.onboardingId}');
}

// Embedded widget
onDidFinishLoading: (meta) {
  print('Onboarding loaded: ${meta.onboardingId}');
}
Exemple d’événement (Cliquer pour développer)
{
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "welcome_screen",
        "screen_index": 0,
        "total_screens": 4
    }
}

Fermeture de l’onboarding

L’onboarding est considéré comme fermé lorsqu’un utilisateur appuie sur un bouton avec l’action Close assignée.

ios-events-2.webp

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.

// Full-screen presentation
void onboardingViewOnCloseAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  await view.dismiss();
}

// Embedded widget
onCloseAction: (meta, actionId) {
  Navigator.of(context).pop();
}
Exemple d’événement (Cliquer 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’afficher à l’intérieur de l’onboarding. Si vous voulez ouvrir un paywall après sa fermeture, il existe une méthode plus simple — gérez l’action de fermeture 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 du placement du paywall :

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

// Full-screen presentation
void onboardingViewOnPaywallAction(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  String actionId,
) {
  // Dismiss onboarding before presenting paywall
  view.dismiss().then((_) {
    _openPaywall(actionId);
  });
}

Future<void> _openPaywall(String actionId) async {
  // Implement your paywall opening logic here
}

// Embedded widget
onPaywallAction: (meta, actionId) {
  _openPaywall(actionId);
}
Exemple d’événement (Cliquer pour développer)
{
    "action_id": "premium_offer_1",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "pricing_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

Suivi de la navigation

Vous recevez un événement analytique lorsque différents événements liés à la navigation se produisent pendant le flow d’onboarding :

// Full-screen presentation
void onboardingViewOnAnalyticsEvent(
  AdaptyUIOnboardingView view,
  AdaptyUIOnboardingMeta meta,
  AdaptyOnboardingsAnalyticsEvent event,
) {
  trackEvent(event.type, meta.onboardingId);
}

// Embedded widget
onAnalyticsEvent: (meta, event) {
  trackEvent(event.type, meta.onboardingId);
}

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

TypeDescription
onboardingStartedLorsque l’onboarding a été chargé
screenPresentedLorsqu’un écran est affiché
screenCompletedLorsqu’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é lorsque les utilisateurs effectuent une action pour quitter l’écran.
secondScreenPresentedLorsque le deuxième écran est affiché
userEmailCollectedDéclenché lorsque l’e-mail de l’utilisateur est collecté via le champ de saisie
onboardingCompletedDé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.
unknownPour 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 :

ChampDescription
onboardingIdIdentifiant unique du flow d’onboarding
screenClientIdIdentifiant de l’écran actuel
screenIndexPosition de l’écran actuel dans le flow
screensTotalNombre total d’écrans dans le flow
Exemples d’événements (Cliquer 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
    }
}