El SDK de Adapty incluye dos módulos clave para una integración fluida en tu app de Flutter:

• Core Adapty: Este SDK esencial es necesario para que Adapty funcione correctamente en tu app.
• AdaptyUI: Este módulo renderiza flows, además de los paywalls del builder antiguo.

Requisitos

El SDK de Adapty para Flutter requiere iOS 15.0+, Xcode 26+ y Flutter 3.32.0+ (Dart 3.8.0+). Consulta Swift Package Manager (iOS) más abajo para los detalles de instalación.

Dependencias

El SDK de Adapty funciona con las siguientes versiones de la Google Play Billing Library en Android:

Versión del SDK de Adapty	Versión de la Billing Library
4.0.4 y posteriores	v8
4.0.0–4.0.3	v7 por defecto, v8 si otra dependencia la eleva

Instalar el SDK de Adapty

Siempre recomendamos instalar la versión más reciente disponible del SDK — incluye las últimas correcciones de estabilidad y mejoras.

1. Añade Adapty a tu archivo pubspec.yaml:

   dependencies: 
     adapty_flutter: ^<the latest SDK version>

2. Ejecuta el siguiente comando para instalar las dependencias:

   flutter pub get

3. Importa los SDK de Adapty en tu aplicación:

   import 'package:adapty_flutter/adapty_flutter.dart';

Swift Package Manager (iOS)

El plugin obtiene el SDK nativo de iOS a través de Swift Package Manager. Si usas Flutter 3.32–3.43, activa el soporte de Swift Package Manager una sola vez:

flutter config --enable-swift-package-manager

Flutter 3.44 y versiones posteriores activan Swift Package Manager por defecto, por lo que no es necesario hacer nada.

Para ver los cambios de API en la v4, consulta la guía de migración.

Activa el módulo Adapty del SDK

Activa el SDK de Adapty en el código de tu app.

Para obtener tu Public SDK Key:

1. Ve al Adapty Dashboard y navega a App settings → General.
2. En la sección Api keys, copia la Public SDK Key (NO la Secret Key).
3. Reemplaza "YOUR_PUBLIC_SDK_KEY" en el código.

O bien, obtenla de forma programática usando el Adapty CLI:

npm install -g adapty
adapty auth login
adapty apps list

O directamente:

npx adapty auth login
adapty apps list

• Asegúrate de usar la Public SDK key para inicializar Adapty; la Secret key solo debe usarse para la API del lado del servidor.
• Las SDK keys son únicas para cada app, así que si tienes varias apps asegúrate de elegir la correcta.

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    _initializeAdapty();

    super.initState();
  }

  Future<void> _initializeAdapty() async {
    try {
      await Adapty().activate(
        configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY'),
      );
    } catch (e) {
      // handle the error
    }
  }

  Widget build(BuildContext context) {
    return Text("Hello");
  }
}

Ahora configura los paywalls en tu app:

• Si usas el Flow & Paywall Builder, primero activa el módulo AdaptyUI más abajo y luego sigue la guía de inicio rápido.
• Si construyes tu propia UI de paywall, consulta la guía de inicio rápido para paywalls personalizados.

Activar el módulo AdaptyUI del SDK de Adapty

Si tienes previsto usar el Flow & Paywall Builder y has instalado el módulo AdaptyUI, también necesitas activar AdaptyUI:

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withActivateUI(true), // This automatically activates AdaptyUI
);

Configuración opcional

Registro

Configurar el sistema de registro

Adapty registra errores y otra información importante para ayudarte a entender qué está ocurriendo. Los niveles disponibles son los siguientes:

Nivel	Descripción
AdaptyLogLevel.error	Solo se registrarán los errores
AdaptyLogLevel.warn	Se registrarán los errores y los mensajes del SDK que no causan errores críticos pero que conviene tener en cuenta.
AdaptyLogLevel.info	Se registrarán los errores, las advertencias y varios mensajes informativos. Valor predeterminado
AdaptyLogLevel.verbose	Se registrará cualquier información adicional que pueda ser útil durante la depuración, como llamadas a funciones, consultas a la API, etc.
AdaptyLogLevel.debug	Se registrará información de depuración.

Puedes configurar el nivel de log en tu app antes de configurar Adapty:

// Set log level before activation. 
// 'verbose' is recommended for development and the first production release
await Adapty().setLogLevel(AdaptyLogLevel.verbose);

// Or set it during configuration
await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withLogLevel(AdaptyLogLevel.verbose),
);

Políticas de datos

