El SDK de Adapty Capacitor 4.1.1 es la versión estable actual de la línea 4.x — la 4.0 se publicó solo como beta, así que si estás en 3.x, migra directamente a la 4.1.1. Esta guía cubre toda la migración: los flows introducidos en la 4.0 y los cambios de la 4.1.1 sobre ellos.

La línea 4.x introduce los flows y renombra las APIs de paywall en consecuencia. Las nuevas APIs funcionan con flows y siguen siendo compatibles con los paywalls del antiguo builder — no se requieren cambios de configuración en el Adapty Dashboard. Además, la versión 4.1.1 hace que Adapty Attribution sea opt-in, renombra el método de atribución externa, cambia el formato del archivo de respaldo y añade las compras in-app promocionadas de App Store.

Referencia rápida

v3	v4.1.1
Adapty Attribution habilitado automáticamente	deshabilitado por defecto — actívalo con adaptyAttributionEnabled: true
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 + AdaptyFlowPaywall
createPaywallView(paywall, params?)	createFlowView(flow, params?)
PaywallViewController	FlowViewController
EventHandlers (tipo)	FlowEventHandlers
CreatePaywallViewParamsInput	CreateFlowViewParamsInput
onRenderingFailed	onError
adapty.updateAttribution({ attribution, source })	adapty.updateExternalAttribution({ attribution, provider })
AdaptyProfile.appliedAttributionSources	AdaptyProfile.appliedExternalAttributionProviders
AttributionSource	AdaptyExternalAttributionProvider
Archivo de respaldo descargado para 3.x	nuevo formato de archivo de respaldo — descarga el archivo de nuevo
Las compras in-app promocionadas se completaban automáticamente, sin posibilidad de interceptarlas	el evento 'onPromotedPurchaseReceived' y adapty.makePromotedPurchase({ product }) delegan la finalización a tu app

AdaptyPaywallProduct conserva su nombre — los productos siguen perteneciendo a un flow, y getPaywallProducts también conserva su nombre, ahora tomando un AdaptyFlow. Los métodos getFlow y getFlowForDefaultAudience ya no aceptan el parámetro locale — pásalo a createFlowView en su lugar. Las APIs de compra y perfil (makePurchase, restorePurchases, getProfile, identify, updateProfile) y setFallback mantienen las mismas firmas, pero el archivo de respaldo debe descargarse de nuevo — consulta Archivos de respaldo. Los métodos de vista present, dismiss, setEventHandlers, clearEventHandlers 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. Los métodos de onboarding siguen funcionando pero están obsoletos — consulta Obsolescencia de la API de onboarding. Algunos comportamientos predeterminados han cambiado — consulta Cambios en el comportamiento predeterminado.

Versiones mínimas

Los requisitos en tiempo de ejecución no han cambiado desde v3.16+: iOS 15.0, Android minSdk 24 y Capacitor 8. No es necesario modificar el deployment target.

Hay un nuevo requisito de compilación: Xcode 26 o posterior — el SDK nativo de Adapty para iOS incluido en esta versión utiliza Swift tools 6.2.

Instalación

Actualiza el paquete

npm install @adapty/capacitor@latest

Luego sincroniza los proyectos nativos:

npx cap sync

iOS: solo 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 se elimina el AdaptyCapacitor.podspec y el SDK se instala en iOS únicamente a través de Swift Package Manager (SPM). El proyecto iOS de tu app debe utilizar la integración SPM de Capacitor:

• Aplicaciones nuevas: añade la plataforma iOS con el gestor de paquetes SPM:

npx cap add ios --packagemanager SPM

• Aplicaciones existentes basadas en CocoaPods: migra el proyecto iOS siguiendo la guía de Capacitor para usar SPM en un proyecto existente.

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

⚠️ La atribución de Adapty está desactivada por defecto

En versiones anteriores, el SDK registraba las instalaciones para Atribución de Adapty automáticamente. A partir de la versión 4.1.1 del SDK, esto está desactivado por defecto: el SDK no registra instalaciones, los eventos 'onInstallationDetailsSuccess' y 'onInstallationDetailsFail' nunca se disparan, y getCurrentInstallationStatus devuelve el estado not_available.

