--- title: "Capacitor - Installation & configuration du SDK Adapty" description: "Guide étape par étape pour installer le SDK Adapty sur Capacitor pour les applications basées sur des abonnements." --- Le SDK Adapty comprend deux modules essentiels pour une intégration fluide dans votre application Capacitor : - **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](adapty-paywall-builder), un outil no-code convivial pour créer facilement des paywalls multiplateformes. AdaptyUI est automatiquement activé avec le module principal. :::tip Vous souhaitez voir un exemple concret d'intégration du SDK Adapty dans une application mobile ? Consultez nos [exemples d'applications](https://github.com/adaptyteam/AdaptySDK-Capacitor/tree/master/examples), qui illustrent la configuration complète, notamment l'affichage des paywalls, les achats et autres fonctionnalités de base. ::: ## Prérequis \{#requirements\} Le [SDK Adapty Capacitor](https://github.com/adaptyteam/AdaptySDK-Capacitor/) requiert les versions suivantes : | Version du SDK Adapty | Version de Capacitor | Version iOS | |-----------------------|----------------------|-------------| | 3.16.0+ | 8 | 15.0+ | | 3.15 | 7 | 14.0+ | Les versions 6 et inférieures de Capacitor ne sont pas prises en charge. La création pour iOS avec Adapty SDK v4 (bêta) nécessite **Xcode 26** ou version ultérieure — le SDK iOS natif qu'il utilise est compilé avec Swift tools 6.2. Les exigences iOS 15.0+, Capacitor 8 et Android minSdk 24 sont identiques à celles du SDK 3.16+. :::info À partir du SDK v3.17, Adapty SDK utilise Google Play Billing Library v8.0.0 par défaut. ::: :::info L'installation du SDK correspond à l'étape 5 de la configuration d'Adapty. Avant que les achats fonctionnent dans votre app, vous devez également connecter votre app aux stores, puis créer des produits, un paywall et un placement dans l'Adapty Dashboard. Le [guide de démarrage rapide](quickstart) décrit toutes les étapes requises. ::: ## Installer le SDK Adapty \{#install-adapty-sdk\} :::important Les étapes ci-dessous installent le SDK Adapty 3.x. Le SDK v4 (bêta) — requis pour le [Flow Builder](adapty-flow-builder) et utilisé par le [démarrage rapide](capacitor-quickstart-paywalls) — s'installe différemment : suivez [SDK Adapty 4.0 (bêta)](#adapty-sdk-40-beta) ci-dessous, ou consultez le [guide de migration](migration-to-capacitor-sdk-v4). ::: [![Release](https://img.shields.io/github/v/release/adaptyteam/AdaptySDK-Capacitor.svg?style=flat&logo=capacitor)](https://github.com/adaptyteam/AdaptySDK-Capacitor/releases) Installez le SDK Adapty : ```sh npm install @adapty/capacitor npx cap sync ``` ### Adapty SDK 4.0 (beta) Capacitor SDK 4.0 — qui ajoute la prise en charge du [Flow Builder](adapty-flow-builder) — est une version préliminaire. Installez la version exacte (npm ne résout pas les pré-versions via les plages caret/tilde), puis synchronisez : ```sh npm install @adapty/capacitor@4.0.1-beta.1 ``` ```sh npx cap sync ``` Sur iOS, la v4 récupère les SDK natifs Adapty via **Swift Package Manager uniquement** — le podspec CocoaPods a été supprimé ([le dépôt de specs CocoaPods passe en lecture seule en décembre 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/)). Le projet iOS de votre application doit utiliser l'intégration SPM de Capacitor : - Pour les nouvelles applications, ajoutez la plateforme iOS avec le gestionnaire de paquets SPM : ```sh npx cap add ios --packagemanager SPM ``` - Pour les applications existantes, migrez le projet iOS de CocoaPods vers SPM en suivant [le guide Capacitor pour utiliser SPM dans un projet existant](https://capacitorjs.com/docs/ios/spm#using-spm-in-an-existing-capacitor-project). Pour la liste complète des changements d'API en v4, consultez [Migrer le SDK Adapty Capacitor vers la v4](migration-to-capacitor-sdk-v4). ## Activer le module Adapty du SDK \{#activate-adapty-module-of-adapty-sdk\} :::note Le SDK n'a besoin d'être activé qu'une seule fois dans votre application. ::: Pour obtenir votre **Public SDK Key** : 1. Accédez à l'Adapty Dashboard et naviguez vers [**App settings → General**](https://app.adapty.io/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](developer-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](getting-started-with-server-side-api). - Les **SDK keys** sont propres à chaque application, donc si vous avez plusieurs applications, veillez à choisir la bonne. Copiez le code suivant dans n'importe quel fichier de l'application pour activer Adapty : ```typescript showLineNumbers try { await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { // verbose logging is recommended for the development purposes and for the first production release logLevel: 'verbose', // in the development environment, use this variable to avoid multiple activation errors. Set it to your development environment variable __ignoreActivationOnFastRefresh: true, } }); console.log('Adapty activated successfully!'); } catch (error) { console.error('Failed to activate Adapty SDK:', error); } ``` :::important Attendez que `activate` soit résolu avant d'appeler toute autre méthode du SDK Adapty. Consultez [L'ordre des appels dans le SDK Capacitor](capacitor-sdk-call-order) pour la séquence complète. ::: :::tip Pour éviter les erreurs d'activation en environnement de développement, utilisez les [conseils](#development-environment-tips). ::: Configurez maintenant les paywalls dans votre application : - Si vous utilisez [Adapty Paywall Builder](adapty-paywall-builder), suivez le [démarrage rapide avec Paywall Builder](capacitor-quickstart-paywalls). - Si vous construisez votre propre interface de paywall, consultez le [démarrage rapide pour les paywalls personnalisés](capacitor-quickstart-manual). ## Activer le module AdaptyUI du SDK Adapty \{#activate-adaptyui-module-of-adapty-sdk\} Si vous prévoyez d'utiliser le [Paywall Builder](adapty-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 \{#optional-setup\} ### Journalisation \{#logging\} #### Configurer le système de journalisation \{#set-up-the-logging-system\} Adapty enregistre les erreurs et d'autres informations importantes pour vous aider à comprendre ce qui se passe. Les niveaux disponibles sont les suivants : | Level | Description | | ---------- | ------------------------------------------------------------ | | `error` | Seules les erreurs seront enregistrées | | `warn` | Les erreurs et les messages du SDK qui ne causent pas d'erreurs critiques, mais qui méritent attention, seront enregistrés | | `info` | Les erreurs, avertissements et divers messages d'information seront enregistrés | | `verbose` | Toute information supplémentaire pouvant être utile lors du débogage, comme les appels de fonctions, les requêtes API, etc., sera enregistrée | Vous pouvez définir le niveau de log dans votre application avant ou pendant la configuration d'Adapty : ```typescript showLineNumbers // Set log level before activation adapty.setLogLevel({ logLevel: 'verbose' }); // Or set it during configuration await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { logLevel: 'verbose', } }); ``` ### Politiques de données \{#data-policies\} Adapty ne stocke pas les données personnelles de vos utilisateurs, sauf si vous les envoyez explicitement. Vous pouvez toutefois mettre en place des politiques de sécurité des données supplémentaires pour respecter les directives du store ou de votre pays. #### Désactiver la collecte et le partage des adresses IP \{#disable-ip-address-collection-and-sharing\} Lors de l'activation du module Adapty, définissez `ipAddressCollectionDisabled` à `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. ```typescript showLineNumbers await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { ipAddressCollectionDisabled: true, } }); ``` #### Désactiver la collecte et le partage de l'identifiant publicitaire \{#disable-advertising-id-collection-and-sharing\} 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 App Tracking Transparency, ou si votre application n'a pas besoin d'attribution publicitaire ni d'analytics basée sur des identifiants publicitaires. ```typescript showLineNumbers await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { ios: { idfaCollectionDisabled: true, }, android: { adIdCollectionDisabled: true, }, } }); ``` #### Configurer le cache média pour AdaptyUI \{#set-up-media-cache-configuration-for-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 : ```typescript showLineNumbers await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { 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 }, } }); ``` | Paramètre | Requis | Description | |-----------|--------|-------------| | memoryStorageTotalCostLimit | optionnel | Taille totale du cache en mémoire, en octets. Valeur par défaut spécifique à la plateforme. | | memoryStorageCountLimit | optionnel | Limite du nombre d'éléments dans le stockage en mémoire. Valeur par défaut spécifique à la plateforme. | | diskStorageSizeLimit | optionnel | Limite de taille des fichiers sur le disque, en octets. Valeur par défaut spécifique à la plateforme. | ### Activer les niveaux d'accès locaux (Android) \{#enable-local-access-levels-android\} Par défaut, les [niveaux d'accès locaux](local-access-levels) sont activés sur iOS et désactivés sur Android. Pour les activer également sur Android, définissez `localAccessLevelAllowed` sur `true` : ```typescript showLineNumbers await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { android: { localAccessLevelAllowed: true, }, } }); ``` ### Effacer les données lors d'une restauration depuis une sauvegarde \{#clear-data-on-backup-restore\} 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 les informations de profil mises 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`. :::note Seul le cache local du SDK est supprimé. L'historique des transactions avec Apple et les données utilisateur sur les serveurs Adapty restent inchangés. ::: ```typescript showLineNumbers await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { ios: { clearDataOnBackup: true, }, } }); ``` ## Conseils pour l'environnement de développement \{#development-environment-tips\} #### Résoudre les erreurs d'activation du SDK avec le rechargement en direct de Capacitor \{#troubleshoot-sdk-activation-errors-on-capacitors-live-reload\} Lors du développement avec le SDK Adapty dans Capacitor, vous pouvez rencontrer l'erreur : `Adapty can only be activated once. Ensure that the SDK activation call is not made more than once.` Ce problème survient car la fonctionnalité de rechargement en direct de Capacitor déclenche plusieurs appels d'activation pendant le développement. Pour l'éviter, utilisez l'option `__ignoreActivationOnFastRefresh` définie sur l'indicateur de mode développement de Capacitor – il diffère selon le bundle que vous utilisez. ```typescript showLineNumbers try { await adapty.activate({ apiKey: 'YOUR_PUBLIC_SDK_KEY', params: { // Set your development environment variable __ignoreActivationOnFastRefresh: true, } }); } catch (error) { console.error('Failed to activate Adapty SDK:', error); // Handle the error appropriately for your app } ``` ## Dépannage \{#troubleshooting\} #### Erreur de version iOS minimale \{#minimum-ios-version-error\} :::note Ceci s'applique aux projets basés sur CocoaPods avec le **SDK 3.x**. Le SDK 4.0 s'installe sur iOS via Swift Package Manager uniquement (il n'y a pas de `Podfile`) et nécessite iOS 15.0 — définissez votre cible de déploiement sur 15.0 dans Xcode. ::: Si vous obtenez une erreur de version iOS minimale avec le SDK 3.x, mettez à jour votre Podfile : ```diff -platform :ios, min_ios_version_supported +platform :ios, '15.0' ``` #### Règles de sauvegarde Android (configuration Auto Backup) \{#android-backup-rules-auto-backup-configuration\} Certains SDKs (dont Adapty) embarquent leur propre configuration Android Auto Backup. Si vous utilisez plusieurs SDKs 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 : `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)` :::note Ces modifications doivent être effectuées dans votre répertoire de la plateforme Android (généralement situé dans le dossier `android/` de votre projet). ::: Pour résoudre ce problème, vous devez : - Indiquer au gestionnaire de fusion de manifeste 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 SDKs. #### 1. Ajoutez l'espace de noms `tools` à votre manifeste \{#1-add-the-tools-namespace-to-your-manifest\} Dans votre fichier `AndroidManifest.xml`, assurez-vous que la balise racine `` inclut tools : ```xml ... ``` #### 2. Remplacez les attributs de sauvegarde dans `` \{#2-override-backup-attributes-in-application\} Dans le même fichier `AndroidManifest.xml`, mettez à jour la balise `` afin que votre application fournisse les valeurs finales et indique au gestionnaire de fusion de remplacer les valeurs des bibliothèques : ```xml ... ``` Si un SDK définit également `android:allowBackup`, incluez-le dans `tools:replace` : ```xml tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules" ``` #### 3. Créez les fichiers de règles de sauvegarde fusionnés \{#3-create-merged-backup-rules-files\} Créez des fichiers XML dans le répertoire `res/xml/` de votre projet Android, en combinant les règles d'Adapty avec celles des autres SDKs. Android utilise des formats de règles de sauvegarde différents selon la version de l'OS, donc créer les deux fichiers garantit la compatibilité avec toutes les versions d'Android prises en charge par votre application. :::note Les exemples ci-dessous utilisent AppsFlyer comme exemple de SDK tiers. Remplacez ou ajoutez des règles pour tout autre SDK que vous utilisez dans votre application. ::: **Pour Android 12 et supérieur** (utilise le nouveau format de règles d'extraction de données) : ```xml title="sample_data_extraction_rules.xml" ``` **Pour Android 11 et inférieur** (utilise l'ancien format de sauvegarde complète) : ```xml title="sample_backup_rules.xml" :::tip Après avoir modifié des fichiers Android natifs, exécutez `npx cap sync android` pour que Capacitor prenne en compte les ressources mises à jour si vous regénérez la plateforme. ::: #### Les achats échouent au retour d'une autre application sur Android \{#purchases-fail-after-returning-from-another-app-in-android\} Si l'Activity qui démarre 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 de l'achat ou son interprétation comme une annulation. Pour vous assurer que les achats fonctionnent correctement, utilisez uniquement les modes de lancement `standard` ou `singleTop` pour l'Activity qui démarre le flux d'achat, et évitez tout autre mode. Dans votre `AndroidManifest.xml`, assurez-vous que l'Activity qui démarre le flux d'achat est configurée sur `standard` ou `singleTop` : ```xml ``` #### Erreurs de build Swift 6 causées par la substitution de SWIFT_VERSION dans le Podfile :::note Cela s'applique aux projets basés sur CocoaPods avec le **SDK 3.x**. Le SDK 4.0 installe les SDK natifs via Swift Package Manager, il n'y a donc pas de `Podfile` à modifier. ::: Lors de la compilation de votre application Capacitor pour iOS, vous pouvez rencontrer des erreurs de compilation Swift 6 sur les targets 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 compiler. Votre propre code d'application peut rester en Swift 5 — seuls les targets des pods Adapty (`Adapty`, `AdaptyUI`, `AdaptyUIBuilder`, `AdaptyLogger`, `AdaptyPlugin`) ont besoin d'être compilés avec Swift 6. La cause la plus fréquente est un hook `post_install` dans `ios/App/Podfile` qui réécrit `SWIFT_VERSION` pour chaque target de pod : ```ruby showLineNumbers title="ios/App/Podfile" 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 : ```ruby showLineNumbers title="ios/App/Podfile" 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 `npx cap sync ios` et recompilez. Pour vérifier, ouvrez `ios/App/Pods/Pods.xcodeproj`, sélectionnez la cible du pod `Adapty` → **Build Settings** → **Swift Language Version**. La valeur devrait être **Swift 6**.