Manejar eventos de onboarding en el SDK de Capacitor
Los onboardings están obsoletos en el SDK v4 y se eliminarán en una versión futura. Ya no reciben correcciones ni mejoras. Usa flows en su lugar: a diferencia de los onboardings, que se ejecutan dentro de un WebView, los flows se renderizan de forma nativa en el dispositivo, lo que ofrece animaciones más fluidas, una apariencia nativa consistente, tiempos de carga más rápidos y sin dependencia del entorno WebView. Consulta Obtener flows y paywalls y Mostrar flows y paywalls para empezar.
Los onboardings configurados con el builder generan eventos a los que tu app puede responder. Usa el método setEventHandlers para gestionar estos eventos en la presentación de pantallas independientes.
Antes de empezar, asegúrate de:
- Haber creado un onboarding.
- Haber añadido el onboarding a un placement.
Configurar manejadores de eventos
Para gestionar los eventos de los onboardings, usa el método 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);
}Tipos de eventos
Las siguientes secciones describen los distintos tipos de eventos que puedes gestionar.
Gestionar acciones personalizadas
En el builder, puedes añadir una acción custom a un botón y asignarle un ID.
Luego, puedes usar este ID en tu código y gestionarlo como una acción personalizada. Por ejemplo, si el usuario pulsa un botón personalizado, como Login o Allow notifications, el manejador de eventos se activará con el parámetro actionId que coincide con el Action ID del builder. Puedes crear tus propios IDs, como “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
},
});Ejemplo de evento (Haz clic para expandir)
{
"actionId": "allow_notifications",
"meta": {
"onboardingId": "onboarding_123",
"screenClientId": "profile_screen",
"screenIndex": 0,
"screensTotal": 3
}
}Finalización de la carga del onboarding
Cuando un onboarding termina de cargarse, se activa este evento:
view.setEventHandlers({
onFinishedLoading(meta) {
console.log('Onboarding loaded:', meta.onboardingId);
},
});Ejemplo de evento (haz clic para expandir)
{
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "welcome_screen",
"screen_index": 0,
"total_screens": 4
}
}Cierre del onboarding
El onboarding se considera cerrado cuando el usuario pulsa un botón con la acción Close asignada.
Ten en cuenta que debes gestionar qué ocurre cuando el usuario cierra el onboarding. Por ejemplo, debes dejar de mostrar el propio onboarding.
view.setEventHandlers({
onClose(actionId, meta) {
console.log('Onboarding closed:', actionId);
return true; // Allow the onboarding to close
},
});Ejemplo de evento (haz clic para expandir)
{
"action_id": "close_button",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "final_screen",
"screen_index": 3,
"total_screens": 4
}
}Apertura de un paywall
Gestiona este evento para abrir un paywall si quieres hacerlo dentro del onboarding. Si quieres abrir un paywall después de que se cierre, hay una forma más directa de hacerlo: gestiona la acción de cierre y abre un paywall sin depender de los datos del evento.
La forma más fluida de trabajar con paywalls en onboardings es hacer que el ID de acción sea igual al ID del placement del paywall. Ten en cuenta que, en iOS, solo se puede mostrar una vista (paywall u onboarding) en pantalla al mismo tiempo. Si presentas un paywall sobre un onboarding, no podrás controlar el onboarding en segundo plano mediante código. Si intentas cerrar el onboarding, se cerrará el paywall en su lugar y el onboarding quedará visible. Para evitarlo, cierra siempre la vista del onboarding antes de presentar el 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
}Ejemplo de evento (Haz clic para expandir)
{
"action_id": "premium_offer_1",
"meta": {
"onboarding_id": "onboarding_123",
"screen_cid": "pricing_screen",
"screen_index": 2,
"total_screens": 4
}
}Seguimiento de navegación
Recibes un evento de analítica cuando ocurren distintos eventos de navegación durante el flow de onboarding:
view.setEventHandlers({
onAnalytics(event, meta) {
console.log('Analytics event:', event.type, meta.onboardingId);
},
});El objeto event puede ser de uno de los siguientes tipos:
| Tipo | Descripción |
|---|---|
onboardingStarted | Cuando el onboarding ha sido cargado |
screenPresented | Cuando se muestra cualquier pantalla |
screenCompleted | Cuando se completa una pantalla. Incluye el parámetro opcional elementId (identificador del elemento completado) y el opcional reply (respuesta del usuario). Se activa cuando el usuario realiza cualquier acción para salir de la pantalla. |
secondScreenPresented | Cuando se muestra la segunda pantalla |
userEmailCollected | Se activa cuando se recoge el correo electrónico del usuario a través del campo de entrada |
onboardingCompleted | Se activa cuando un usuario llega a una pantalla con el ID final. Si necesitas este evento, asigna el ID final a la última pantalla. |
unknown | Para cualquier tipo de evento no reconocido. Incluye name (el nombre del evento desconocido) y meta (metadatos adicionales) |
Cada evento incluye información meta que contiene: |
| Campo | Descripción |
|---|---|
onboardingId | Identificador único del flow de onboarding |
screenClientId | Identificador de la pantalla actual |
screenIndex | Posición de la pantalla actual en el flow |
screensTotal | Número total de pantallas en el flow |
Ejemplos de eventos (haz clic para expandir)
// 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
}
}