Instalar y configurar el SDK de Adapty para React Native en un proyecto Expo

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 utilizas el Adapty Paywall Builder, una herramienta visual sin código para crear paywalls multiplataforma fácilmente. AdaptyUI se activa automáticamente junto con el módulo principal.

Si necesitas un tutorial completo sobre cómo implementar compras in-app en tu app de React Native, consulta este artículo.

Para una guía completa de implementación, también puedes ver el vídeo:

Requisitos

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

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

Instala el SDK de Adapty

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

   npx expo install react-native-adapty
   npx expo prebuild

2. Compila tu app para desarrollo usando EAS o una compilación local:

# For iOS
eas build --profile development --platform ios

# For Android
eas build --profile development --platform android

# For iOS
npx expo run:ios

# For Android
npx expo run:android

3. Inicia el servidor de desarrollo:

   npx expo start --dev-client

Adapty SDK 4.0 (beta): habilitar Swift Package Manager

React Native SDK 4.0 — que añade soporte para Flow Builder — es una versión preliminar que requiere React Native 0.75 o posterior. Instala la versión exacta (npm no resuelve versiones preliminares mediante rangos con ^ o ~):

npx expo install react-native-adapty@4.0.0-beta.1

v4 descarga los SDKs nativos de iOS (Adapty, AdaptyUI, AdaptyPlugin) a través de Swift Package Manager en lugar de sub-dependencias de CocoaPods (el repositorio de specs de CocoaPods pasará a solo lectura en diciembre de 2026). SPM requiere frameworks dinámicos, que en Expo se habilitan con el plugin expo-build-properties. Añádelo a app.json (o app.config.js):

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "useFrameworks": "dynamic"
          }
        }
      ]
    ]
  }
}

Luego instala el plugin y regenera el proyecto nativo:

npx expo install expo-build-properties
npx expo prebuild --clean

Consulta Migrar el SDK de Adapty React Native a v4 para ver la migración completa.

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 la guía de inicio rápido con Paywall Builder.
• Si construyes tu propia interfaz de paywall, consulta la guía de inicio rápido para paywalls personalizados.

Activar el módulo AdaptyUI del SDK de Adapty

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

Configuración opcional

Registro

Configurar el sistema de registro

Adapty registra errores y otra información importante para ayudarte a entender qué está pasando. 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 del store o del país.

Deshabilitar la recopilación y el intercambio de direcciones IP

Al activar el módulo de Adapty, establece ipAddressCollectionDisabled en true para deshabilitar la recopilación y el intercambio 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 innecesaria de datos cuando las funciones basadas en IP no son necesarias para tu aplicación.

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 desactivar 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 prompt de App Tracking Transparency, o si tu app no necesita atribución publicitaria ni análisis basados en IDs publicitarios.

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 consumo de red. Puedes personalizar la configuración de la caché proporcionando una configuración personalizada.

Usa mediaCache para cambiar 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. El SDK se inicializa entonces con un estado limpio. El valor predeterminado es false.

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

Consejos para el entorno de desarrollo

Configura el modo mock para Expo Go / Expo Web

Los entornos de Expo Go y Expo Web no tienen acceso a los módulos nativos de Adapty. Para evitar errores en tiempo de ejecución sin dejar de poder construir y probar la UI y la lógica de paywall de tu app, Adapty ofrece el modo mock.

De forma predeterminada, el SDK detecta automáticamente los entornos Expo Go y web y activa el modo simulado. No necesitas configurar nada a menos que quieras personalizar los datos simulados.

Cuando el modo simulado está activo:

• Todos los métodos de Adapty devuelven datos simulados sin realizar solicitudes de red a los servidores de Adapty.
• Por defecto, el perfil simulado inicial no tiene suscripciones activas.
• Por defecto, makePurchase(...) simula una compra exitosa y otorga acceso premium. Puedes personalizar los datos de prueba 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');

Retrasar la activación del SDK con fines de desarrollo

Adapty pre-carga 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 con frecuencia solicita autenticación durante el desarrollo. Aunque Adapty no puede controlar el flujo de autenticación de StoreKit, sí puede aplazar las solicitudes que el SDK realiza para obtener datos de usuario actualizados.

Al activar la propiedad __debugDeferActivation, la llamada de activación queda en espera hasta que realizas la siguiente llamada al SDK de Adapty. Esto evita solicitudes de autenticación innecesarias cuando no son necesarias. Es importante tener en cuenta que esta función está pensada únicamente 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 actualización rápida (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
}

Solución de problemas

Error de versión mínima de iOS

Al compilar para iOS, puede aparecer un error relacionado con la versión mínima de iOS o el deployment target. Adapty requiere iOS 15.0+.

Como Expo genera el proyecto de iOS (incluido el Podfile) durante expo prebuild, no debes editar el Podfile directamente. En su lugar, configura el deployment target mediante el plugin de configuración expo-build-properties.

1. Instala el plugin:

   npx expo install expo-build-properties

2. Actualiza tu configuración de Expo (app.json o app.config.js) para establecer el deployment target de iOS:

{
    "expo": {
        // ...other Expo config...
        "plugins": [
            [
                "expo-build-properties",
                {
                    "ios": {
                        // Adapty requires iOS 15.0+.
                        "deploymentTarget": "15.0"
                    }
                }
            ],
        ]
    }
}

3. Regenera el proyecto nativo de iOS y reconstrúyelo:

npx expo prebuild --clean
npx expo run:ios      # or `eas build -p ios` on your CI

Conflicto del manifiesto de Android Auto Backup

Cuando usas Expo con varios SDKs que configuran Android Auto Backup (como Adapty, AppsFlyer o expo-secure-store), puede aparecer un conflicto en el fusionador de manifiestos.

Un error típico tiene este aspecto: Manifest merger failed : Attribute application@fullBackupContent value=(@xml/secure_store_backup_rules) from AndroidManifest.xml:24:248-306 is also present at [io.adapty:android-sdk:3.12.0] AndroidManifest.xml:9:18-70 value=(@xml/adapty_backup_rules). Para resolver este conflicto, debes permitir que el plugin de Adapty gestione la configuración de copia de seguridad de Android. Si tu proyecto también usa expo-secure-store, desactiva su propia configuración de copia de seguridad para evitar conflictos.

Así es como debes configurar tu app.json:

{
  "expo": {
    "plugins": [
      ["react-native-adapty", { "replaceAndroidBackupConfig": true }],
      ["expo-secure-store", { "configureAndroidBackup": false }]
    ]
  }
}

La opción replaceAndroidBackupConfig está en false por defecto. Cuando se activa, permite que el plugin de Adapty controle las reglas de copia de seguridad de Android. Incluye "configureAndroidBackup": false si usas expo-secure-store para evitar advertencias, ya que la configuración de copia de seguridad de SecureStore pasará a gestionarla Adapty.