Adapty no almacena datos personales de tus usuarios a menos que los envíes explícitamente, pero puedes implementar políticas adicionales de seguridad de datos para cumplir con las directrices de la store o del país.

Deshabilitar la recopilación y el uso compartido de la dirección IP

Al activar el módulo de Adapty, establece ipAddressCollectionDisabled en true para deshabilitar la recopilación y el uso compartido de la dirección IP del usuario. El valor predeterminado es false.

Usa este parámetro para mejorar la privacidad del usuario, cumplir con las regulaciones regionales de protección de datos (como el RGPD o la CCPA) o reducir la recopilación de datos innecesaria cuando las funciones basadas en IP no son necesarias para tu app.

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withIpAddressCollectionDisabled(true),
);

Desactivar la recopilación y el uso compartido del ID publicitario

Al activar el módulo de Adapty, establece appleIdfaCollectionDisabled (iOS) o googleAdvertisingIdCollectionDisabled (Android) en true para desactivar la recopilación de identificadores publicitarios. El valor por defecto es false.

Usa este parámetro para cumplir con las políticas del App Store/Play Store, evitar que aparezca el aviso de App Tracking Transparency, o si tu app no necesita atribución publicitaria ni análisis basados en IDs publicitarios.

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withAppleIdfaCollectionDisabled(true)      // iOS
    ..withGoogleAdvertisingIdCollectionDisabled(true), // Android
);

Configurar la caché de medios para AdaptyUI

El módulo se activa automáticamente con el SDK de Adapty. Si Adapty no renderiza tus pantallas y quieres desactivar el módulo AdaptyUI, pasa withActivateUI(false) durante la activación.

De forma predeterminada, AdaptyUI almacena en caché los medios (como imágenes y vídeos) para mejorar el rendimiento y reducir el uso de red. Puedes personalizar la configuración de caché proporcionando una configuración personalizada.

Usa withMediaCacheConfiguration para sobrescribir los límites de caché predeterminados. Esto es opcional: si no llamas a este método, se usarán los valores predeterminados (100 MB de tamaño en disco, sin límite de recuento en memoria). Sin embargo, si creas el objeto de configuración, todos sus parámetros son obligatorios.

final mediaCacheConfig = AdaptyUIMediaCacheConfiguration(
  memoryStorageTotalCostLimit: 200 * 1024 * 1024, // 200 MB
  memoryStorageCountLimit: 2147483647, // max int value
  diskStorageSizeLimit: 200 * 1024 * 1024, // 200 MB
);

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withMediaCacheConfiguration(mediaCacheConfig),
);

Parámetros:

Parámetro	Presencia	Descripción
memoryStorageTotalCostLimit	requerido	Tamaño total de la caché en memoria en bytes. El valor predeterminado es 100 MB.
memoryStorageCountLimit	requerido	El límite de elementos de la memoria caché. El valor predeterminado es el valor máximo de int.
diskStorageSizeLimit	requerido	El límite de tamaño de archivo en disco en bytes. El valor predeterminado es 100 MB.

Habilitar niveles de acceso locales (Android)

Por defecto, los niveles de acceso locales están habilitados en iOS y deshabilitados en Android. Para habilitarlos también en Android, establece withGoogleLocalAccessLevelAllowed en true:

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withGoogleLocalAccessLevelAllowed(true),
);

Borrar datos al restaurar copia de seguridad

Cuando appleClearDataOnBackup se establece en true, el SDK detecta cuándo la app se restaura desde una copia de seguridad de iCloud y elimina todos los datos almacenados localmente por el SDK, incluida la información de perfil en caché, los detalles de productos y los paywalls. El SDK se inicializa entonces con un estado limpio. El valor predeterminado es false.

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withAppleClearDataOnBackup(true) // default – false
);

Habilitar la atribución de Adapty

Si usas Adapty Attribution, llama a withAdaptyAttributionEnabled(true) al activar el SDK. El valor predeterminado es false: sin este parámetro, el SDK no registra instalaciones ni envía los detalles de instalación a tu app. En versiones del SDK anteriores a la 4.1, la atribución de Adapty se habilita automáticamente.

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

Solución de problemas

Reglas de copia de seguridad de Android (configuración de Auto Backup)

Algunos SDKs (incluido Adapty) incluyen su propia configuración de Android Auto Backup. Si usas varios SDKs que definen reglas de copia de seguridad, el fusionador de manifiestos de Android puede fallar con un error relacionado con android:fullBackupContent, android:dataExtractionRules o android:allowBackup.

