Migrar el SDK de React Native de Adapty a la versión 4.0

El SDK de React Native de Adapty 4.0 (beta) introduce los flows y cambia el nombre de las APIs de paywall en consecuencia. Las nuevas APIs funcionan tanto con el nuevo Flow Builder como con el Paywall Builder existente — no se requieren cambios de configuración en el Adapty Dashboard.

Referencia rápida

v3	v4
`adapty.getPaywall(placementId, locale?, params?)`	`adapty.getFlow(placementId, params?)`
`adapty.getPaywallForDefaultAudience(placementId, locale?, params?)`	`adapty.getFlowForDefaultAudience(placementId, params?)`
`adapty.getPaywallProducts(paywall)`	`adapty.getPaywallProducts(flow)`
`adapty.logShowPaywall(paywall)`	`adapty.logShowFlow(flow)`
`AdaptyPaywall` (tipo)	`AdaptyFlow`
`createPaywallView(paywall)`	`createFlowView(flow)`
`AdaptyPaywallView` (componente)	`AdaptyFlowView`
`EventHandlers` (tipo)	`FlowEventHandlers`
`onPaywallShown`	`onAppeared`
`onPaywallClosed`	`onDisappeared`
`onRenderingFailed`	`onError`
`AdaptyPaywallProduct` mantiene su nombre — los productos siguen perteneciendo a un flow, y `getPaywallProducts` ahora acepta un `AdaptyFlow`. Los métodos `getFlow` y `getFlowForDefaultAudience` ya no reciben un parámetro `locale`. Los métodos de vista `present`, `dismiss`, `setEventHandlers` y `showDialog`, y los manejadores de eventos `onCloseButtonPress`, `onUrlPress`, `onCustomAction`, `onProductSelected`, `onPurchaseStarted`, `onPurchaseCompleted`, `onPurchaseFailed`, `onRestoreStarted`, `onRestoreCompleted`, `onRestoreFailed`, `onLoadingProductsFailed`, `onWebPaymentNavigationFinished` y `onAndroidSystemBack` conservan los mismos nombres que en v3. Algunos comportamientos predeterminados han cambiado — consulta Cambios en el comportamiento predeterminado.

Versión mínima de iOS

Adapty React Native SDK 4.0 eleva el deployment target mínimo de iOS 13.0 a iOS 15.0. Establece tu deployment target de iOS en 15.0 o superior antes de actualizar.

Instalación

Actualizar el paquete

v4.0 es una versión previa al lanzamiento, así que fija la versión exacta: npm no selecciona versiones pre-release mediante rangos con caret/tilde:

npm install react-native-adapty@4.0.0
# or
yarn add react-native-adapty@4.0.0

iOS: los SDKs nativos ahora se obtienen a través de Swift Package Manager

El repositorio de specs de CocoaPods pasará a ser de solo lectura en diciembre de 2026, por lo que a partir de la v4 los SDKs nativos Adapty, AdaptyUI y AdaptyPlugin ya no se descargan como sub-dependencias de CocoaPods — el podspec los obtiene a través de Swift Package Manager (mediante el helper spm_dependency). Esto requiere dos cosas:

React Native 0.75 o posterior — necesario para el helper spm_dependency del podspec. Con una versión anterior, pod install falla con un error explícito; actualiza React Native primero, o quédate con react-native-adapty 3.x.
Frameworks dinámicos — las dependencias SPM requieren enlace dinámico. La forma de habilitarlo difiere entre Expo y React Native sin configuración adicional.

Expo

Añade el plugin de configuración expo-build-properties y establece los frameworks de iOS como dinámicos en app.json (o app.config.js):

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "useFrameworks": "dynamic"
          }
        }
      ]
    ]
  }
}

Luego instala el plugin y regenera el proyecto nativo:

npx expo install expo-build-properties
npx expo prebuild --clean

Bare React Native

Añade los frameworks dinámicos a tu target de iOS y reinstala los pods:

use_frameworks! :linkage => :dynamic

cd ios && pod install --repo-update

Si anteriormente incluiste Adapty, AdaptyUI o AdaptyPlugin como sub-dependencias de CocoaPods, elimina primero cualquier línea pod 'Adapty', pod 'AdaptyUI' o pod 'AdaptyPlugin' de tu Podfile.

Cambiar del enlace estático predeterminado a frameworks dinámicos puede entrar en conflicto con bibliotecas que aún no admiten encabezados modulares y es incompatible con Flipper. Si encuentras problemas de compilación, consulta este artículo sobre cómo integrar Swift Package Manager con bibliotecas de React Native.

Consulta Instalar el SDK de Adapty para ver la configuración completa.

Obtención de flows

getPaywall → getFlow

El tipo devuelto cambia de AdaptyPaywall a AdaptyFlow, y se elimina el parámetro locale — cuando renderizas un flow, el idioma se resuelve automáticamente; para paywalls personalizados, todos los idiomas están disponibles en flow.remoteConfigs:

