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

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 affiche les flows, en plus des paywalls créés avec l’ancien builder. AdaptyUI est automatiquement activé avec le module principal.

Prérequis

Installer le SDK Adapty

Ajoutez le package à votre projet :

# using npm
npm install react-native-adapty

# or using yarn
yarn add react-native-adapty

Configurez votre projet iOS

Adapty publie ses SDK iOS natifs (Adapty, AdaptyUI, AdaptyPlugin) uniquement sous forme de packages Swift — la v4 a abandonné la distribution CocoaPods (le dépôt de specs CocoaPods passe en lecture seule en décembre 2026). Les deux options installent ces packages Swift ; elles diffèrent par ce qui pilote l’installation.

• CocoaPods (par défaut, SDK 4.0 et versions ultérieures) : Votre projet iOS conserve son Podfile, et le helper spm_dependency de React Native ajoute les packages Swift d’Adapty au projet Pods. Les packages Swift se lient dynamiquement, donc le Podfile doit passer aux frameworks dynamiques.
• Intégration SPM de React Native (SDK 4.1 et versions ultérieures) : Votre projet iOS abandonne CocoaPods, et React Native résout lui-même les packages Swift à partir du manifeste Package.swift fourni par Adapty. React Native a ajouté cette intégration dans la version 0.87 en préversion et ne la recommande pas encore pour la production.

use_frameworks! :linkage => :dynamic

cd ios && pod install --repo-update

cd ios && npx react-native spm

Activer le module Adapty du SDK Adapty

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 Flow & Paywall Builder, suivez le guide de démarrage rapide.
• Si vous créez votre propre interface de paywall, consultez le guide de démarrage rapide pour les paywalls personnalisés.

Activer le module AdaptyUI du SDK Adapty

Si vous prévoyez d’utiliser le Flow & Paywall Builder, vous aurez besoin du module AdaptyUI. Il s’active automatiquement en même temps que le 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 inutile 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 politiques de l’App Store/Play Store, éviter de déclencher 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) pour améliorer les performances et réduire l’utilisation du 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 à 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, notamment le profil mis en cache, les détails des produits et les paywalls. Le SDK s’initialise ensuite dans un état propre. La valeur par défaut est false.

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

Activer l’attribution Adapty

Si vous utilisez l’attribution Adapty, définissez adaptyAttributionEnabled sur true lors de l’activation du SDK. La valeur par défaut est false : sans ce paramètre, le SDK n’enregistre pas les installations et ne transmet pas les détails d’installation à votre application. Dans les versions du SDK antérieures à la 4.1, l’attribution Adapty est activée automatiquement.

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

Conseils pour l’environnement de développement

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

Adapty pré-charge 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 à jour.

En activant la propriété __debugDeferActivation, l’appel d’activation est différé jusqu’au prochain appel du SDK Adapty. Cela évite les invites 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 utilisateur possibles. En production, l’activation ne doit pas être différée, car les appareils réels mémorisent généralement les données d’authentification et ne demandent pas répétitivement les identifiants.

Voici l’approche recommandée pour l’utilisation :

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 suivante : Adapty can only be activated once. Ensure that the SDK activation call is not made more than once.

Cela se produit car 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 drapeau 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
}

Configurer le mode mock pour les tests locaux

Pour le développement local et les tests, vous pouvez activer le mode mock afin d’éviter d’avoir besoin de comptes sandbox App Store/Google Play et d’accélérer les itérations. Le mode mock contourne complètement les modules natifs d’Adapty et renvoie des données simulées.

Pour activer le mode mock, définissez enableMock sur true :

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

Lorsque le mode mock est actif :

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

Vous pouvez personnaliser les données fictives via 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 avez besoin d’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');

Dépannage

Erreur de version iOS minimale

Si vous obtenez une erreur de version iOS minimale, mettez à jour votre Podfile :

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

Conflit de manifeste Android Auto Backup

