Migrar el SDK de Flutter de Adapty a v4.1

El SDK de Flutter de Adapty 4.1 cambia la forma en que se activa Adapty Attribution, renombra las APIs de atribución externa y cambia el formato del archivo de respaldo. Además, delega a tu app las compras in-app promovidas en App Store y añade una forma de mantener una vista de flow activa tras cerrarla.

Warning

Las APIs renombradas son un cambio definitivo. Los nombres anteriores se han eliminado por completo — no existen alias deprecados que los sustituyan. El código que compilaba con 4.0.x fallará en 4.1 hasta que renombres cada llamada indicada a continuación.

Si todavía usas la versión 3.x, empieza por Migrar a v4.0 y luego sigue esta guía.

Referencia rápida

v4.0	v4.1
Atribución de Adapty habilitada automáticamente	Atribución de Adapty deshabilitada por defecto; actívala con `withAdaptyAttributionEnabled(true)`
`Adapty().updateAttribution(attribution, source: source)`	`Adapty().updateExternalAttribution(attribution, provider: provider)`
`AdaptyAttributionSource`	`AdaptyExternalAttributionProvider`, con un nuevo valor `custom`
`AdaptyProfile.appliedAttributionSources`	`AdaptyProfile.appliedExternalAttributionProviders`
Archivo de respaldo descargado para 4.0	Nuevo formato de archivo de respaldo; descarga el archivo de nuevo
Las compras in-app promocionadas se completaban solas	Tu app las completa desde `didReceivePromotedPurchaseStream`
`dismissFlowView(view)` siempre libera la vista	`destroy: false` mantiene la vista activa para presentarla de nuevo

Las API de compra, perfil y presentación de flows no han cambiado.

Instalación

Actualiza adapty_flutter a la versión 4.1 en tu pubspec.yaml:

dependencies:
  adapty_flutter: 4.1.0

Si tu app usa el Modo Kids, especifica adapty_flutter_kids en su lugar:

dependencies:
  adapty_flutter_kids: 4.1.0

Los requisitos no cambian respecto a la versión 4.0: Flutter 3.32.0 (Dart 3.8.0) e iOS 15.0. Consulta Instalar el SDK de Adapty para la configuración completa.

4.1 fija el SDK nativo de iOS en 4.1.3 y el SDK nativo de Android en 4.1.1. La versión de iOS también corrige los parámetros numéricos de los eventos analíticos de flows: antes de esta versión, todos los 0 y 1 llegaban a flowViewDidReceiveAnalyticEvent como false y true.

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

Warning

Si actualizas al SDK 4.1 y no te das de alta, la atribución de Adapty deja de funcionar silenciosamente: las instalaciones dejan de registrarse y no recibes ningún aviso.

A partir de la versión 4.0 y anteriores, el SDK registraba las instalaciones para Adapty Attribution de forma automática. Desde la versión 4.1, esto está desactivado por defecto: el SDK no registra instalaciones, onUpdateInstallationDetailsSuccessStream y onUpdateInstallationDetailsFailStream no emiten nunca, y getCurrentInstallationStatus devuelve AdaptyInstallationStatusNotAvailable.

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

  await Adapty().activate(
-   configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY'),
+   configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
+     ..withAdaptyAttributionEnabled(true),
  );

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

APIs de atribución externa renombradas

Las APIs que envían datos de atribución desde un proveedor externo (Adjust, AppsFlyer, Branch, Tenjin o uno personalizado) se han renombrado para coincidir con los SDKs nativos.

updateAttribution → updateExternalAttribution

El método ha sido renombrado y su parámetro source pasa a llamarse provider. El parámetro ahora acepta un AdaptyExternalAttributionProvider en lugar de una cadena de texto, y los datos de atribución siguen siendo un mapa:

- await Adapty().updateAttribution(attribution, source: 'adjust');
+ await Adapty().updateExternalAttribution(attribution, provider: AdaptyExternalAttributionProvider.adjust);

AdaptyAttributionSource → AdaptyExternalAttributionProvider

El tipo de proveedor ha sido renombrado. Sigue siendo un contenedor abierto sobre una cadena — los valores predefinidos son appleAds, adjust, appsflyer, branch, tenjin, y un nuevo custom para proveedores con los que Adapty no se integra directamente. Puedes construir uno a partir de cualquier otra cadena, por lo que un proveedor que Adapty añada más adelante funcionará sin necesidad de actualizar el SDK:

