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

La línea 4.x introduce flows y renombra las APIs de paywall en consecuencia. Las nuevas APIs funcionan con flows, y también siguen funcionando con paywalls del builder anterior — no se requieren cambios de configuración en el Adapty Dashboard. Además, la versión 4.1 renombra las APIs de atribución externa, convierte la atribución de Adapty en opt-in, añade un método de listener obligatorio y cambia el formato del archivo de respaldo.

Referencia rápida

v3	v4.1
Adapty.GetPaywall(placementId, locale, ...)	Adapty.GetFlow(placementId, ...)
Adapty.GetPaywallForDefaultAudience(placementId, locale, ...)	Adapty.GetFlowForDefaultAudience(placementId, ...)
Adapty.GetPaywallProducts(paywall, ...)	Adapty.GetPaywallProducts(flow, ...)
Adapty.LogShowPaywall(paywall, ...)	Adapty.LogShowFlow(flow, ...)
AdaptyPaywall	AdaptyFlow
AdaptyUI.CreatePaywallView(paywall, ...)	AdaptyUI.CreateFlowView(flow, ...)
AdaptyUICreatePaywallViewParameters	AdaptyUICreateFlowViewParameters
AdaptyUIPaywallView	AdaptyUIFlowView
AdaptyUI.PresentPaywallView(view, ...) / DismissPaywallView(view, ...)	AdaptyUI.PresentFlowView(view, ...) / DismissFlowView(view, ...)
Adapty.SetPaywallsEventsListener(listener)	Adapty.SetFlowsEventsListener(listener)
AdaptyPaywallsEventsListener	IAdaptyFlowsEventsListener
AdaptyEventListener	IAdaptyEventListener, con un nuevo método requerido OnReceivePromotedPurchase
AdaptyOnboardingsEventsListener	IAdaptyOnboardingsEventsListener
PaywallViewDidPerformAction, PaywallViewDidAppear y otros callbacks PaywallView...	FlowViewDidPerformAction, FlowViewDidAppear y otros callbacks FlowView...
PaywallViewDidFailRendering	FlowViewDidReceiveError
Adapty.UpdateAttribution(data, source, ...) con un string source	Adapty.UpdateExternalAttribution(jsonString, provider, ...) con un AdaptyExternalAttributionProvider
AdaptyProfile.AppliedAttributionSources como IReadOnlyList<string>	AdaptyProfile.AppliedExternalAttributionProviders como IReadOnlyList<AdaptyExternalAttributionProvider>
Atribución de Adapty habilitada automáticamente	deshabilitada por defecto — actívala con Builder.SetAdaptyAttributionEnabled(true)
Archivo de respaldo descargado para 3.x	nuevo formato de archivo de respaldo — descarga el archivo de nuevo
Adapty.SetFallbackPaywalls(...) (obsoleto en v3)	eliminado — usa Adapty.SetFallback(fileName, ...)
Builder.SetIDFACollectionDisabled(...) (obsoleto en v3)	eliminado — usa Builder.SetAppleIDFACollectionDisabled(...)
paywall.Products (una lista de AdaptyProductReference)	eliminado — usa ProductIdentifiers o VendorProductIds, o llama a GetPaywallProducts(flow) para obtener productos completos
AdaptyProductReference	eliminado como tipo público — consulta Modelo de datos
paywall.RemoteConfigString	eliminado — usa flow.RemoteConfig?.Data

AdaptyPaywallProduct mantiene su nombre — los productos siguen perteneciendo a un flow, y GetPaywallProducts también mantiene su nombre, ahora tomando un AdaptyFlow. Los métodos GetFlow y GetFlowForDefaultAudience ya no aceptan el parámetro locale. Las APIs de compra y perfil (MakePurchase, RestorePurchases, GetProfile, Identify, UpdateProfile) no cambian. SetFallback mantiene su firma, pero el archivo que lee debe descargarse de nuevo — consulta Archivos de respaldo. Los métodos de onboarding siguen funcionando pero están obsoletos — consulta Deprecación de la API de onboarding. Algunos comportamientos predeterminados han cambiado — consulta Cambios en el comportamiento predeterminado.

