Install & configure Adapty SDK in a pure React Native project

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

• Core Adapty: Este módulo es necesario para que Adapty funcione correctamente en tu app.
• AdaptyUI: Este módulo es necesario si usas el Adapty Paywall Builder, una herramienta sin código y fácil de usar para crear paywalls multiplataforma. AdaptyUI se activa automáticamente junto con el módulo principal.

Requisitos

El SDK de Adapty para React Native requiere iOS 15.0+.

Para compilar en iOS se necesita Swift 6.0 o posterior. El Modo Infantil requiere Swift 6.1 o posterior.

Instalar el SDK de Adapty

1. Instala el SDK de Adapty (esto también instala @adapty/core automáticamente):

   # using npm
   npm install react-native-adapty
   
   # or using yarn
   yarn add react-native-adapty

2. Para iOS, instala los pods:

   cd ios && pod install

   ...
   buildscript {
     ...
     dependencies {
       ...
       classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.0"
     }
   }
   ...

Adapty SDK 4.0: habilitar Swift Package Manager

React Native SDK 4.0 — que añade soporte para Flow Builder — requiere React Native 0.75 o posterior. Instala el SDK:

npm install react-native-adapty@^4.0.0

# or using yarn
yarn add react-native-adapty@^4.0.0

v4 incorpora los SDK nativos de iOS (Adapty, AdaptyUI, AdaptyPlugin) a través de Swift Package Manager en lugar de las sub-dependencias de CocoaPods (el repositorio de specs de CocoaPods pasará a ser de solo lectura en diciembre de 2026). SPM requiere frameworks dinámicos — añade lo siguiente al target de tu ios/Podfile y luego reinstala los pods:

use_frameworks! :linkage => :dynamic

cd ios && pod install --repo-update

Si anteriamente tenías Adapty, AdaptyUI o AdaptyPlugin como sub-dependencias de CocoaPods, elimina primero cualquier línea pod 'Adapty', pod 'AdaptyUI' o pod 'AdaptyPlugin' de tu Podfile.

Activa el módulo Adapty del SDK

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.

Copia el siguiente código en App.tsx para activar Adapty:

adapty.activate('YOUR_PUBLIC_SDK_KEY');

Ahora configura los paywalls en tu app:

• Si usas Adapty Paywall Builder, sigue el inicio rápido con Paywall Builder.
• Si construyes tu propia UI de paywall, consulta el inicio rápido para paywalls personalizados.

Activar el módulo AdaptyUI del SDK de Adapty

Si planeas usar Paywall Builder, necesitas el módulo AdaptyUI. Se activa automáticamente al activar el módulo principal; no es necesario hacer nada más.

Configuración opcional

Registro

Configura el sistema de registro

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

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

// Or set it during configuration
adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  logLevel: '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 de seguridad de datos adicionales para cumplir con las directrices de la store o del país.

Desactivar la recopilación y el uso compartido de direcciones IP

Al activar el módulo de Adapty, establece ipAddressCollectionDisabled en true para desactivar 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 normativas regionales de protección de datos (como GDPR o CCPA), o reducir la recopilación de datos innecesaria cuando las funciones basadas en IP no son necesarias para tu app.

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  ipAddressCollectionDisabled: true,
});

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

Al activar el módulo de Adapty, establece ios.idfaCollectionDisabled (iOS) o android.adIdCollectionDisabled (Android) en true para deshabilitar la recopilación de identificadores publicitarios. El valor predeterminado es false.

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

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  ios: {
    idfaCollectionDisabled: true,
  },
  android: {
    adIdCollectionDisabled: true,
  },
});

Configurar la caché de medios para AdaptyUI

Por defecto, 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 mediaCache para sobrescribir la configuración de caché predeterminada:

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  mediaCache: {
    memoryStorageTotalCostLimit: 200 * 1024 * 1024, // Optional: memory cache size in bytes
    memoryStorageCountLimit: 2147483647,            // Optional: max number of items in memory
    diskStorageSizeLimit: 200 * 1024 * 1024,       // Optional: disk cache size in bytes
  },
});

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 localAccessLevelAllowed en true:

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  android: {
     localAccessLevelAllowed: true,
  },
});

Borrar datos al restaurar desde copia de seguridad

Cuando clearDataOnBackup 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 del SDK almacenados localmente, incluida la información de perfil en caché, los detalles de productos y los paywalls. A continuación, el SDK se inicializa con un estado limpio. El valor predeterminado es false.

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
   ios: {
      clearDataOnBackup: true
   },
});

Consejos para el entorno de desarrollo

Retrasar la activación del SDK con fines de desarrollo

Adapty obtiene de antemano todos los datos de usuario necesarios al activar el SDK, lo que permite un acceso más rápido a datos actualizados.

