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

Les onboardings sont dépréciés dans le SDK v4 et seront supprimés dans une version future. 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 réduits et aucune dépendance à l’environnement WebView. Consultez Obtenir des flows et paywalls et Afficher des flows et paywalls pour commencer.

Les onboardings configurés avec le builder génèrent des événements auxquels votre application peut réagir. Utilisez la méthode setEventHandlers pour gérer ces événements lors d’une présentation d’écran autonome.

Avant de commencer, assurez-vous que :

Vous avez créé un onboarding.
Vous avez ajouté l’onboarding à un placement.

Configurer les gestionnaires d’événements

Pour gérer les événements des onboardings, utilisez la méthode view.setEventHandlers :


try {
  const view = await createOnboardingView(onboarding);
  
  view.setEventHandlers({
    onAnalytics(event, meta) {
      console.log('Analytics event:', event);
    },
    onClose(actionId, meta) {
      console.log('Onboarding closed:', actionId);
      return true; // Allow the onboarding to close
    },
    onCustom(actionId, meta) {
      console.log('Custom action:', actionId);
      return false; // Don't close the onboarding
    },
    onPaywall(actionId, meta) {
      console.log('Paywall action:', actionId);
      view.dismiss().then(() => {
        openPaywall(actionId);
      });
    },
    onStateUpdated(action, meta) {
      console.log('State updated:', action);
    },
    onFinishedLoading(meta) {
      console.log('Onboarding finished loading');
    },
    onError(error) {
      console.error('Onboarding error:', error);
    },
  });
  
  await view.present();
} catch (error) {
  console.error('Failed to present onboarding:', error);
}

Types d’événements

Les sections suivantes décrivent les différents types d’événements que vous pouvez gérer.

Gérer les 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 traiter comme une action personnalisée. Par exemple, si un utilisateur appuie sur un bouton personnalisé, comme Login ou Allow notifications, le gestionnaire d’événements sera déclenché avec le paramètre actionId correspondant à l’Action ID défini dans le builder. Vous pouvez créer vos propres IDs, comme “allowNotifications”.

view.setEventHandlers({
  onCustom(actionId, meta) {
    switch (actionId) {
      case 'login':
        console.log('Login action triggered');
        break;
      case 'allow_notifications':
        console.log('Allow notifications action triggered');
        break;
    }
    return false; // Don't close the onboarding
  },
});

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

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

Fin du chargement de l’onboarding

Cet événement est déclenché lorsqu’un onboarding termine son chargement :

view.setEventHandlers({
  onFinishedLoading(meta) {
    console.log('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 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.

view.setEventHandlers({
  onClose(actionId, meta) {
    console.log('Onboarding closed:', actionId);
    return true; // Allow the onboarding to close
  },
});

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’afficher à l’intérieur de l’onboarding. Si vous voulez ouvrir un paywall après la fermeture de l’onboarding, 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 d’utiliser les paywalls dans les onboardings est de définir l’ID d’action égal à l’ID de placement du paywall.

Notez que, sur 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 en arrière-plan par programme. 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 de présenter le paywall.

view.setEventHandlers({
  onPaywall(actionId, meta) {
    // Dismiss onboarding before presenting paywall
    view.dismiss().then(() => {
      openPaywall(actionId);
    });
  },
});

async function openPaywall(placementId: string) {
  // Implement your paywall opening logic here
}

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

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

view.setEventHandlers({
  onAnalytics(event, meta) {
    console.log('Analytics event:', event.type, meta.onboardingId);
  },
});

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é quand les utilisateurs effectuent une action pour quitter l’écran.
`secondScreenPresented`	Lorsque le deuxième écran est affiché
`userEmailCollected`	Déclenché lorsque l’e-mail de l’utilisateur est collecté 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
`screensTotal`	Nombre 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
    }
}

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

Configurer les gestionnaires d’événements

Types d’événements

Gérer les actions personnalisées

Fin du chargement de l’onboarding

Fermeture de l’onboarding

Ouverture d’un paywall

Suivi de la navigation