--- title: "Installer et configurer le SDK Flutter" description: "Guide étape par étape pour installer le SDK Adapty sur Flutter pour les applications basées sur des abonnements." --- Le SDK Adapty comprend deux modules clés pour une intégration fluide dans votre application Flutter : - **Core Adapty** : Ce SDK essentiel est nécessaire 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. :::tip Vous souhaitez voir un exemple concret d'intégration du SDK Adapty dans une application mobile ? Consultez notre [exemple d'application](https://github.com/adaptyteam/AdaptySDK-Flutter/tree/master/example), qui illustre la configuration complète, notamment l'affichage des paywalls, les achats et d'autres fonctionnalités de base. ::: ## Prérequis \{#requirements\} Le SDK Adapty prend en charge iOS 13.0+, mais nécessite iOS 15.0+ pour fonctionner correctement avec les paywalls créés dans le Paywall Builder. Adapty Flutter SDK 4.0 — qui ajoute la prise en charge du [Flow Builder](adapty-flow-builder) — relève les exigences minimales à **iOS 15.0+**, **Xcode 26+** et **Flutter 3.32.0+** (Dart 3.8.0+). Consultez [Adapty SDK 4.0](#adapty-sdk-40-swift-package-manager) ci-dessous pour les détails d'installation. :::info Adapty est compatible avec Google Play Billing Library jusqu'à la version 8.x. Par défaut, Adapty fonctionne avec Google Play Billing Library v7.0.0, mais si vous souhaitez forcer une version ultérieure, vous pouvez [ajouter la dépendance](https://developer.android.com/google/play/billing/integrate#dependency) manuellement. ::: :::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\} [![Release](https://img.shields.io/github/v/release/adaptyteam/AdaptySDK-Flutter.svg?style=flat&logo=flutter)](https://github.com/adaptyteam/AdaptySDK-Flutter/releases) :::important Les étapes ci-dessous installent le dernier SDK stable (3.x). Si vous avez besoin de la v4 — requise pour le [Flow Builder](adapty-flow-builder) et utilisée par le [démarrage rapide](flutter-quickstart-paywalls) — suivez plutôt [Adapty SDK 4.0 : Swift Package Manager](#adapty-sdk-40-swift-package-manager) ci-dessous. ::: 1. Ajoutez Adapty à votre fichier `pubspec.yaml` : ```yaml showLineNumbers title="pubspec.yaml" dependencies: adapty_flutter: ^ ``` 2. Exécutez la commande suivante pour installer les dépendances : ```bash showLineNumbers title="Terminal" flutter pub get ``` 3. Importez les SDK Adapty dans votre application : ```dart showLineNumbers title="main.dart" import 'package:adapty_flutter/adapty_flutter.dart'; ``` ### SDK Adapty 4.0 : Swift Package Manager \{#adapty-sdk-40-swift-package-manager\} Ajoutez Adapty Flutter SDK 4.0 — qui ajoute la prise en charge du [Flow Builder](adapty-flow-builder) — à votre `pubspec.yaml` : ```yaml showLineNumbers title="pubspec.yaml" dependencies: adapty_flutter: 4.0.3 ``` À partir de la v4, le SDK iOS natif n'est plus distribué via CocoaPods — le plugin le récupère uniquement via **Swift Package Manager** ([le dépôt de specs CocoaPods passe en lecture seule en décembre 2026](https://blog.cocoapods.org/CocoaPods-Specs-Repo/)). Si vous utilisez Flutter 3.32–3.43, activez la prise en charge de Swift Package Manager une seule fois : ```bash showLineNumbers title="Terminal" flutter config --enable-swift-package-manager ``` Flutter 3.44 et versions ultérieures activent Swift Package Manager par défaut, aucune action n'est donc nécessaire. Pour les changements d'API dans la v4, consultez le [guide de migration](migration-to-flutter-sdk-v4). ## Activer le module Adapty du SDK \{#activate-adapty-module-of-adapty-sdk\} Activez le SDK dans le code de votre application. :::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. ```dart showLineNumbers title="main.dart" void main() { runApp(MyApp()); } class MyApp extends StatefulWidget { @override _MyAppState createState() => _MyAppState(); } class _MyAppState extends State { @override void initState() { _initializeAdapty(); super.initState(); } Future _initializeAdapty() async { try { await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY'), ); } catch (e) { // handle the error } } Widget build(BuildContext context) { return Text("Hello"); } } ``` :::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 Flutter](flutter-sdk-call-order) pour la séquence complète. ::: Configurez maintenant les paywalls dans votre application : - Si vous utilisez [Adapty Paywall Builder](adapty-paywall-builder), commencez par [activer le module AdaptyUI](#activate-adaptyui-module-of-adapty-sdk) ci-dessous, puis suivez le [guide de démarrage rapide du Paywall Builder](flutter-quickstart-paywalls). - Si vous créez votre propre interface de paywall, consultez le [guide de démarrage rapide pour les paywalls personnalisés](flutter-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) et avez [installé le module AdaptyUI](sdk-installation-flutter#install-adapty-sdk), vous devez également activer AdaptyUI : :::note Les dépendances liées à AdaptyUI sont liées à votre application, que AdaptyUI soit activé ou non. ::: :::important Dans votre code, vous devez activer le module Adapty principal avant d'activer AdaptyUI. ::: ```dart showLineNumbers title="main.dart" await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withActivateUI(true), // This automatically activates AdaptyUI ); ``` ## 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 suivants sont disponibles : | Level | Description | | :----------------------- | :------------------------------------------------------------------------------------------------------------------------ | | `AdaptyLogLevel.error` | Seules les erreurs seront journalisées | | `AdaptyLogLevel.warn` | Les erreurs et les messages du SDK qui ne causent pas d'erreurs critiques, mais méritent attention, seront journalisés. | | `AdaptyLogLevel.info` | Les erreurs, avertissements et divers messages d'information seront journalisés. Valeur par défaut | | `AdaptyLogLevel.verbose` | Toute information supplémentaire utile au débogage, comme les appels de fonctions, les requêtes API, etc., sera journalisée. | | `AdaptyLogLevel.debug` | Les informations de débogage seront journalisées. | Vous pouvez définir le niveau de log dans votre application avant de configurer Adapty : ```dart showLineNumbers title="main.dart" // Set log level before activation. // 'verbose' is recommended for development and the first production release await Adapty().setLogLevel(AdaptyLogLevel.verbose); // Or set it during configuration await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withLogLevel(AdaptyLogLevel.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é supplémentaires pour respecter les règles du store ou les réglementations 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` 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 nécessaires pour votre application. ```dart showLineNumbers title="main.dart" await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withIpAddressCollectionDisabled(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 `appleIdfaCollectionDisabled` (iOS) ou `googleAdvertisingIdCollectionDisabled` (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'une attribution publicitaire ou d'analyses basées sur les identifiants publicitaires. ```dart showLineNumbers title="main.dart" await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withAppleIdfaCollectionDisabled(true) // iOS ..withGoogleAdvertisingIdCollectionDisabled(true), // Android ); ``` #### Configurer le cache média pour AdaptyUI \{#set-up-media-cache-configuration-for-adaptyui\} Le module est activé automatiquement avec le SDK Adapty. Si vous n'utilisez pas le Paywall Builder et souhaitez désactiver le module AdaptyUI, passez `withActivateUI(false)` lors de l'activation. Par défaut, AdaptyUI met en cache les médias (images et vidéos) pour améliorer les performances et réduire la consommation réseau. Vous pouvez personnaliser les paramètres du cache en fournissant une configuration personnalisée. Utilisez `withMediaCacheConfiguration` pour remplacer les limites du cache par défaut. C'est facultatif — si vous n'appelez pas cette méthode, les valeurs par défaut seront utilisées (100 Mo sur disque, nombre illimité en mémoire). En revanche, si vous créez l'objet de configuration, tous ses paramètres sont obligatoires. ```dart showLineNumbers title="main.dart" final mediaCacheConfig = AdaptyUIMediaCacheConfiguration( memoryStorageTotalCostLimit: 200 * 1024 * 1024, // 200 MB memoryStorageCountLimit: 2147483647, // max int value diskStorageSizeLimit: 200 * 1024 * 1024, // 200 MB ); await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withMediaCacheConfiguration(mediaCacheConfig), ); ``` **Paramètres :** | Paramètre | Présence | Description | |-------------------------|----------|-----------------------------------------------------------------------------| | memoryStorageTotalCostLimit | requis | Taille totale du cache en mémoire en octets. La valeur par défaut est 100 Mo. | | memoryStorageCountLimit | requis | Limite du nombre d'éléments dans le stockage en mémoire. La valeur par défaut est la valeur int maximale. | | diskStorageSizeLimit | requis | Limite de taille des fichiers sur disque en octets. La valeur par défaut est 100 Mo. | ### 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 `withGoogleLocalAccessLevelAllowed` sur `true` : ```dart showLineNumbers title="main.dart" await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withGoogleLocalAccessLevelAllowed(true), ); ``` ### Effacer les données lors d'une restauration depuis une sauvegarde \{#clear-data-on-backup-restore\} Lorsque `appleClearDataOnBackup` 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 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`. :::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. ::: ```dart showLineNumbers title="main.dart" await Adapty().activate( configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY') ..withAppleClearDataOnBackup(true) // default – false ); ``` ## Dépannage \{#troubleshooting\} #### Règles de sauvegarde Android (configuration de l'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" #### Les achats échouent après être revenu 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 de façon incorrecte 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 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 définie sur `standard` ou `singleTop` : ```xml ``` #### Erreurs de build Swift 6 causées par le remplacement de SWIFT_VERSION dans le Podfile \{#swift-6-build-errors-caused-by-podfile-swift_version-override\} Lors de la compilation de votre application Flutter 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`, l'absence de conformité `Sendable` 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. Le code de votre propre application peut rester en Swift 5 — seules les cibles de pods Adapty (`Adapty`, `AdaptyUI`, `AdaptyUIBuilder`, `AdaptyLogger`, `AdaptyPlugin`) ont besoin d'être compilées avec Swift 6. La cause la plus fréquente est un hook `post_install` dans `ios/Podfile` qui réécrit `SWIFT_VERSION` pour toutes les cibles de pods : ```ruby showLineNumbers title="ios/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 ``` **Fix** : Excluez les cibles de pods Adapty de la substitution : ```ruby showLineNumbers title="ios/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 `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**. La valeur doit être **Swift 6**.