Instalación

Para instalar el SDK 4.1 mediante el Unity Package Manager, añade la etiqueta de versión a la URL de Git:

https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk#4.1.0

Si instalas mediante el paquete de Unity, descarga adapty-unity-plugin-4.1.0.unitypackage desde la versión 4.1.0. Consulta Instalar el SDK de Adapty para ver la configuración completa.

Con la versión 4.x llegan dos cambios en la configuración del build:

• Las dependencias de iOS migran a Swift Package Manager. El SDK nativo de Adapty para iOS se declara ahora como paquete Swift remoto en lugar de un pod de CocoaPods. Actualiza el External Dependency Manager a 1.2.188 o posterior, ya que las versiones anteriores no admiten dependencias de Swift Package Manager. Los pasos de CocoaPods (iOS Resolver -> Install Cocoapods, abrir Unity-iPhone.xcworkspace) ya no aplican. Para compilar para iOS ahora se requiere Xcode 26 o posterior, ya que el paquete Swift se compila con Swift tools 6.2.
• El deployment target de iOS debe ser 15.0 o posterior. Un nuevo validador de compilación en el Unity Editor detiene la compilación para iOS si el target es inferior.

Las versiones nativas del SDK de Adapty se actualizan a la 4.x en ambas plataformas y se resuelven automáticamente; no se necesitan cambios adicionales en la compilación.

Recuperar flows

GetPaywall → GetFlow

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

