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, un outil no-code convivial pour créer facilement des paywalls multiplateformes.

Prérequis

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 — relève les exigences minimales à iOS 15.0+, Xcode 26+ et Flutter 3.32.0+ (Dart 3.8.0+). Consultez Adapty SDK 4.0 ci-dessous pour les détails d’installation.

Installer le SDK Adapty

1. Ajoutez Adapty à votre fichier pubspec.yaml :

   dependencies: 
     adapty_flutter: ^<the latest SDK version>

2. Exécutez la commande suivante pour installer les dépendances :

   flutter pub get

3. Importez les SDK Adapty dans votre application :

   import 'package:adapty_flutter/adapty_flutter.dart';

SDK Adapty 4.0 : Swift Package Manager

Ajoutez Adapty Flutter SDK 4.0 — qui ajoute la prise en charge du Flow Builder — à votre 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). Si vous utilisez Flutter 3.32–3.43, activez la prise en charge de Swift Package Manager une seule fois :

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.

Activer le module Adapty du SDK

Activez le SDK dans le code de votre application.

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.

void main() {
  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    _initializeAdapty();

    super.initState();
  }

  Future<void> _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");
  }
}

Configurez maintenant les paywalls dans votre application :

• Si vous utilisez Adapty Paywall Builder, commencez par activer le module AdaptyUI ci-dessous, puis suivez le guide de démarrage rapide du Paywall Builder.
• 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 Paywall Builder et avez installé le module AdaptyUI, vous devez également activer AdaptyUI :

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withActivateUI(true), // This automatically activates AdaptyUI
);

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 :

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 :

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

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

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.

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withIpAddressCollectionDisabled(true),
);

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

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.

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withAppleIdfaCollectionDisabled(true)      // iOS
    ..withGoogleAdvertisingIdCollectionDisabled(true), // Android
);

Configurer le cache média pour 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.

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)

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 withGoogleLocalAccessLevelAllowed sur true :

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withGoogleLocalAccessLevelAllowed(true),
);

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

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.

await Adapty().activate(
  configuration: AdaptyConfiguration(apiKey: 'YOUR_PUBLIC_SDK_KEY')
    ..withAppleClearDataOnBackup(true) // default – false
);

Dépannage

Règles de sauvegarde Android (configuration de l’Auto Backup)

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)

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

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. Remplacez 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, incluez-le dans tools:replace :

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

3. Créez les fichiers de règles de sauvegarde fusionnés

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.

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 être revenu d’une autre application sur 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 :

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

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

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 :

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 :

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.