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

Prérequis

Le SDK Adapty pour Capacitor exige les versions suivantes :

Version du SDK Adapty	Version de Capacitor	Version iOS
4.1+	8	15.0+
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 compilation pour iOS requiert Xcode 26 ou une version ultérieure — le SDK iOS natif est construit avec Swift tools 6.2. Sur Android, le SDK minimum est 24.

Installer le SDK Adapty

Installez le SDK Adapty :

npm install @adapty/capacitor
npx cap sync

Sur iOS, le SDK Adapty 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). Le projet iOS de votre application doit utiliser l’intégration SPM de Capacitor :

• Pour les nouvelles apps, ajoutez la plateforme iOS avec le gestionnaire de paquets SPM :

  npx cap add ios --packagemanager SPM

• Pour les apps existantes, migrez le projet iOS de CocoaPods vers SPM en suivant le guide Capacitor pour utiliser SPM dans un projet existant.

Vous mettez à jour depuis la v3 ? Consultez Migrer le SDK Adapty Capacitor vers la v4.1 pour la liste complète des changements d’API.

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 n’importe quel fichier de l’application pour activer Adapty :

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

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 souhaitez utiliser le Flow & Paywall Builder, vous aurez besoin du module AdaptyUI. Il est activé 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 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 :

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

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

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.

await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    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 App Tracking Transparency, ou si votre application n’a pas besoin d’attribution publicitaire ni d’analytics basée sur des identifiants publicitaires.

await adapty.activate({
  apiKey: 'YOUR_PUBLIC_SDK_KEY',
  params: {
    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 :

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)

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 :

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

Effacer les données lors d’une restauration depuis une 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 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.

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

Activer l’attribution Adapty

Si vous utilisez Adapty Attribution, 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 informations d’installation à votre application. Dans les versions du SDK antérieures à 4.1, Adapty Attribution est activé automatiquement.

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

Conseils pour l’environnement de développement

Résoudre les erreurs d’activation du SDK avec le rechargement en direct de Capacitor

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.

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

Erreur de version iOS minimale

Si vous obtenez une erreur de version iOS minimale avec le SDK 3.x, mettez à jour votre Podfile :

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

Règles de sauvegarde Android (configuration 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 au retour 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 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 :

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

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

Lors de la compilation de votre application Capacitor pour iOS, vous pouvez rencontrer des erreurs de compilation Swift 6 sur les cibles de pod 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 :

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