- Adapty.GetPaywall("YOUR_PLACEMENT_ID", "en", (paywall, error) => {
+ Adapty.GetFlow("YOUR_PLACEMENT_ID", (flow, error) => {
      if (error != null) {
          // handle the error
          return;
      }
-     // use the paywall
+     // use the flow
  });

GetPaywallForDefaultAudience se renombra de la misma manera:

- Adapty.GetPaywallForDefaultAudience("YOUR_PLACEMENT_ID", "en", (paywall, error) => { /* ... */ });
+ Adapty.GetFlowForDefaultAudience("YOUR_PLACEMENT_ID", (flow, error) => { /* ... */ });

GetPaywallProducts(paywall) → GetPaywallProducts(flow)

GetPaywallProducts mantiene su nombre pero ahora acepta un AdaptyFlow:

- Adapty.GetPaywallProducts(paywall, (products, error) => {
+ Adapty.GetPaywallProducts(flow, (products, error) => {
      if (error != null) {
          // handle the error
          return;
      }
      // use the products
  });

Modelo de datos

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

Propiedad de AdaptyPaywall en v3	Propiedad de AdaptyFlow en v4	Acción
RemoteConfig (única, nullable)	RemoteConfigs (lista)	Un flow lleva un Remote Config por idioma configurado. Lee el que corresponda al usuario desde flow.RemoteConfigs. El atajo flow.RemoteConfig devuelve la primera entrada.
(nuevo)	Paywalls (lista de AdaptyFlowPaywall)	Cada entrada es una variación de paywall en el flow, con su propio Name, VariationId y ProductIdentifiers. Los métodos de web paywall reciben un AdaptyFlowPaywall; consulta Métodos de web paywall.
ProductIdentifiers, VendorProductIds	se conservan	En AdaptyFlow, estos agregan los productos de todas las variaciones de paywall. Cada variación también expone sus propios ProductIdentifiers y VendorProductIds. Para obtener productos, sigue llamando a GetPaywallProducts(flow).
HasViewConfiguration	eliminado	Elimina cualquier comprobación de HasViewConfiguration de tu código — CreateFlowView devuelve un error en su lugar (consulta Mostrar flows).
Products (lista de AdaptyProductReference)	eliminado	AdaptyProductReference ya no es público, y con él desaparecen los valores PromotionalOfferId, WinBackOfferId y AndroidOfferId que contenía. Usa ProductIdentifiers — una lista de AdaptyProductIdentifier con VendorProductId y el campo exclusivo de Android BasePlanId (el AndroidBasePlanId de v3) — o llama a GetPaywallProducts(flow) cuando necesites objetos AdaptyPaywallProduct completos con precios y ofertas.
RemoteConfigString	eliminado	Lee el string directamente desde el Remote Config: flow.RemoteConfig?.Data, o la entrada correspondiente en flow.RemoteConfigs.
(nuevo)	FlowVersionId (nullable)	El identificador de versión del flow, o null cuando no está disponible.

AdaptyPaywallProduct gana un campo nuevo: FlowProductId, el identificador del producto dentro del flow, que es null para los productos que no pertenecen a un flow.

Métodos de paywall web

OpenWebPaywall y CreateWebPaywallUrl mantienen sus nombres, pero el argumento paywall ahora acepta un AdaptyFlowPaywall — una de las variaciones en flow.Paywalls. Aún puedes pasar un AdaptyPaywallProduct en su lugar:

- Adapty.OpenWebPaywall(paywall, AdaptyWebPresentation.ExternalBrowser, (error) => { /* ... */ });
+ var flowPaywall = flow.Paywalls.FirstOrDefault();
+ if (flowPaywall != null) {
+     Adapty.OpenWebPaywall(flowPaywall, AdaptyWebPresentation.ExternalBrowser, (error) => { /* ... */ });
+ }

Seguimiento de visualizaciones de flows

LogShowPaywall → LogShowFlow

LogShowPaywall pasa 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 siguen funcionando sin cambios en el dashboard.

- Adapty.LogShowPaywall(paywall, (error) => { /* ... */ });
+ Adapty.LogShowFlow(flow, (error) => { /* ... */ });

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

Mostrando flows

CreatePaywallView → CreateFlowView

Renombra el método de fábrica y pasa el AdaptyFlow. El tipo de vista devuelto cambia de AdaptyUIPaywallView a AdaptyUIFlowView, pero sus métodos (Present, Dismiss) no cambian, y el objeto de parámetros opcionales mantiene los mismos campos (LoadTimeout, PreloadProducts, CustomTags, CustomTimers, CustomAssets, ProductPurchaseParameters) bajo el nuevo nombre AdaptyUICreateFlowViewParameters, además de dos nuevos — Locale y EnableSafeAreaPaddings:

- AdaptyUI.CreatePaywallView(paywall, parameters, (view, error) => {
+ AdaptyUI.CreateFlowView(flow, parameters, (view, error) => {
      if (error != null) {
          // handle the error
          return;
      }
      view.Present((error) => { /* handle the error */ });
  });

CreateFlowView devuelve un error si el flow no tiene ninguna vista configurada — esto reemplaza la comprobación HasViewConfiguration de v3:

- if (paywall.HasViewConfiguration) {
-     AdaptyUI.CreatePaywallView(paywall, null, (view, error) => { /* ... */ });
- }
+ AdaptyUI.CreateFlowView(flow, (view, error) => {
+     if (error != null) {
+         // the flow has no view configured, or view creation failed
+         return;
+     }
+     view.Present((error) => { /* handle the error */ });
+ });

Rellenos de área segura en Android

AdaptyUICreateFlowViewParameters añade EnableSafeAreaPaddings, que controla los rellenos de área segura en Android en tiempo de ejecución. Se ignora en iOS y su valor predeterminado es true:

var parameters = new AdaptyUICreateFlowViewParameters()
    .SetEnableSafeAreaPaddings(false);

Manejo de eventos

Las interfaces de listener siguen ahora la convención de prefijo I de C#, y no se mantienen alias heredados; renombra AdaptyEventListener a IAdaptyEventListener y AdaptyOnboardingsEventsListener a IAdaptyOnboardingsEventsListener en todos los lugares donde las implementes.

El listener de eventos de flow se renombra de AdaptyPaywallsEventsListener a IAdaptyFlowsEventsListener, su método de registro de SetPaywallsEventsListener a SetFlowsEventsListener, y sus callbacks cambian el prefijo PaywallView por FlowView. Los cuerpos de los handlers existentes no necesitan cambios de código: solo hay que renombrar la interfaz y los métodos:

- public class MyListener : MonoBehaviour, AdaptyPaywallsEventsListener {
-     public void PaywallViewDidFinishPurchase(
-         AdaptyUIPaywallView view,
+ public class MyListener : MonoBehaviour, IAdaptyFlowsEventsListener {
+     public void FlowViewDidFinishPurchase(
+         AdaptyUIFlowView view,
          AdaptyPaywallProduct product,
          AdaptyPurchaseResult purchasedResult
      ) {
          // custom logic after purchase
      }
      // ...
  }

- Adapty.SetPaywallsEventsListener(myListener);
+ Adapty.SetFlowsEventsListener(myListener);

Un callback ha sido renombrado: PaywallViewDidFailRendering pasa a llamarse FlowViewDidReceiveError. Se activa para los mismos errores de renderizado que antes, además de otros errores de ejecución no relacionados con compras:

- public void PaywallViewDidFailRendering(AdaptyUIPaywallView view, AdaptyError error) { }
+ public void FlowViewDidReceiveError(AdaptyUIFlowView view, AdaptyError error) { }

Consulta Gestionar eventos de flow y paywall para ver la lista completa de callbacks.

Nuevo método obligatorio: OnReceivePromotedPurchase

A partir de la versión 4.1 del SDK, IAdaptyEventListener tiene un método adicional, por lo que cualquier clase que lo implemente dejará de compilar hasta que añadas:

public void OnReceivePromotedPurchase(AdaptyPromotedProduct product) {
    // The user tapped one of your in-app purchases on your App Store product page.
    // Complete the purchase through Adapty:
    Adapty.MakePromotedPurchase(product, (result, error) => { /* ... */ });
}

Este método es para compras in-app promocionadas en el App Store y nunca se llama en Android. No dejes el cuerpo vacío: en iOS 16.4 y versiones posteriores, el SDK entrega la compra aquí y espera a que la completes, por lo que un cuerpo vacío descarta una compra que el usuario ya había iniciado. Las versiones anteriores completaban este tipo de compras automáticamente. Consulta Compras in-app promocionadas desde el App Store.

Nuevas APIs

• Adapty.SetObserverModeResolver(...) con un IAdaptyUIObserverModeResolver — gestiona compras y restauraciones iniciadas desde flows cuando el SDK funciona en modo Observer. Antes esto solo estaba disponible en los SDKs nativos de iOS y Android. Consulta Presentar flows en modo Observer.
• Adapty.SetSystemRequestsHandler(...) con un IAdaptyUISystemRequestsHandler — reservado para solicitudes del sistema desde un flow: prompts de permisos del SO (FlowViewDidAskPermission) y solicitudes de valoración de la app (FlowViewDidRequestAppReview). Los flows aún no activan estas solicitudes, por lo que no necesitas registrar un handler.
• AdaptyUICreateFlowViewParameters.Locale (configúralo con SetLocale) — renderiza un flow o paywall con una localización del Builder específica en lugar de la predeterminada del flow. Un flow se localiza cuando se crea su vista, así que este es el único lugar donde elegir su localización; la vista creada reporta la localización con la que fue construida en view.Locale. Consulta Usar localizaciones y códigos de idioma.
• El nuevo callback FlowViewDidReceiveAnalyticEvent en IAdaptyFlowsEventsListener reporta eventos de análisis desde un flow, empezando por una vista de pantalla para cada pantalla que abre el usuario. Consulta Rastrear vistas de pantalla de flows.
• AdaptyUI.OpenUrl(url, openIn, ...) y AdaptyUI.RequestAppReview(...) — el comportamiento nativo detrás de las acciones open_url y las solicitudes de valoración de la app. Llama a OpenUrl desde FlowViewDidPerformAction para mantener el comportamiento predeterminado de URLs; RequestAppReview respalda el prompt de valoración predeterminado, que los flows aún no activan.

APIs de atribución externa renombradas

A partir de la versión 4.1 del SDK, las APIs para pasar datos de atribución desde un proveedor externo (Adjust, AppsFlyer, Branch, Tenjin o uno personalizado) se han renombrado para coincidir con los SDKs nativos, y el proveedor pasa de ser una cadena de texto a un tipo. No existen alias obsoletos, por lo que los puntos de llamada existentes dejan de compilar hasta que los actualices:

Antes de 4.1	4.1
Adapty.UpdateAttribution(data, source, ...)	Adapty.UpdateExternalAttribution(jsonString, provider, ...)
source como string	provider como AdaptyExternalAttributionProvider
AdaptyProfile.AppliedAttributionSources como IReadOnlyList<string>	AdaptyProfile.AppliedExternalAttributionProviders como IReadOnlyList<AdaptyExternalAttributionProvider>

Renombrar el método no es suficiente — cambia también el argumento del proveedor en la misma edición:

- Adapty.UpdateAttribution(attributionJsonString, "adjust", (error) => { /* ... */ });
+ Adapty.UpdateExternalAttribution(attributionJsonString, AdaptyExternalAttributionProvider.Adjust, (error) => { /* ... */ });

AdaptyExternalAttributionProvider lleva el identificador con el que el backend reconoce al proveedor, con seis instancias compartidas: AppleAds (apple_search_ads), Adjust, Appsflyer, Branch, Tenjin y Custom. Para un proveedor que Adapty añada después de esta versión del SDK, constrúyelo a partir de su identificador — new AdaptyExternalAttributionProvider("your_provider") — y llegará al backend sin cambios. Los espacios en blanco alrededor se eliminan automáticamente.

Los datos de atribución se envían como una cadena JSON serializada. Si los tienes en forma de diccionario, serialízalos primero:

var attributionJsonString = Newtonsoft.Json.JsonConvert.SerializeObject(attribution);

En el lado del perfil, lee los proveedores aplicados a través del nuevo tipo:

- if (profile.AppliedAttributionSources.Contains("apple_search_ads")) {
+ if (profile.AppliedExternalAttributionProviders.Contains(AdaptyExternalAttributionProvider.AppleAds)) {
      // Apple Ads attribution has been applied
  }

La atribución de Adapty está desactivada por defecto

En versiones anteriores, el SDK registraba las instalaciones para Adapty Attribution de forma automática. A partir de la versión 4.1 del SDK, esto está desactivado por defecto: el SDK no registra instalaciones, los callbacks OnInstallationDetailsSuccess y OnInstallationDetailsFail nunca se ejecutan, y GetCurrentInstallationStatus devuelve el estado NotAvailable.

Si usas Adapty Attribution, actívalo al inicializar el SDK:

var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAdaptyAttributionEnabled(true);

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

Archivos de respaldo

El formato del archivo de respaldo cambió en el SDK 4.1. Descarga de nuevo los archivos de respaldo de iOS y Android desde Placements > Fallbacks y reemplaza los que tengas en Assets/StreamingAssets, aunque ya los hayas descargado para una versión anterior.

Cambios en el comportamiento predeterminado

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

• Finalización de la compra: En v3, la vista se cerraba automáticamente tras una compra exitosa. En v4, un flow permanece abierto tras una compra o un error hasta que lo cierres tú — el SDK no aplica ningún comportamiento por defecto. Llama a view.Dismiss(...) en FlowViewDidFinishPurchase una vez que el usuario obtenga acceso.
• Botón Atrás de Android: El botón Atrás del sistema (o el gesto de retroceso) se entrega a FlowViewDidPerformAction como una acción SystemBack y ya no cierra un flow por sí solo — igual que en iOS, donde un flow no puede cerrarse con un gesto del sistema. Ofrece a los usuarios una salida explícita (un botón Close o una acción on_device_back), o cierra la vista tú mismo al gestionar la acción.
• 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.
• Transacciones en modo Observer: ReportTransaction ya no devuelve un error de decodificación cuando tiene éxito — en v3 la respuesta de éxito se parseaba incorrectamente, por lo que un reporte exitoso siempre terminaba con un error.

Obsolescencia de la API de onboarding

La API de onboarding heredada está en desuso 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 en desuso: GetOnboarding, GetOnboardingForDefaultAudience, AdaptyUI.CreateOnboardingView, AdaptyUI.PresentOnboardingView, AdaptyUI.DismissOnboardingView y Adapty.SetOnboardingsEventsListener.