---
title: "Gérer les événements d'onboarding dans le SDK Capacitor"
description: "Gérez les événements liés à l'onboarding dans Capacitor avec Adapty."
---
:::warning
**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](capacitor-get-pb-paywalls) à 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](capacitor-get-pb-paywalls) et [Afficher des flows et paywalls](capacitor-present-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 :
1. Vous avez [créé un onboarding](create-onboarding).
2. Vous avez ajouté l'onboarding à un [placement](placements).
## Configurer les gestionnaires d'événements \{#set-up-event-handlers\}
Pour gérer les événements des onboardings, utilisez la méthode `view.setEventHandlers` :
```typescript showLineNumbers
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 \{#event-types\}
Les sections suivantes décrivent les différents types d'événements que vous pouvez gérer.
### Gérer les actions personnalisées \{#handle-custom-actions\}
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".
```typescript showLineNumbers
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)
```json
{
"actionId": "allow_notifications",
"meta": {
"onboardingId": "onboarding_123",
"screenClientId": "profile_screen",
"screenIndex": 0,
"screensTotal": 3
}
}
```
### Fin du chargement de l'onboarding \{#finishing-loading-onboarding\}
Cet événement est déclenché lorsqu'un onboarding termine son chargement :
```typescript showLineNumbers
view.setEventHandlers({
onFinishedLoading(meta) {
console.log('Onboarding loaded:', meta.onboardingId);
},
});
```
Exemple d'événement (cliquez pour développer)
```json
{
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "welcome_screen",
"screen_index": 0,
"total_screens": 4
}
}
```
### Fermeture de l'onboarding \{#closing-onboarding\}
L'onboarding est considéré comme fermé lorsqu'un utilisateur appuie sur un bouton auquel l'action **Close** est assignée.
:::important
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.
:::
```typescript showLineNumbers
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)
```json
{
"action_id": "close_button",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "final_screen",
"screen_index": 3,
"total_screens": 4
}
}
```
### Ouverture d'un paywall \{#opening-a-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 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.
```typescript showLineNumbers
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)
```json
{
"action_id": "premium_offer_1",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "pricing_screen",
"screen_index": 2,
"total_screens": 4
}
}
```
### Suivi de la navigation \{#tracking-navigation\}
Vous recevez un événement d'analytics lorsque différents événements liés à la navigation se produisent pendant le flow d'onboarding :
```typescript showLineNumbers
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](design-onboarding). |
| `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)
```javascript
// 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
}
}
```