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

El SDK de React Native de Adapty 4.0 introduce los flows y renombra 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` conserva su nombre — los productos siguen perteneciendo a un flow, y `getPaywallProducts` ahora toma un `AdaptyFlow`. Los métodos `getFlow` y `getFlowForDefaultAudience` ya no aceptan el parámetro `locale` — pásalo a `createFlowView` en su lugar. Los métodos de la 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` mantienen los mismos nombres que en v3. Algunos comportamientos por defecto han cambiado — consulta Cambios en el comportamiento por defecto.

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.2
# or
yarn add react-native-adapty@4.0.2

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",
            "buildReactNativeFromSource": true
          }
        }
      ]
    ]
  }
}

buildReactNativeFromSource es obligatorio en Expo SDK 57 y versiones posteriores. Expo SDK 57 incluye un framework de React Native precompilado cuyos encabezados no son accesibles para otros paquetes cuando los frameworks son dinámicos, por lo que la compilación de iOS falla con errores como 'React/RCTBridge.h' file not found en expo-updates o @expo/ui. Compilar React Native desde el código fuente evita el conflicto, aunque aumenta el tiempo de compilación en iOS. En Expo SDK 56 y versiones anteriores, puedes omitir esta opción.

A continuación, instala el plugin y regenera el proyecto nativo:

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

Bare React Native

Añade frameworks dinámicos a tu target de iOS y luego 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.

Warning

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 el parámetro locale se traslada de la llamada de obtención a createFlowView; para paywalls personalizados, todas las configuraciones regionales se devuelven en flow.remoteConfigs:

- const paywall = await adapty.getPaywall('YOUR_PLACEMENT_ID', 'en');
+ const flow = await adapty.getFlow('YOUR_PLACEMENT_ID');
+ const view = await createFlowView(flow, { locale: 'en' });

locale es opcional en createFlowView: si se omite, la vista se renderiza en en, o en la localización predeterminada del flow si no tiene en. Requiere el SDK 4.0.2 o posterior; consulta Localizaciones y códigos de idioma.

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);

Archivos de respaldo

El formato del archivo de respaldo cambió en el SDK v4. Descarga el nuevo archivo desde Placements > Fallbacks y agrégalo a tu app.

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} /* … */ />

Note

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.

Note

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.