Certains SDK (dont Adapty) embarquent leur propre configuration Android Auto Backup. Si vous utilisez plusieurs SDK qui définissent des règles de sauvegarde, la fusion du manifeste Android peut échouer avec une erreur mentionnant android:fullBackupContent, android:dataExtractionRules ou android:allowBackup.

Symptômes typiques de l’erreur : 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)

Pour résoudre ce problème, vous devez :

• Indiquer au gestionnaire de fusion de manifestes d’utiliser les valeurs de votre application pour les attributs liés à la sauvegarde.

• Créer des fichiers de règles de sauvegarde qui fusionnent les règles d’Adapty avec celles des autres SDK.

1. Ajouter le namespace tools à votre manifeste

Dans votre fichier AndroidManifest.xml, assurez-vous que la balise racine <manifest> inclut tools :

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

    ...
</manifest>

2. Remplacer les attributs de sauvegarde dans <application>

Dans le même fichier AndroidManifest.xml, mettez à jour la balise <application> afin que votre application fournisse les valeurs finales et indique au gestionnaire de fusion de remplacer les valeurs des bibliothèques :

<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 un SDK définit également android:allowBackup, ajoutez-le dans tools:replace :

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

3. Créer les fichiers de règles de sauvegarde fusionnées

Créez des fichiers XML dans le répertoire res/xml/ de votre projet Android, qui combinent les règles d’Adapty avec celles des autres SDK. Android utilise des formats de règles de sauvegarde différents selon la version du système, donc créer les deux fichiers garantit la compatibilité avec toutes les versions Android prises en charge par votre application.

Pour Android 12 et supérieur (utilise le nouveau format de règles d’extraction de données) :

<?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>

Pour Android 11 et inférieur (utilise l’ancien format de sauvegarde complète) :

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

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

    

Les achats échouent après un retour depuis une autre application sur Android

Si l’Activity qui lance le flow d’achat utilise un launchMode non standard, Android peut la recréer ou la réutiliser incorrectement lorsque l’utilisateur revient de Google Play, d’une application bancaire ou d’un navigateur. Cela peut entraîner la perte du résultat d’achat ou son traitement comme une annulation.

Pour garantir le bon fonctionnement des achats, utilisez uniquement les modes de lancement standard ou singleTop pour l’Activity qui démarre le flow d’achat, et évitez tout autre mode.

Dans votre AndroidManifest.xml, assurez-vous que l’Activity qui démarre le flow d’achat est configurée sur standard ou singleTop :

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

Erreur de version du plugin Kotlin Gradle sur React Native en dessous de 0.73

Sur les versions de React Native antérieures à 0.73.0, le build Android échoue à cause de la version du plugin Kotlin Gradle. Mettez à jour le fichier /android/build.gradle et vérifiez que la dépendance kotlin-gradle-plugin:1.8.0 (ou une version plus récente) est présente :

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

Erreurs de build Swift 6 causées par le remplacement de SWIFT_VERSION dans le Podfile

Lors de la compilation de votre application React Native pour iOS, vous pouvez rencontrer des erreurs de compilation Swift 6 sur les cibles de pods Adapty. Les symptômes typiques incluent des incompatibilités @Sendable dans AdaptyUIBuilderLogic, une conformité Sendable manquante sur les types Adapty, ou des erreurs d’isolation d’acteur.

Les pods Adapty déclarent s.swift_version = '6.0' et nécessitent Swift 6 pour être compilés. Votre propre code applicatif peut rester en Swift 5 — seuls les targets de pods Adapty (Adapty, AdaptyUI, AdaptyUIBuilder, AdaptyLogger, AdaptyPlugin) doivent être compilés avec Swift 6.

La cause la plus fréquente est un hook post_install dans ios/Podfile qui écrase SWIFT_VERSION pour tous les targets de pods :

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

Correctif : Excluez les cibles de pod Adapty de la surcharge :

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

Ensuite, exécutez pod install depuis le répertoire ios/ et reconstruisez le projet.

Pour vérifier, ouvrez ios/Pods/Pods.xcodeproj, sélectionnez la cible pod Adapty → Build Settings → Swift Language Version. Elle doit afficher Swift 6.