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

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

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.

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

  • Présentation plein écran : Nécessite la configuration 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 inline directement dans le widget

Avant de commencer, assurez-vous que :

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

Événements de présentation en plein écran

Configurer l’observateur d’événements

Pour gérer les événements des onboardings en plein écran, implémentez AdaptyUIOnboardingsEventsObserver et définissez-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 callback directement dans le widget. Notez que les événements sont envoyés à la fois aux callbacks 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 personnalisée à un bouton et lui attribuer un identifiant.

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 (Cliquez pour développer)
{
  "actionId": "allowNotifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}

Fin du chargement de l’onboarding

Lorsque le chargement d’un onboarding se termine, 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 (Cliquez 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
Important

Notez que vous devez gérer ce qui se passe lorsqu’un utilisateur ferme l’onboarding. Par exemple, vous devez cesser 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 (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’afficher à l’intérieur de l’onboarding. Si vous voulez ouvrir un paywall après sa fermeture, il existe une approche plus directe : 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 de placement du paywall :

Note

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 onboarding avant d’afficher 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 agrandir)
{
    "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 d’analyse lorsque différents événements liés à la navigation se produisent dans 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
onboardingStartedQuand l’onboarding a été chargé
screenPresentedQuand un écran est affiché
screenCompletedQuand 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 les utilisateurs effectuent une action pour quitter l’écran.
secondScreenPresentedQuand le deuxième écran est affiché
userEmailCollectedDéclenché lorsque l’adresse e-mail de l’utilisateur est collectée 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, assignez 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 (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
    }
}