Gérer les événements d'onboarding dans le SDK Capacitor
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. Utilisez la méthode setEventHandlers pour gérer ces événements lors de la présentation d’un é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 custom à un bouton et lui attribuer un ID.
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, 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
Lorsque le chargement d’un onboarding est terminé, cet événement est déclenché :
view.setEventHandlers({
onFinishedLoading(meta) {
console.log('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 associé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 (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 souhaitez ouvrir un paywall après sa fermeture, il existe une méthode 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 comme étant égal à l’ID de placement du paywall.
Notez que, sous 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. Toute tentative 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.
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 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 au cours du 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é lorsque les utilisateurs effectuent une action pour quitter l’écran. |
secondScreenPresented | Lorsque le deuxième écran est affiché |
userEmailCollected | Déclenché lorsque l’adresse e-mail de l’utilisateur est collectée 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
}
}