Síntomas típicos del error: Manifest merger failed: Attribute application@dataExtractionRules value=(@xml/your_data_extraction_rules) is also present at [com.other.sdk:library:1.0.0] value=(@xml/other_sdk_data_extraction_rules)

Para resolverlo, necesitas:

• Indicar al fusionador de manifiestos que use los valores de tu app para los atributos relacionados con la copia de seguridad.

• Crear archivos de reglas de copia de seguridad que combinen las reglas de Adapty con las de otros SDKs.

1. Añade el espacio de nombres tools a tu manifiesto

En tu archivo AndroidManifest.xml, asegúrate de que la etiqueta raíz <manifest> incluya tools:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.example.app">

    ...
</manifest>

2. Sobreescribe los atributos de copia de seguridad en <application>

En el mismo archivo AndroidManifest.xml, actualiza la etiqueta <application> para que tu app proporcione los valores finales e indique al fusionador de manifiestos que reemplace los valores de las bibliotecas:

<application
android:name=".App"
android:allowBackup="true"
android:fullBackupContent="@xml/sample_backup_rules"           
android:dataExtractionRules="@xml/sample_data_extraction_rules"
tools:replace="android:fullBackupContent,android:dataExtractionRules">

    ...
</application>

Si algún SDK también define android:allowBackup, inclúyelo en tools:replace:

tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"

3. Crea los archivos de reglas de copia de seguridad combinadas

Crea archivos XML en el directorio res/xml/ de tu proyecto Android que combinen las reglas de Adapty con las de otros SDKs. Android usa diferentes formatos de reglas de copia de seguridad según la versión del sistema operativo, por lo que crear ambos archivos garantiza la compatibilidad con todas las versiones de Android que soporta tu app.

Para Android 12 y superior (usa el nuevo formato de reglas de extracción de datos):

<?xml version="1.0" encoding="utf-8"?>
<data-extraction-rules>
    <cloud-backup>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </cloud-backup>

    <device-transfer>
        
        <exclude domain="sharedpref" path="appsflyer-data"/>
        <exclude domain="sharedpref" path="appsflyer-purchase-data"/>
        <exclude domain="database" path="afpurchases.db"/>
        <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>
    </device-transfer>
</data-extraction-rules>

Para Android 11 e inferior (usa el formato heredado de contenido de copia de seguridad completa):

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

    

Las compras fallan al volver desde otra aplicación en Android

Si la Activity que inicia el flujo de compra usa un launchMode distinto al predeterminado, Android puede recrearla o reutilizarla incorrectamente cuando el usuario regresa desde Google Play, una aplicación bancaria o un navegador. Esto puede hacer que el resultado de la compra se pierda o se trate como cancelado.

Para garantizar que las compras funcionen correctamente, usa únicamente los modos de inicio standard o singleTop para la Activity que inicia el flujo de compra, y evita cualquier otro modo.

En tu AndroidManifest.xml, asegúrate de que la Activity que inicia el flow de compra esté configurada como standard o singleTop:

<activity
    android:name=".MainActivity"
    android:launchMode="standard" />

Errores de compilación en Swift 6 causados por la sobreescritura de SWIFT_VERSION en el Podfile

Al compilar tu app Flutter para iOS, es posible que veas errores de compilación de Swift 6 en los targets del pod de Adapty. Los síntomas más habituales son: incompatibilidades con @Sendable en AdaptyUIBuilderLogic, falta de conformidad con Sendable en los tipos de Adapty, o errores de aislamiento de actores.

Los pods de Adapty declaran s.swift_version = '6.0' y requieren Swift 6 para compilar. Tu propio código de la app puede seguir en Swift 5 — solo los targets del pod de Adapty (Adapty, AdaptyUI, AdaptyUIBuilder, AdaptyLogger, AdaptyPlugin) necesitan compilarse con Swift 6.

La causa más común es un hook post_install en ios/Podfile que sobreescribe SWIFT_VERSION para cada target de pod:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

Solución: Excluye los targets del pod Adapty de la sobreescritura:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    next if %w[Adapty AdaptyUI AdaptyUIBuilder AdaptyLogger AdaptyPlugin].include?(target.name)
    target.build_configurations.each do |config|
      config.build_settings['SWIFT_VERSION'] = '5.9'
    end
  end
end

Luego ejecuta pod install desde el directorio ios/ y vuelve a compilar.

Para verificarlo, abre ios/Pods/Pods.xcodeproj, selecciona el target del pod Adapty → Build Settings → Swift Language Version. Debería mostrar Swift 6.