Gestionar eventos de flow y paywall - React Native
Esta guía cubre el manejo de eventos para compras, restauraciones, selección de productos y renderizado de flows. También puedes configurar el manejo de botones (cerrar el flow, abrir enlaces, acciones personalizadas, etc.). Consulta nuestra guía sobre el manejo de acciones de botones para más detalles.
Los flows y paywalls creados con el Flow Builder no necesitan código adicional para realizar y restaurar compras. Sin embargo, generan ciertos eventos a los que tu aplicación puede responder. Estos eventos incluyen pulsaciones de botones (botones de cierre, URLs, selecciones de productos, etc.), así como notificaciones sobre acciones relacionadas con compras realizadas en el flow. A continuación se explica cómo responder a estos eventos.
Para controlar o supervisar los procesos que ocurren en la pantalla del flow dentro de tu aplicación móvil, implementa manejadores de eventos:
Ejemplos de eventos (Haz clic para expandir)
// onCloseButtonPress
{
//Record the event
}
// onAndroidSystemBack
{
//Record the event
}
// onUrlPress
{
"url": "https://example.com/terms"
}
// onCustomAction
{
"actionId": "login"
}
// onProductSelected
{
"productId": "premium_monthly"
}
// onPurchaseStarted
{
"product": {
"vendorProductId": "premium_monthly",
"localizedTitle": "Premium Monthly",
"localizedDescription": "Premium subscription for 1 month",
"price": {
"amount": 9.99,
"currencyCode": "USD",
"currencySymbol": "$",
"localizedString": "$9.99"
}
}
}
// onPurchaseCompleted - Success
{
"purchaseResult": {
"type": "success",
"profile": {
"accessLevels": {
"premium": {
"id": "premium",
"isActive": true,
"expiresAt": "2024-02-15T10:30:00Z"
}
}
}
},
"product": {
"vendorProductId": "premium_monthly",
"localizedTitle": "Premium Monthly",
"localizedDescription": "Premium subscription for 1 month",
"price": {
"amount": 9.99,
"currencyCode": "USD",
"currencySymbol": "$",
"localizedString": "$9.99"
}
}
}
// onPurchaseCompleted - Cancelled
{
"purchaseResult": {
"type": "user_cancelled"
},
"product": {
"vendorProductId": "premium_monthly",
"localizedTitle": "Premium Monthly",
"localizedDescription": "Premium subscription for 1 month",
"price": {
"amount": 9.99,
"currencyCode": "USD",
"currencySymbol": "$",
"localizedString": "$9.99"
}
}
}
// onPurchaseFailed
{
"error": {
"code": "purchase_failed",
"message": "Purchase failed due to insufficient funds",
"details": {
"underlyingError": "Insufficient funds in account"
}
},
"product": {
"vendorProductId": "premium_monthly",
"localizedTitle": "Premium Monthly",
"localizedDescription": "Premium subscription for 1 month",
"price": {
"amount": 9.99,
"currencyCode": "USD",
"currencySymbol": "$",
"localizedString": "$9.99"
}
}
}
// onRestoreCompleted
{
"profile": {
"accessLevels": {
"premium": {
"id": "premium",
"isActive": true,
"expiresAt": "2024-02-15T10:30:00Z"
}
},
"subscriptions": [
{
"vendorProductId": "premium_monthly",
"isActive": true,
"expiresAt": "2024-02-15T10:30:00Z"
}
]
}
}
// onRestoreFailed
{
"error": {
"code": "restore_failed",
"message": "Purchase restoration failed",
"details": {
"underlyingError": "No previous purchases found"
}
}
}
// onError
{
"error": {
"code": "rendering_failed",
"message": "Failed to render flow interface",
"details": {
"underlyingError": "Invalid flow configuration"
}
}
}
// onLoadingProductsFailed
{
"error": {
"code": "products_loading_failed",
"message": "Failed to load products from the server",
"details": {
"underlyingError": "Network timeout"
}
}
}
// onAppeared
{
//Record the event
}
// onDisappeared
{
//Record the event
}
// onWebPaymentNavigationFinished
{
//Record the event
}Puedes registrar solo los manejadores de eventos que necesites y omitir los que no uses. De este modo, no se crearán listeners de eventos innecesarios. No hay manejadores de eventos obligatorios.
Los manejadores de eventos devuelven un booleano. Si se devuelve true, el proceso de visualización se considera completado, por lo que la pantalla del flow se cierra y se eliminan los listeners de eventos para esa vista.
Algunos manejadores de eventos tienen un comportamiento predeterminado que puedes sobreescribir si es necesario:
onCloseButtonPress: cierra el flow cuando se pulsa el botón de cierre.onUrlPress: abre la URL pulsada y mantiene el flow abierto.onAndroidSystemBack(solo para presentación modal): mantiene el flow abierto cuando se pulsa el botón Back. Devuelvetruepara cerrarlo.onRestoreCompleted: mantiene el flow abierto tras una restauración exitosa. Devuelvetruepara cerrarlo.onPurchaseCompleted: mantiene el flow abierto tras completarse una compra. Devuelvetruepara cerrarlo.onError: cierra el flow si falla su renderizado.
Controladores de eventos
| Manejador de eventos | Descripción |
|---|---|
| onCustomAction | Se invoca cuando el usuario realiza una acción personalizada, por ejemplo, al hacer clic en un botón personalizado. |
| onUrlPress | Se invoca cuando el usuario hace clic en una URL dentro del flow. |
| onAndroidSystemBack | Solo presentación modal: se invoca cuando el usuario pulsa el botón del sistema Back de Android. |
| onCloseButtonPress | Se invoca cuando el botón de cerrar está visible y el usuario lo pulsa. Se recomienda cerrar la pantalla del flow en este manejador. |
| onPurchaseCompleted | Se invoca cuando la compra finaliza, ya sea con éxito, cancelada por el usuario o pendiente de aprobación. En caso de compra exitosa, proporciona un AdaptyProfile actualizado. Las cancelaciones del usuario y los pagos pendientes (por ejemplo, cuando se requiere aprobación parental) activan este evento, no onPurchaseFailed. |
| onPurchaseStarted | Se invoca cuando el usuario pulsa el botón de acción “Comprar” para iniciar el proceso de compra. |
| onPurchaseFailed | Se invoca cuando una compra falla por errores (por ejemplo, restricciones de pago, productos no válidos, fallos de red o errores de verificación de transacción). No se invoca para cancelaciones del usuario ni pagos pendientes, que activan onPurchaseCompleted en su lugar. |
| onRestoreStarted | Se invoca cuando el usuario inicia un proceso de restauración de compras. |
| onRestoreCompleted | Se invoca cuando la restauración de compras se completa con éxito y proporciona un AdaptyProfile actualizado. Se recomienda cerrar la pantalla si el usuario tiene el accessLevel requerido. Consulta el tema Estado de la suscripción para saber cómo comprobarlo. |
| onRestoreFailed | Se invoca cuando el proceso de restauración falla y proporciona un AdaptyError. |
| onProductSelected | Se invoca cuando se selecciona cualquier producto en la vista del flow, lo que permite monitorear qué elige el usuario antes de la compra. |
| onError | Se invoca cuando ocurre un error durante el renderizado de la vista y proporciona un AdaptyError. Estos errores no deberían producirse; si encuentras uno, comunícanoslo. |
| onLoadingProductsFailed | Se invoca cuando la carga de productos falla y proporciona un AdaptyError. Si no has configurado prefetchProducts: true al crear la vista, AdaptyUI obtendrá los objetos necesarios del servidor por sí mismo. |
| onAppeared | Se invoca cuando el flow se muestra al usuario. En iOS, también se invoca cuando el usuario pulsa el botón de paywall web dentro de un flow y el paywall web se abre en un navegador in-app. |
| onDisappeared | Solo presentación modal: se invoca cuando el usuario cierra el flow. En iOS, también se invoca cuando un paywall web abierto desde un flow en un navegador in-app desaparece de la pantalla. |
| onWebPaymentNavigationFinished | Se invoca tras intentar abrir un paywall web para la compra, tanto si se abre con éxito como si falla. |
| onAnalytics | Reservado para eventos analíticos personalizados de un flow. Los flows aún no emiten estos eventos a tu código, por lo que no es necesario implementarlo. |
| onRequestAppReview | Reservado para solicitudes de valoración de la app desde un flow. Los flows aún no activan solicitudes de valoración, por lo que no es necesario implementarlo. |
| onRequestPermission | Reservado para solicitudes de permisos del sistema (como notificaciones push o acceso a la cámara) desde un flow. Los flows aún no activan solicitudes de permisos, por lo que no es necesario implementarlo. |
| onObserverPurchaseInitiated | Solo modo observador: se invoca cuando el usuario pulsa el botón de compra en un flow. Adapty no realiza la compra — ejecútala con tu propio código de compra y luego notifica la transacción a Adapty. Consulta Gestionar compras en modo observador más abajo. |
| onObserverRestoreInitiated | Solo modo observador: se invoca cuando el usuario pulsa el botón de restaurar en un flow. Adapty no restaura — hazlo tú mismo y luego notifica las transacciones restauradas. Consulta Gestionar compras en modo observador más abajo. |
Gestionar compras en modo observador
Si activaste el SDK en modo observador (observerMode: true) y presentas un flow renderizado por Adapty, el SDK no realiza las compras por ti. Cuando el usuario pulsa el botón de compra o restauración, el SDK invoca onObserverPurchaseInitiated o onObserverRestoreInitiated en su lugar. Realiza la compra o restauración con tu propio código, controla el indicador de carga del flow con los callbacks proporcionados y, después, reporta la transacción a Adapty.
const unsubscribe = view.setEventHandlers({
onObserverPurchaseInitiated(product, onStartPurchase, onFinishPurchase) {
onStartPurchase(); // show the flow's loading indicator
myPurchaseApi(product.vendorProductId)
.then((transactionId) => adapty.reportTransaction(transactionId))
.finally(() => onFinishPurchase()); // hide the loading indicator
return false; // keep the flow open; dismiss it yourself after success
},
onObserverRestoreInitiated(onStartRestore, onFinishRestore) {
onStartRestore();
myRestoreApi()
.finally(() => onFinishRestore());
return false;
},
});Esta guía cubre el manejo de eventos para compras, restauraciones, selección de productos y renderizado de paywalls. También debes implementar el manejo de botones (cerrar el paywall, abrir enlaces, etc.). Consulta nuestra guía sobre cómo manejar las acciones de los botones para más detalles.
Los paywalls configurados con el Paywall Builder no necesitan código adicional para realizar y restaurar compras. Sin embargo, generan una serie de eventos a los que tu app puede responder. Estos eventos incluyen pulsaciones de botones (botones de cierre, URLs, selección de productos, etc.), así como notificaciones sobre acciones relacionadas con compras realizadas en el paywall. A continuación te explicamos cómo responder a estos eventos.
Esta guía es exclusivamente para paywalls del nuevo Paywall Builder que requieren Adapty SDK v3.0 o posterior.
Para controlar o monitorear los procesos que ocurren en la pantalla del paywall dentro de tu app móvil, implementa manejadores de eventos:
Ejemplos de eventos (Haz clic para expandir)
// onCloseButtonPress
{
//Record the event
}
// onAndroidSystemBack
{
//Record the event
}
// onUrlPress
{
"url": "https://example.com/terms"
}
// onCustomAction
{
"actionId": "login"
}
// onProductSelected
{
"productId": "premium_monthly"
}
// onPurchaseStarted
{
"product": {
"vendorProductId": "premium_monthly",
"localizedTitle": "Premium Monthly",
"localizedDescription": "Premium subscription for 1 month",
"price": {
"amount": 9.99,
"currencyCode": "USD",
"currencySymbol": "$",
"localizedString": "$9.99"
}
}
}
// onPurchaseCompleted - Success
{
"purchaseResult": {
"type": "success",
"profile": {
"accessLevels": {
"premium": {
"id": "premium",
"isActive": true,
"expiresAt": "2024-02-15T10:30:00Z"
}
}
}
},
"product": {
"vendorProductId": "premium_monthly",
"localizedTitle": "Premium Monthly",
"localizedDescription": "Premium subscription for 1 month",
"price": {
"amount": 9.99,
"currencyCode": "USD",
"currencySymbol": "$",
"localizedString": "$9.99"
}
}
}
// onPurchaseCompleted - Cancelled
{
"purchaseResult": {
"type": "user_cancelled"
},
"product": {
"vendorProductId": "premium_monthly",
"localizedTitle": "Premium Monthly",
"localizedDescription": "Premium subscription for 1 month",
"price": {
"amount": 9.99,
"currencyCode": "USD",
"currencySymbol": "$",
"localizedString": "$9.99"
}
}
}
// onPurchaseFailed
{
"error": {
"code": "purchase_failed",
"message": "Purchase failed due to insufficient funds",
"details": {
"underlyingError": "Insufficient funds in account"
}
},
"product": {
"vendorProductId": "premium_monthly",
"localizedTitle": "Premium Monthly",
"localizedDescription": "Premium subscription for 1 month",
"price": {
"amount": 9.99,
"currencyCode": "USD",
"currencySymbol": "$",
"localizedString": "$9.99"
}
}
}
// onRestoreCompleted
{
"profile": {
"accessLevels": {
"premium": {
"id": "premium",
"isActive": true,
"expiresAt": "2024-02-15T10:30:00Z"
}
},
"subscriptions": [
{
"vendorProductId": "premium_monthly",
"isActive": true,
"expiresAt": "2024-02-15T10:30:00Z"
}
]
}
}
// onRestoreFailed
{
"error": {
"code": "restore_failed",
"message": "Purchase restoration failed",
"details": {
"underlyingError": "No previous purchases found"
}
}
}
// onRenderingFailed
{
"error": {
"code": "rendering_failed",
"message": "Failed to render paywall interface",
"details": {
"underlyingError": "Invalid paywall configuration"
}
}
}
// onLoadingProductsFailed
{
"error": {
"code": "products_loading_failed",
"message": "Failed to load products from the server",
"details": {
"underlyingError": "Network timeout"
}
}
}
// onPaywallShown
{
//Record the event
}
// onPaywallClosed
{
//Record the event
}
// onWebPaymentNavigationFinished
{
//Record the event
}Puedes registrar solo los manejadores de eventos que necesites y omitir los que no uses. Así no se crearán listeners innecesarios. No hay ningún manejador de eventos obligatorio.
Los manejadores de eventos devuelven un booleano. Si se devuelve true, el proceso de visualización se considera completado, por lo que la pantalla del paywall se cierra y se eliminan los listeners de eventos para esa vista.
Algunos manejadores de eventos tienen un comportamiento predeterminado que puedes reemplazar si lo necesitas:
onCloseButtonPress: cierra el paywall cuando se pulsa el botón de cerrar.onUrlPress: abre la URL pulsada y mantiene el paywall abierto.onAndroidSystemBack(solo para presentación modal): cierra el paywall cuando se pulsa el botón Back.onRestoreCompleted: cierra el paywall tras una restauración exitosa.onPurchaseCompleted: cierra el paywall a menos que el usuario haya cancelado.onRenderingFailed: cierra el paywall si falla su renderizado.
Controladores de eventos
| Manejador de eventos | Descripción |
|---|---|
| onCustomAction | Se invoca cuando el usuario realiza una acción personalizada, por ejemplo, hace clic en un botón personalizado. |
| onUrlPress | Se invoca cuando el usuario hace clic en una URL de tu paywall. |
| onAndroidSystemBack | Solo en presentación modal: se invoca cuando el usuario pulsa el botón de sistema Back de Android. |
| onCloseButtonPress | Se invoca cuando el botón de cierre está visible y el usuario lo pulsa. Se recomienda cerrar la pantalla del paywall en este manejador. |
| onPurchaseCompleted | Se invoca cuando la compra finaliza, ya sea con éxito, cancelada por el usuario o pendiente de aprobación. En caso de compra exitosa, proporciona un AdaptyProfile actualizado. Las cancelaciones del usuario y los pagos pendientes (p. ej., se requiere aprobación parental) disparan este evento, no onPurchaseFailed. |
| onPurchaseStarted | Se invoca cuando el usuario pulsa el botón de acción “Comprar” para iniciar el proceso de compra. |
| onPurchaseFailed | Se invoca cuando una compra falla por errores (p. ej., restricciones de pago, productos no válidos, fallos de red, errores de verificación de transacción). No se invoca por cancelaciones del usuario ni pagos pendientes, que disparan onPurchaseCompleted en su lugar. |
| onRestoreStarted | Se invoca cuando el usuario inicia un proceso de restauración de compras. |
| onRestoreCompleted | Se invoca cuando la restauración de compras tiene éxito y proporciona un AdaptyProfile actualizado. Se recomienda cerrar la pantalla si el usuario tiene el accessLevel requerido. Consulta el tema Estado de suscripción para saber cómo comprobarlo. |
| onRestoreFailed | Se invoca cuando el proceso de restauración falla y proporciona AdaptyError. |
| onProductSelected | Se invoca cuando se selecciona cualquier producto en la vista del paywall, lo que permite monitorizar qué elige el usuario antes de la compra. |
| onRenderingFailed | Se invoca cuando ocurre un error durante el renderizado de la vista y proporciona AdaptyError. Estos errores no deberían ocurrir; si te encuentras con uno, por favor comunícanoslo. |
| onLoadingProductsFailed | Se invoca cuando la carga de productos falla y proporciona AdaptyError. Si no has configurado prefetchProducts: true al crear la vista, AdaptyUI recuperará los objetos necesarios del servidor por sí mismo. |
| onPaywallShown | Se invoca cuando el paywall se muestra al usuario. En iOS, también se invoca cuando el usuario pulsa el botón de web paywall dentro de un paywall y el web paywall se abre en un navegador in-app. |
| onPaywallClosed | Solo en presentación modal: se invoca cuando el usuario cierra el paywall. En iOS, también se invoca cuando un web paywall abierto desde un paywall en un navegador in-app desaparece de la pantalla. |
| onWebPaymentNavigationFinished | Se invoca tras intentar abrir un web paywall para realizar una compra, tanto si tiene éxito como si falla. |