Installer et configurer le SDK Adapty React Native dans un projet Expo

Adapty SDK comprend deux modules clés pour une intégration fluide dans votre application React Native :

• Core Adapty : ce module est indispensable au bon fonctionnement d’Adapty dans votre application.
• AdaptyUI : ce module est nécessaire si vous utilisez le Adapty Paywall Builder, un outil no-code convivial pour créer facilement des paywalls multiplateformes. AdaptyUI est automatiquement activé avec le module principal.

Si vous souhaitez un tutoriel complet sur l’implémentation des achats intégrés dans votre application React Native, consultez celui-ci.

Pour une présentation complète de l’implémentation, vous pouvez également regarder la vidéo :

Prérequis

Le SDK React Native d’Adapty requiert iOS 15.0+.

La compilation pour iOS nécessite Swift 6.0 ou une version ultérieure. Le mode enfants requiert Swift 6.1 ou une version ultérieure.

Installer le SDK Adapty

1. Installez le SDK Adapty (cela installe également @adapty/core automatiquement) :

   npx expo install react-native-adapty
   npx expo prebuild

2. Compilez votre application pour le développement avec EAS ou un build 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. Démarrez le serveur de développement :

   npx expo start --dev-client

Adapty SDK 4.0 : activer Swift Package Manager

Le SDK React Native 4.0 — qui ajoute la prise en charge du Flow Builder — nécessite React Native 0.75 ou une version ultérieure. Installez le SDK :

npx expo install react-native-adapty@^4.0.0

v4 récupère les SDK iOS natifs (Adapty, AdaptyUI, AdaptyPlugin) via Swift Package Manager plutôt que les sous-dépendances CocoaPods (le dépôt de specs CocoaPods passe en lecture seule en décembre 2026). SPM requiert des frameworks dynamiques, que vous activez dans Expo avec le plugin expo-build-properties. Ajoutez-le dans app.json (ou app.config.js) :

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

buildReactNativeFromSource est requis à partir d’Expo SDK 57 et versions ultérieures. Expo SDK 57 embarque un framework React Native prébuild dont les headers ne sont pas accessibles aux autres packages lorsque les frameworks sont dynamiques, ce qui entraîne des erreurs de build iOS du type 'React/RCTBridge.h' file not found dans expo-updates ou @expo/ui. Compiler React Native depuis les sources permet d’éviter ce conflit, au prix de builds iOS plus longs. Avec Expo SDK 56 ou antérieur, cette option peut être omise.

Installez ensuite le plugin et regénérez le projet natif :

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

Consultez Migrer le SDK Adapty React Native vers la v4 pour la migration complète.

Activer le module Adapty du SDK

Pour obtenir votre Public SDK Key :

1. Accédez à l’Adapty Dashboard et naviguez vers App settings → General.
2. Dans la section Api keys, copiez la Public SDK Key (et NON la Secret Key).
3. Remplacez "YOUR_PUBLIC_SDK_KEY" dans le code.

Ou obtenez-la de façon programmatique via l’Adapty CLI :

npm install -g adapty
adapty auth login
adapty apps list

Ou, directement :

npx adapty auth login
adapty apps list

• Assurez-vous d’utiliser la Public SDK key pour l’initialisation d’Adapty — la Secret key ne doit être utilisée que pour l’API côté serveur.
• Les SDK keys sont propres à chaque application, donc si vous avez plusieurs applications, veillez à choisir la bonne.

Copiez le code suivant dans App.tsx pour activer Adapty :

adapty.activate('YOUR_PUBLIC_SDK_KEY');

Configurez maintenant les paywalls dans votre application :

• Si vous utilisez le Adapty Paywall Builder, suivez le guide de démarrage du Paywall Builder.
• Si vous créez votre propre interface de paywall, consultez le guide de démarrage pour les paywalls personnalisés.

Activer le module AdaptyUI du SDK Adapty

Si vous prévoyez d’utiliser le Paywall Builder, vous avez besoin du module AdaptyUI. Il est activé automatiquement lors de l’activation du module principal ; vous n’avez rien d’autre à faire.

Configuration optionnelle

Journalisation

Configurer le système de journalisation

Adapty enregistre les erreurs et d’autres informations importantes pour vous aider à comprendre ce qui se passe. Les niveaux suivants sont disponibles :

Vous pouvez définir le niveau de journalisation dans votre application avant ou pendant la configuration d’Adapty :

// 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',
});

Politiques de données

Adapty ne stocke pas les données personnelles de vos utilisateurs sauf si vous les envoyez explicitement, mais vous pouvez mettre en place des politiques de sécurité des données supplémentaires pour respecter les directives du store ou du pays.

Désactiver la collecte et le partage des adresses IP

Lors de l’activation du module Adapty, définissez ipAddressCollectionDisabled sur true pour désactiver la collecte et le partage des adresses IP des utilisateurs. La valeur par défaut est false.

Utilisez ce paramètre pour renforcer la confidentialité des utilisateurs, vous conformer aux réglementations régionales de protection des données (comme le RGPD ou le CCPA), ou réduire la collecte de données inutiles lorsque les fonctionnalités basées sur l’IP ne sont pas requises pour votre application.

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

Désactiver la collecte et le partage de l’identifiant publicitaire

Lors de l’activation du module Adapty, définissez ios.idfaCollectionDisabled (iOS) ou android.adIdCollectionDisabled (Android) sur true pour désactiver la collecte des identifiants publicitaires. La valeur par défaut est false.

Utilisez ce paramètre pour respecter les règles de l’App Store ou du Play Store, éviter d’afficher la demande d’autorisation App Tracking Transparency, ou si votre application n’a pas besoin d’attribution publicitaire ni d’analyses basées sur les identifiants publicitaires.

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