Si utilizas Atribución de Adapty, actívalo al inicializar el SDK:

  await adapty.activate({
    apiKey: 'YOUR_PUBLIC_SDK_KEY',
    params: {
+     adaptyAttributionEnabled: true,
    },
  });

Si no usas Adapty Attribution, no es necesario hacer ningún cambio.

Obtener flows

getPaywall → getFlow

El tipo devuelto cambia de AdaptyPaywall a AdaptyFlow, y la opción locale se traslada de la llamada de obtención a createFlowView; para paywalls personalizados, todos los locales se devuelven en flow.remoteConfigs:

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

locale es opcional en createFlowView: omítelo y la vista se renderizará en en, o en la localización predeterminada del flow cuando el flow no tenga en. Debido a ese fallback, la vista puede renderizarse en una localización distinta a la que solicitaste — la nueva propiedad FlowViewController.locale informa cuál se usó. Consulta Localizaciones y códigos de idioma.

getPaywallForDefaultAudience se renombra de la misma manera:

- const paywall = await adapty.getPaywallForDefaultAudience({ placementId: 'YOUR_PLACEMENT_ID', locale: 'en' });
+ const flow = await adapty.getFlowForDefaultAudience({ placementId: '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 la versión 4.0 y de nuevo en la 4.1.1. Descarga el archivo otra vez desde Placements > Fallbacks y agrégalo a tu app, aunque ya hayas descargado uno para una beta de la versión 4.0.

Modelo de datos

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

Campo v3 AdaptyPaywall	Campo v4 AdaptyFlow	Acción
remoteConfig? (único)	remoteConfigs?: AdaptyRemoteConfig[] (array)	Un flow lleva un Remote Config por idioma configurado. Lee el que coincida con el usuario: flow.remoteConfigs?.find((c) => c.lang === 'en').
productIdentifiers	flow.paywalls[i].productIdentifiers	Los identificadores de producto ahora están en cada variación del flow, no en el flow en sí.
products (obsoleto en v3)	eliminado	Usa flow.paywalls[i].productIdentifiers, o llama a getPaywallProducts(flow) para obtener los productos completos. ProductReference se ha eliminado como tipo público.
webPurchaseUrl?	flow.paywalls[i].webPurchaseUrl	Movido del flow a cada variación del paywall.
version?: number	flowVersionId?: string	Renombrado, y el tipo cambió de number a string.
requestLocale	eliminado	El idioma ya no forma parte del modelo.
(nuevo)	paywalls: AdaptyFlowPaywall[]	Cada entrada es una variación de paywall en el flow.
(nuevo)	responseCreatedAt: number	Marca de tiempo de la respuesta del servidor, en milisegundos.

requestLocale permanece en AdaptyOnboarding — solo el modelo de flow lo elimina.

Los identificadores de producto se han movido del flow a cada variación:

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

Si tu código aún lee paywall.products — obsoleto en v3 y ahora eliminado — cambia a productIdentifiers, o llama a getPaywallProducts(flow) cuando necesites los productos completos en lugar de los identificadores.

Métodos de paywall web

openWebPaywall y createWebPaywallUrl mantienen sus nombres, pero la opción paywallOrProduct ahora acepta un AdaptyFlowPaywall (una variante de flow) en lugar de un AdaptyPaywall. Todavía puedes pasar un AdaptyPaywallProduct. Asegúrate de que flow.paywalls no esté vacío antes de leer la primera entrada:

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

Seguimiento de vistas de flow

logShowPaywall → logShowFlow

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

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

Al igual que en la v3, no es necesario llamar a este método al mostrar flows o paywalls renderizados por Adapty — Adapty registra esas vistas automáticamente.

Mostrar flows

createPaywallView → createFlowView

Cambia el nombre de la función de fábrica y pasa el AdaptyFlow. El controlador retornado pasa de llamarse PaywallViewController a FlowViewController, pero sus métodos (present, dismiss, setEventHandlers, clearEventHandlers y showDialog) no cambian. El tipo de parámetros se renombra de CreatePaywallViewParamsInput a CreateFlowViewParamsInput:

- import { createPaywallView } from '@adapty/capacitor';
+ import { createFlowView } from '@adapty/capacitor';

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

Nuevos parámetros

CreateFlowViewParamsInput conserva todos los parámetros de v3 (prefetchProducts, loadTimeoutMs, customTags, customTimers, customAssets, productPurchaseParams) y añade tres:

Parámetro	Descripción
locale	La localización con la que se renderiza el flow. Se trasladó aquí desde getPaywall — consulta getPaywall → getFlow.
customLayoutId	El ID personalizado de un layout en la configuración de layouts del flow. Pásalo para renderizar ese layout concreto en lugar del que el SDK selecciona automáticamente según el tipo de dispositivo y el tamaño de pantalla. Si ningún layout coincide con el ID, la llamada falla con un error de no-view-configuration. El Flow & Paywall Builder todavía no asigna IDs de layout personalizados, así que deja este campo sin definir.
android.enableSafeArea	Controla los márgenes de área segura de Android en tiempo de ejecución. Se anida bajo la clave android y tiene el valor predeterminado true.

const view = await createFlowView(flow, {
  locale: 'en',
  customLayoutId: 'tablet_landscape',
  android: { enableSafeArea: true },
});

Manejo de eventos

La interfaz del manejador de eventos pasa de llamarse EventHandlers a FlowEventHandlers, y un callback también cambia de nombre. El cuerpo de los manejadores existentes no necesita modificaciones — solo renombra:

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

Todos los demás manejadores de eventos conservan sus nombres. Uno cambia su firma: onAppeared ahora es (view) en lugar de (), donde view es un FlowEventView que describe la vista que apareció, incluyendo la localización con la que fue construida. Los manejadores existentes seguirán funcionando, ya que ignoran el nuevo argumento. Consulta Gestionar eventos de flow y paywall para ver la lista completa.

v4 también añade algunas funcionalidades que puedes activar de forma opcional:

• adapty.openWebUrl({ url, openIn }) y adapty.requestAppReview() — estos métodos respaldan los handlers predeterminados onUrlPress y onRequestAppReview, de modo que las URLs y las solicitudes de valoración de la app se gestionan de forma nativa sin configuración adicional. Llámalos directamente solo si reemplazas esos handlers.
• Gestión de compras en Observer mode dentro de flows mediante los nuevos handlers onObserverPurchaseInitiated / onObserverRestoreInitiated. Consulta Presentar flows en Observer mode.
• onAnalytics: (name, params) — eventos de analíticas que emite un flow, comenzando con una vista de pantalla por cada pantalla que abre el usuario. Consulta Rastrear vistas de pantalla de flows.
• onRequestPermission: (permission, customArgs) — reservado para solicitudes de permisos del sistema (como notificaciones push o acceso a la cámara) desde un flow. Los flows aún no disparan solicitudes de permisos, por lo que no es necesario implementarlo.

Además, la versión 4.1.1 añade un evento a nivel de SDK en lugar de un manejador de flow: 'onPromotedPurchaseReceived', entregado a través de adapty.addListener. Si no hay ningún listener registrado, el SDK completa la compra promocionada por sí mismo; si se registra uno, la finalización pasa a tu aplicación. Consulta Compras in-app promocionadas en App Store.

APIs de atribución externa renombradas

A partir de la versión 4.1.1 del SDK, las APIs para pasar datos de atribución desde un proveedor externo (Adjust, AppsFlyer, Branch, Tenjin o uno personalizado) han sido renombradas para coincidir con los SDKs nativos. No existen alias obsoletos, por lo que los sitios de llamada existentes dejarán de funcionar hasta que los renombres:

Antes de 4.1.1	4.1.1
adapty.updateAttribution({ attribution, source })	adapty.updateExternalAttribution({ attribution, provider })
AttributionSource	AdaptyExternalAttributionProvider
AdaptyProfile.appliedAttributionSources	AdaptyProfile.appliedExternalAttributionProviders

updateAttribution → updateExternalAttribution

El método ha sido renombrado y su opción source pasa a llamarse provider. Los datos de atribución siguen siendo un objeto plano:

- await adapty.updateAttribution({ attribution, source: 'adjust' });
+ await adapty.updateExternalAttribution({ attribution, provider: 'adjust' });

AttributionSource → AdaptyExternalAttributionProvider

El tipo de proveedor cambia de nombre. Sigue siendo una unión abierta — los valores predefinidos son 'apple_search_ads', 'adjust', 'appsflyer', 'branch' y 'tenjin', y cualquier otra cadena es válida, de modo que un proveedor que Adapty añada más adelante funciona sin actualizar el SDK:

- import type { AttributionSource } from '@adapty/capacitor';
+ import type { AdaptyExternalAttributionProvider } from '@adapty/capacitor';

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

La propiedad del perfil que lista los proveedores de atribución aplicados al perfil ha sido renombrada, y el tipo de sus elementos cambia en consecuencia:

- if (profile.appliedAttributionSources?.includes('apple_search_ads')) {
+ if (profile.appliedExternalAttributionProviders?.includes('apple_search_ads')) {
      // Apple Ads attribution has been applied
  }

El código que la lee necesita actualizarse — consulta Mostrar un paywall segmentado con Apple Ads.

Compras in-app promocionadas en la App Store

Antes de la versión 4.1.1, una compra in-app promocionada en la página de tu producto en la App Store se completaba por sí sola y Adapty registraba la transacción, pero tu app no tenía forma de interceptarla. La versión 4.1.1 añade ese gancho, por lo que se trata de una nueva funcionalidad y no de un paso de migración: si no añades código propio, el SDK sigue completando las compras promocionadas por ti.

Escribe código solo para encargarte tú mismo de la finalización — por ejemplo, para mostrar primero una pantalla. Registra un listener para el nuevo evento 'onPromotedPurchaseReceived' y completa la compra con adapty.makePromotedPurchase. Mientras ese listener esté registrado, el SDK deja de completar las compras promocionadas por ti.

Cambios en el comportamiento predeterminado

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

• onAndroidSystemBack: El comportamiento predeterminado cambió de cerrar la vista a mantenerla abierta. Para restaurar el comportamiento anterior, devuelve true desde el handler.
• onPurchaseCompleted: El comportamiento predeterminado 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 predeterminado cambió de cerrar la vista tras una restauración exitosa a mantenerla abierta. Para restaurar el comportamiento anterior, devuelve true desde el handler.
• onUrlPress: Ahora el comportamiento predeterminado abre la URL a través de la capa nativa, respetando la configuración de navegador integrado o externo del dashboard. Reemplaza el handler para abrir URLs tú mismo.
• Las vistas son de un solo uso: Después de dismiss(), la vista se destruye. Llama a createFlowView de nuevo para mostrar el flow otra vez.

APIs eliminadas

Exportaciones eliminadas

Estos símbolos ya no se exportan desde @adapty/capacitor. Elimina sus importaciones:

• AdaptyPaywall: Usa AdaptyFlow y AdaptyFlowPaywall 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 de parámetros de compra android (ver más abajo).

activate: lockMethodsUntilReady

lockMethodsUntilReady (ya obsoleto y sin efecto en v3) ha sido eliminado. Quítalo de tu llamada a activate — mantenerlo ya no compila:

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

makePurchase: parámetros de Android

La forma plana obsoleta de MakePurchaseParamsInput para Android ha sido eliminada; solo queda la forma anidada. Mueve los parámetros de compra de Android a params: { android: { ... } }. Consulta Realizar compras para ver el ejemplo completo.

Obsolescencia de la API de onboarding

La API de onboarding heredada está obsoleta en v4 en favor del Flow & Paywall Builder. Sigue funcionando, pero se eliminará en una versión futura, así que planifica la migración de tus onboardings al Flow & Paywall Builder.

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