- const paywall = await adapty.getPaywall('YOUR_PLACEMENT_ID', 'en');
+ const flow = await adapty.getFlow('YOUR_PLACEMENT_ID');

getPaywallForDefaultAudience se renombra de la misma forma:

- const paywall = await adapty.getPaywallForDefaultAudience('YOUR_PLACEMENT_ID', 'en');
+ const flow = await adapty.getFlowForDefaultAudience('YOUR_PLACEMENT_ID');

getPaywallProducts(paywall) → getPaywallProducts(flow)

getPaywallProducts mantiene su nombre pero ahora recibe un AdaptyFlow:

- const products = await adapty.getPaywallProducts(paywall);
+ const products = await adapty.getPaywallProducts(flow);

Modelo de datos

getFlow devuelve un AdaptyFlow en lugar de un AdaptyPaywall, y la forma del objeto ha cambiado:

Campo de v3 `AdaptyPaywall`	Campo de v4 `AdaptyFlow`	Acción
`remoteConfig?` (único)	`remoteConfigs?: AdaptyRemoteConfig[]` (array)	Un flow lleva un Remote Config por idioma configurado. Lee el que corresponde al usuario: `flow.remoteConfigs?.find((c) => c.lang === 'en')`.
`products`	`flow.paywalls[i].productIdentifiers`	Los identificadores de producto ahora están en cada variación del flow, no en el flow en sí.
`webPurchaseUrl?`	`flow.paywalls[i].webPurchaseUrl`	Se ha movido del flow a cada variación de paywall.
`version?: number`	`flowVersionId?: string`	Renombrado, y el tipo ha cambiado de `number` a `string`.
`hasViewConfiguration`	eliminado	Elimina cualquier comprobación de `hasViewConfiguration` de tu código.
`requestLocale`	eliminado	La configuración regional ya no forma parte del modelo.
(nuevo)	`paywalls: AdaptyFlowPaywall[]`	Cada entrada es una variación de paywall dentro del flow.
(nuevo)	`responseCreatedAt: number`	Marca de tiempo de la respuesta del servidor, en milisegundos.
Product identifiers moved from the flow to each variation:

- const ids = paywall.products;
+ const ids = flow.paywalls[0].productIdentifiers;

Métodos de paywall web

openWebPaywall y createWebPaywallUrl mantienen sus nombres, pero el primer argumento es ahora un AdaptyFlowPaywall (una variante de flow) en lugar de un AdaptyPaywall. Puedes seguir pasando un AdaptyPaywallProduct.

  const flow = await adapty.getFlow('YOUR_PLACEMENT_ID');
- await adapty.openWebPaywall(paywall);
+ await adapty.openWebPaywall(flow.paywalls[0]);

Seguimiento de visualizaciones de flows

logShowPaywall → logShowFlow

logShowPaywall ha pasado a llamarse logShowFlow y ahora recibe un AdaptyFlow. El evento se sigue registrando contra la misma variación, por lo que las métricas de embudo y las pruebas A/B existentes siguen funcionando sin cambios en el dashboard.

- await adapty.logShowPaywall(paywall);
+ await adapty.logShowFlow(flow);

Al igual que en v3, no es necesario llamar a este método cuando se muestran flows o paywalls renderizados por el Flow Builder o el Paywall Builder — Adapty registra esas vistas automáticamente.

Mostrar flows

createPaywallView → createFlowView

Renombra la función de fábrica y pasa el AdaptyFlow. Los métodos del controlador devuelto (present, dismiss, setEventHandlers, showDialog) no cambian:

- import { createPaywallView } from 'react-native-adapty';
+ import { createFlowView } from 'react-native-adapty';

- const view = await createPaywallView(paywall);
+ const view = await createFlowView(flow);
  await view.present();

AdaptyPaywallView → AdaptyFlowView

Si renderizas con el componente React, renómbralo y pasa el prop flow:

- import { AdaptyPaywallView } from 'react-native-adapty';
+ import { AdaptyFlowView } from 'react-native-adapty';

- <AdaptyPaywallView paywall={paywall} /* … */ />
+ <AdaptyFlowView flow={flow} /* … */ />

Una vista de flow creada con createFlowView es de un solo uso: después de llamar a dismiss(), la vista se destruye, por lo que debes llamar a createFlowView de nuevo para presentar el flow otra vez. Un AdaptyFlowView embebido se descarta desmontándolo — devolver true desde un manejador no cierra una vista embebida, así que cambia tu propio estado en su lugar, por ejemplo en onCloseButtonPress.

Gestión de eventos

La interfaz de gestión de eventos se renombra de EventHandlers a FlowEventHandlers, y tres callbacks también cambian de nombre. No es necesario modificar el código interno de los handlers — solo renómbralos:

- onPaywallShown: () => { /* … */ },
+ onAppeared: () => { /* … */ },