Configurer le cache média pour AdaptyUI

Par défaut, AdaptyUI met en cache les médias (images et vidéos, par exemple) pour améliorer les performances et réduire la consommation réseau. Vous pouvez personnaliser ces paramètres en fournissant une configuration personnalisée.

Utilisez mediaCache pour remplacer les paramètres de cache par défaut :

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
  },
});

Activer les niveaux d’accès locaux (Android)

Par défaut, les niveaux d’accès locaux sont activés sur iOS et désactivés sur Android. Pour les activer également sur Android, définissez localAccessLevelAllowed sur true :

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

Effacer les données lors d’une restauration de sauvegarde

Lorsque clearDataOnBackup est défini sur true, le SDK détecte quand l’application est restaurée depuis une sauvegarde iCloud et supprime toutes les données SDK stockées localement, y compris les informations de profil en cache, les détails des produits et les paywalls. Le SDK s’initialise ensuite dans un état vierge. La valeur par défaut est false.

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

Conseils pour l’environnement de développement

Configurer le mode mock pour Expo Go / Expo Web

Les environnements Expo Go et Expo Web n’ont pas accès aux modules natifs d’Adapty. Pour éviter les erreurs d’exécution tout en pouvant continuer à développer et tester l’interface et la logique de vos paywalls, Adapty propose un mode mock.

Par défaut, le SDK détecte automatiquement les environnements Expo Go et web et active le mode mock. Aucune configuration n’est nécessaire, sauf si vous souhaitez personnaliser les données mock.

Lorsque le mode mock est actif :

• Toutes les méthodes Adapty retournent des données mock sans effectuer de requêtes réseau vers les serveurs d’Adapty.
• Par défaut, le profil mock initial n’a pas d’abonnements actifs.
• Par défaut, makePurchase(...) simule un achat réussi et accorde l’accès premium.

Vous pouvez personnaliser les données fictives avec mockConfig lors de l’activation. Consultez le format de configuration et les paramètres pris en charge ici.

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 vous devez appeler des méthodes du SDK avant l’activation (comme isActivated() ou setLogLevel()), utilisez enableMock() avant activate(). Si le bridge est déjà initialisé, cette méthode ne fait rien.

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

// Now you can call methods before activation

await adapty.activate('YOUR_PUBLIC_SDK_KEY');

Différer l’activation du SDK à des fins de développement

Adapty récupère à l’avance toutes les données utilisateur nécessaires lors de l’activation du SDK, ce qui permet un accès plus rapide aux données fraîches.

Cependant, cela peut poser un problème dans le simulateur iOS, qui demande fréquemment une authentification pendant le développement. Bien qu’Adapty ne puisse pas contrôler le flux d’authentification StoreKit, il peut différer les requêtes effectuées par le SDK pour obtenir des données utilisateur fraîches.

En activant la propriété __debugDeferActivation, l’appel d’activation est suspendu jusqu’à ce que vous effectuiez le prochain appel au SDK Adapty. Cela évite les demandes d’authentification inutiles si elles ne sont pas nécessaires.

Il est important de noter que cette fonctionnalité est destinée uniquement au développement, car elle ne couvre pas tous les scénarios utilisateurs possibles. En production, l’activation ne doit pas être retardée, car les appareils réels mémorisent généralement les données d’authentification et ne redemandent pas les identifiants à répétition.

Voici l’approche recommandée :

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
}

Résoudre les erreurs d’activation du SDK lors du Fast Refresh de React Native

Lors du développement avec le SDK Adapty dans React Native, vous pouvez rencontrer l’erreur : Adapty can only be activated once. Ensure that the SDK activation call is not made more than once.

Cela se produit parce que la fonctionnalité de fast refresh de React Native déclenche plusieurs appels d’activation pendant le développement. Pour éviter cela, utilisez l’option __ignoreActivationOnFastRefresh définie sur __DEV__ (le flag du mode développement 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
}

Résolution des problèmes

Erreur de version iOS minimale

Lors d’une compilation pour iOS, vous pourriez voir une erreur concernant la version iOS minimale ou la cible de déploiement. Adapty requiert iOS 15.0+.

Étant donné qu’Expo génère le projet iOS (y compris le Podfile) lors de l’exécution de expo prebuild, vous ne devez pas modifier le Podfile directement. Configurez plutôt la cible de déploiement via le plugin de configuration expo-build-properties.

1. Installez le plugin :

   npx expo install expo-build-properties

2. Mettez à jour votre configuration Expo (app.json ou app.config.js) pour définir la cible de déploiement iOS :

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

3. Régénérez le projet iOS natif et reconstruisez :

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

Conflit de manifeste Android Auto Backup

Lors de l’utilisation d’Expo avec plusieurs SDK qui configurent Android Auto Backup (comme Adapty, AppsFlyer ou expo-secure-store), vous pouvez rencontrer un conflit lors de la fusion des manifestes.

Une erreur type ressemble à ceci : 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).

Pour résoudre ce conflit, vous devez laisser le plugin Adapty gérer la configuration de sauvegarde Android. Si votre projet utilise également expo-secure-store, désactivez sa propre configuration de sauvegarde pour éviter les conflits.

Voici comment configurer votre app.json :

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

L’option replaceAndroidBackupConfig est false par défaut. Lorsqu’elle est activée, elle permet au plugin Adapty de contrôler les règles de sauvegarde Android. Ajoutez "configureAndroidBackup": false si vous utilisez expo-secure-store pour éviter les avertissements, car la configuration de sauvegarde de SecureStore sera désormais gérée par Adapty.