Sin embargo, esto puede ser un problema en el simulador de iOS, que durante el desarrollo suele pedir autenticación con frecuencia. Aunque Adapty no puede controlar el flujo de autenticación de StoreKit, sí puede aplazar las solicitudes que realiza el SDK para obtener datos de usuario actualizados. Al activar la propiedad __debugDeferActivation, la llamada de activación se retiene hasta que realizas la siguiente llamada al SDK de Adapty. Esto evita solicitudes innecesarias de datos de autenticación cuando no son necesarias.

Es importante tener en cuenta que esta función está pensada solo para uso en desarrollo, ya que no cubre todos los escenarios de usuario posibles. En producción, la activación no debe retrasarse, ya que los dispositivos reales suelen recordar los datos de autenticación y no solicitan las credenciales repetidamente.

Este es el enfoque recomendado para su uso:

try {
  adapty.activate('PUBLIC_SDK_KEY', {
    __debugDeferActivation: isSimulator(), // 'isSimulator' from any 3rd party library
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Handle the error appropriately for your app
}

Solucionar errores de activación del SDK con Fast Refresh de React Native

Al desarrollar con el SDK de Adapty en React Native, es posible que encuentres el error: Adapty can only be activated once. Ensure that the SDK activation call is not made more than once. Esto ocurre porque la función de fast refresh de React Native activa múltiples llamadas de activación durante el desarrollo. Para evitarlo, usa la opción __ignoreActivationOnFastRefresh con el valor __DEV__ (el indicador del modo de desarrollo de React Native).

try {
  adapty.activate('PUBLIC_SDK_KEY', {
    __ignoreActivationOnFastRefresh: __DEV__,
  });
} catch (error) {
  console.error('Failed to activate Adapty SDK:', error);
  // Handle the error appropriately for your app
}

Configura el modo mock para pruebas locales

Para el desarrollo local y las pruebas, puedes activar el modo mock para evitar necesitar cuentas de sandbox de App Store/Google Play y agilizar las iteraciones. El modo mock omite completamente los módulos nativos de Adapty y devuelve datos simulados.

Para activar el modo mock, establece enableMock en true:

adapty.activate('YOUR_PUBLIC_SDK_KEY', {
  enableMock: true,
});

Cuando el modo mock está activo:

• Todos los métodos de Adapty devuelven datos de prueba sin realizar solicitudes de red a los servidores de Adapty.
• Por defecto, el perfil mock inicial no tiene suscripciones activas.
• Por defecto, makePurchase(...) simula una compra exitosa y concede acceso premium.

Puedes personalizar los datos mock usando mockConfig durante la activación. Consulta el formato de configuración y los parámetros disponibles aquí.

try {
   await adapty.activate('YOUR_PUBLIC_SDK_KEY', {
      mockConfig: {
         // Customize the initial mock profile (optional)
      },
   });
} catch (error) {
   console.error('Failed to activate Adapty SDK:', error);
}

Si necesitas llamar a métodos del SDK antes de la activación (como isActivated() o setLogLevel()), usa enableMock() antes de activate(). Si el puente ya está inicializado, este método no hace nada.

adapty.enableMock(); // Optional: pass mockConfig to customize mock data

// Now you can call methods before activation

await adapty.activate('YOUR_PUBLIC_SDK_KEY');

Solución de problemas

Error de versión mínima de iOS

Si obtienes un error de versión mínima de iOS, actualiza tu Podfile:

-platform :ios, min_ios_version_supported
+platform :ios, '15.0'

Conflicto en el manifiesto de Android Auto Backup

Algunos SDKs (incluido Adapty) incluyen su propia configuración de Android Auto Backup. Si utilizas 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 namespace 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 definitivos e indique al fusionador de manifiestos que reemplace los valores de las librerías:

<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 utiliza distintos 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 admite 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 legado 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 app en Android

Si la Activity que inicia el flow de compra usa un launchMode distinto al predeterminado, Android puede recrearla o reutilizarla de forma incorrecta cuando el usuario regresa desde Google Play, una app bancaria o un navegador. Esto puede provocar que el resultado de la compra se pierda o se trate como cancelado. Para garantizar que las compras funcionen correctamente, utiliza solo 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 flujo de compra esté configurada como standard o singleTop:

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

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

Al compilar tu app de React Native para iOS, puede que veas errores de compilación de Swift 6 en los targets de los pods de Adapty. Los síntomas típicos incluyen discrepancias con @Sendable en AdaptyUIBuilderLogic, falta de conformidad con Sendable en 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 puede quedarse en Swift 5 — solo los targets de los pods 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 todos los targets del 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 de Adapty del override:

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.