final provider = AdaptyExternalAttributionProvider('my_provider');

AdaptyProfile.appliedAttributionSources → appliedExternalAttributionProviders

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

- if (profile.appliedAttributionSources.contains(AdaptyAttributionSource.appleAds)) {
+ if (profile.appliedExternalAttributionProviders.contains(AdaptyExternalAttributionProvider.appleAds)) {
      // Apple Ads attribution has been applied
  }

El campo de perfil serializado mantiene el nombre applied_attribution_sources, por lo que un backend que lea el perfil en bruto no necesita cambios. El código que lee la propiedad sí necesita actualizarse — consulta Mostrar un paywall con segmentación de Apple Ads.

Archivos de respaldo

El formato del archivo de respaldo cambió en el SDK 4.1. Descarga el archivo nuevamente desde Placements > Fallbacks y añádelo a tu app, aunque ya hayas descargado uno para la versión 4.0.

Warning

Este paso no genera ningún error de compilación. Si lo omites, el SDK rechazará el archivo obsoleto y todos los placements perderán su respaldo.

⚠️ Las compras in-app promocionadas ahora esperan a tu app

Warning

Este es un cambio de comportamiento, no una nueva función para adoptar cuando sea conveniente. En la versión 4.0, una compra in-app promocionada en la página de tu producto en el App Store se completaba sola. En la versión 4.1, solo se completa si tu app la escucha. Publica la versión 4.1 sin el código que aparece a continuación y esas compras dejarán de ocurrir: el App Store le entrega el producto a tu app y no sucede nada más.

En la versión 4.0, Adapty registraba una compra promocionada como cualquier otra transacción, y tu app no tenía forma de interceptarla. La versión 4.1 le da a tu app ese control, y con él la responsabilidad de completar la compra.

Suscríbete a didReceivePromotedPurchaseStream y pasa el producto a makePromotedPurchase:

Adapty().didReceivePromotedPurchaseStream.listen((product) async {
  try {
    final result = await Adapty().makePromotedPurchase(product: product);
    // process the purchase result
  } on AdaptyError catch (e) {
    // handle the error
  }
});

Suscríbete antes de que pueda llegar una compra promocionada — durante el inicio de la app, justo después de activate. El stream es un broadcast stream que no reproduce eventos pasados: un producto entregado mientras no hay nadie escuchando se descarta y la compra se pierde.

makePromotedPurchase no recibe parámetros de compra, ya que un producto promocionado proviene del App Store y no de un paywall, y no lleva contexto de paywall. Devuelve el mismo AdaptyPurchaseResult que makePurchase.

Warning

El stream está construido sobre StoreKit 2 y requiere iOS 16.4 o posterior. En versiones anteriores a iOS 16.4 y en Android, nunca emite eventos.

Si el producto promocionado incluye una oferta de suscripción, el SDK la aplica automáticamente al realizar la compra. La oferta se obtiene del intent de compra de App Store, que la expone en iOS 18.0 y versiones posteriores. En iOS 16.4–17.x, la compra se realiza al precio base.

Mantener activa una vista de flow después de cerrarla

AdaptyUI().dismissFlowView y AdaptyUIFlowView.dismiss aceptan un flag destroy:

await AdaptyUI().dismissFlowView(view, destroy: false);

Por defecto es true, lo que libera la vista como antes. Con destroy: false la vista permanece activa, de modo que puedes volver a mostrarla y el usuario regresa a la pantalla donde lo dejó, con el estado que el flow había acumulado.

Una vista conservada de esta forma se mantiene hasta que la cierras con destroy: true. Presentar una vista liberada falla, así que llama de nuevo a createFlowView para mostrar ese flow otra vez.

hasViewConfiguration

AdaptyFlow.hasViewConfiguration ahora también requiere que el flow lleve un esquema de interfaz, por lo que devuelve true únicamente para un flow que AdaptyUI puede renderizar. Un flow que llegó a tu aplicación sin su esquema ahora devuelve false donde la versión 4.0 devolvía true. Consulta Obtener la configuración de vista.