- onPaywallClosed: () => { /* … */ },
+ onDisappeared: () => { /* … */ },

- onRenderingFailed: (error) => { /* … */ },
+ onError: (error) => { /* … */ },

Todos los demás manejadores de eventos conservan sus nombres. Dos también reciben un segundo argumento: onPurchaseCompleted pasa a ser (purchaseResult, product) y onPurchaseFailed pasa a ser (error, product), donde product es el AdaptyPaywallProduct involucrado. Consulta Gestionar eventos de flow y paywall para ver la lista completa.

onDisappeared solo se activa en un flow presentado de forma modal con createFlowView().present(). El componente AdaptyFlowView no lo expone como prop; para cerrar una vista embebida, desmóntala.

La v4 también añade algunas funciones opcionales a las que puedes suscribirte:

Los métodos adapty.openWebUrl(url, openIn?) y adapty.requestAppReview() respaldan los handlers predeterminados onUrlPress y onRequestAppReview, de modo que las URLs y las solicitudes de reseña de la app se gestionan de forma nativa sin configuración adicional. Llámalos directamente solo si sobreescribes esos handlers.
Gestión de compras en modo observador dentro de flows mediante los nuevos handlers onObserverPurchaseInitiated / onObserverRestoreInitiated. Consulta Gestionar compras en modo observador.

APIs eliminadas y obsoletas

setFallbackPaywalls → setFallback

setFallbackPaywalls ha sido eliminado. Usa setFallback, que acepta el mismo argumento:

- await adapty.setFallbackPaywalls(fileLocation);
+ await adapty.setFallback(fileLocation);

Exportaciones eliminadas

Estos símbolos ya no se exportan desde react-native-adapty. Elimina sus importaciones:

AdaptyPaywall: Usa AdaptyFlow en su lugar.
ProductReference: Usa AdaptyProductIdentifier, léelo desde flow.paywalls[i].productIdentifiers.
AdaptyPaywallBuilder: Eliminado. Los flows y paywalls se renderizan de forma nativa.
AdaptyAndroidSubscriptionUpdateParameters: Usa la forma anidada subscriptionUpdateParams (ver más abajo).

activate: lockMethodsUntilReady

lockMethodsUntilReady se ha eliminado y este comportamiento ahora está siempre activo. Elimínalo de tu llamada a activate — mantenerlo ya no compila:

- await adapty.activate('PUBLIC_SDK_KEY', { lockMethodsUntilReady: true });
+ await adapty.activate('PUBLIC_SDK_KEY');

makePurchase: actualización de suscripción en Android

Se elimina la estructura plana de actualización de suscripción en Android. Mueve oldSubVendorProductId y prorationMode a un objeto anidado subscriptionUpdateParams, y mantén isOfferPersonalized en el nivel superior. Consulta Realizar compras para ver el ejemplo completo.

Android: relleno de áreas seguras

El recurso booleano de Android <bool name="adapty_paywall_enable_safe_area_paddings">…</bool> ha sido eliminado. Bórralo de res/values/bools.xml y controla los rellenos de áreas seguras en tiempo de ejecución con el parámetro enableSafeArea al crear el flow view. Su valor predeterminado es true para la presentación modal y false para el componente embebido.

Modo mock

Si ejecutas el SDK en modo mock (Expo Go o vista previa web), renombra la clave de configuración mock paywalls a flows.

Cambios en el comportamiento por defecto

Estos cambios no provocan errores de compilación, así que pruébalos en tiempo de ejecución:

onAndroidSystemBack: El comportamiento por defecto cambió de cerrar la vista a mantenerla abierta. Para restaurar el comportamiento anterior, devuelve true desde el handler.
onPurchaseCompleted: El comportamiento por defecto cambió de cerrar la vista (salvo que el usuario cancelara la compra) a mantenerla siempre abierta. Para restaurar el comportamiento anterior, devuelve purchaseResult.type !== 'user_cancelled' desde el handler.
onRestoreCompleted: El comportamiento por defecto cambió de cerrar la vista tras una restauración exitosa a mantenerla abierta. Para restaurar el comportamiento anterior, devuelve true desde el handler.
onUrlPress: El comportamiento por defecto ahora abre la URL a través de la capa nativa, respetando la configuración de navegador integrado o externo del dashboard. Sobreescribe el handler para gestionar la apertura de URLs tú mismo.

Desuso de la API de onboarding

La API de onboarding heredada está marcada como obsoleta en v4.0 a favor del Flow Builder. Sigue funcionando, y tu IDE señala los símbolos obsoletos a través de sus anotaciones @deprecated — no hay advertencias en tiempo de ejecución. Estos símbolos se eliminarán en una versión futura, así que planifica la migración de tus onboardings al Flow Builder.

Símbolos obsoletos: getOnboarding, getOnboardingForDefaultAudience, createOnboardingView y AdaptyOnboardingView.