Installer et configurer le SDK Android

Le SDK Adapty comprend deux modules clés pour une intégration fluide dans votre application mobile :

• Core Adapty : Ce SDK essentiel est nécessaire au bon fonctionnement d’Adapty dans votre application.
• AdaptyUI : Ce module est requis si vous utilisez le Adapty Paywall Builder, un outil no-code convivial pour créer facilement des paywalls multiplateformes. AdaptyUI est automatiquement activé avec le module principal.

Prérequis

Version minimale du SDK : minSdkVersion 21

Installer le SDK Adapty

Choisissez votre méthode de configuration des dépendances :

• Gradle standard : Ajoutez les dépendances dans votre build.gradle au niveau du module
• Si votre projet utilise des fichiers .gradle.kts, ajoutez les dépendances dans votre build.gradle.kts au niveau du module
• Si vous utilisez des catalogues de versions, ajoutez les dépendances dans votre fichier libs.versions.toml, puis référencez-les dans build.gradle.kts

dependencies {
    ...
    implementation platform('io.adapty:adapty-bom:<the latest SDK version>')
    implementation 'io.adapty:android-sdk'

    // Only add this line if you plan to use Paywall Builder
    implementation 'io.adapty:android-ui'
}

dependencies {
    ...
    implementation(platform("io.adapty:adapty-bom:<the latest SDK version>"))
    implementation("io.adapty:android-sdk")

    // Only add this line if you plan to use Paywall Builder:
    implementation("io.adapty:android-ui")
}

//libs.versions.toml

[versions]
..
adaptyBom = "<the latest SDK version>"

[libraries]
..
adapty-bom = { module = "io.adapty:adapty-bom", version.ref = "adaptyBom" }
adapty = { module = "io.adapty:android-sdk" }

// Only add this line if you plan to use Paywall Builder:
adapty-ui = { module = "io.adapty:android-ui" }

//module-level build.gradle.kts

dependencies {
    ...
    implementation(platform(libs.adapty.bom))
    implementation(libs.adapty)

    // Only add this line if you plan to use Paywall Builder:
    implementation(libs.adapty.ui)
}

Si la dépendance n’est pas résolue, assurez-vous que vous avez mavenCentral() dans vos scripts Gradle.

allprojects {
    repositories {
        ...
        mavenCentral()
    }
}

dependencyResolutionManagement {
    ...
    repositories {
        ...
        mavenCentral()
    }
}

Activer le module Adapty du SDK Adapty

Configuration de base

Activez le SDK Adapty 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.

// In your Application class

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Adapty.activate(
            applicationContext,
            AdaptyConfig.Builder("PUBLIC_SDK_KEY")
                .build()
        )
    }
}

// In your Application class

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Adapty.activate(
            getApplicationContext(),
            new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
                .build()
        );
    }
}

Configurez maintenant les paywalls dans votre application :

• Si vous utilisez Adapty Paywall Builder, suivez le démarrage rapide avec Paywall Builder.
• Si vous créez votre propre interface de paywall, consultez le démarrage rapide pour les paywalls personnalisés.

Activer le module AdaptyUI du SDK Adapty

Si vous prévoyez d’utiliser le 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.

Configurer Proguard

Avant de lancer votre application en production, ajoutez -keep class com.adapty.** { *; } à votre configuration Proguard.

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 log dans votre application avant de configurer Adapty.

Adapty.logLevel = AdaptyLogLevel.VERBOSE
//recommended for development and the first production release

Adapty.setLogLevel(AdaptyLogLevel.VERBOSE);
//recommended for development and the first production release

Rediriger les messages du système de journalisation

Si vous avez besoin pour une raison quelconque d’envoyer les messages d’Adapty vers votre système ou de les sauvegarder dans un fichier, vous pouvez remplacer le comportement par défaut :

Adapty.setLogHandler { level, message ->
    //handle the log
}

Adapty.setLogHandler((level, message) -> {
    //handle the log
});

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 directives du store ou des réglementations locales.

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.

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withIpAddressCollectionDisabled(true)
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withIpAddressCollectionDisabled(true)
    .build();

Désactiver la collecte et le partage de l’identifiant publicitaire (Ad ID)

Lors de l’activation du module Adapty, définissez adIdCollectionDisabled sur true pour désactiver la collecte de l’identifiant publicitaire de l’utilisateur. La valeur par défaut est false.

Utilisez ce paramètre pour respecter les règles du Play Store, éviter de déclencher la demande d’autorisation pour l’identifiant publicitaire, ou si votre application ne nécessite pas d’attribution publicitaire ni d’analyse basée sur l’Ad ID.

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withAdIdCollectionDisabled(true)
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withAdIdCollectionDisabled(true)
    .build();

Activer l’Attribution Adapty

À partir de la version 4.1 du SDK Adapty, l’Attribution Adapty est désactivée par défaut. Lors de l’activation du module Adapty, définissez adaptyAttributionEnabled sur true pour permettre au SDK d’enregistrer les installations et de transmettre les détails d’installation à votre application.

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withAdaptyAttributionEnabled(true)
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withAdaptyAttributionEnabled(true)
    .build();

Dans les versions du SDK inférieures à 4.1, l’attribution Adapty est activée automatiquement — aucune modification du code n’est nécessaire.

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 les paramètres du cache en fournissant une configuration personnalisée.

Utilisez AdaptyUI.configureMediaCache pour modifier la taille du cache et la durée de validité par défaut. Cette étape est facultative — si vous n’appelez pas cette méthode, les valeurs par défaut seront utilisées (100 Mo sur le disque, validité de 7 jours).

val cacheConfig = MediaCacheConfiguration.Builder()
    .overrideDiskStorageSizeLimit(200L * 1024 * 1024) // 200 MB
    .overrideDiskCacheValidityTime(3.days)
    .build()

AdaptyUI.configureMediaCache(cacheConfig)

MediaCacheConfiguration cacheConfig = new MediaCacheConfiguration.Builder()
    .overrideDiskStorageSizeLimit(200L * 1024 * 1024) // 200 MB
    .overrideDiskCacheValidityTime(TimeInterval.days(3))
    .build();

AdaptyUI.configureMediaCache(cacheConfig);

Paramètres :

Définir des identifiants de compte obscurcis

Google Play exige des identifiants de compte obscurcis dans certains cas d’utilisation pour renforcer la confidentialité et la sécurité des utilisateurs. Ces identifiants permettent à Google Play d’identifier les achats tout en gardant les informations des utilisateurs anonymes, ce qui est particulièrement important pour la prévention de la fraude et l’analyse.

Vous devrez peut-être définir ces identifiants si votre application traite des données utilisateur sensibles ou si vous devez vous conformer à des réglementations spécifiques en matière de confidentialité. Les identifiants obscurcis permettent à Google Play de suivre les achats sans exposer les véritables identifiants des utilisateurs.

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withObfuscatedAccountId("YOUR_OBFUSCATED_ACCOUNT_ID")
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withObfuscatedAccountId("YOUR_OBFUSCATED_ACCOUNT_ID")
    .build();

Exécuter Adapty dans un processus personnalisé

Par défaut, Adapty ne peut s’exécuter que dans le processus principal de votre application. Si votre application utilise plusieurs processus, initialisez Adapty une seule fois ; sinon, un comportement inattendu pourrait se produire.

Si vous avez besoin d’exécuter Adapty dans un processus différent, spécifiez-le dans votre configuration :

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withProcessName(":custom")
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withProcessName(":custom")
    .build();

Si vous essayez d’activer Adapty dans un autre processus sans définir cette valeur, le SDK va enregistrer un avertissement et ignorer l’activation.

Activer les niveaux d’accès locaux

Par défaut, les niveaux d’accès locaux sont désactivés sur Android. Pour les activer, définissez withLocalAccessLevelAllowed sur true :

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withLocalAccessLevelAllowed(true)
    .build()

new AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withLocalAccessLevelAllowed(true)
    .build();

Dépannage

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

Certains SDK (dont Adapty) embarquent leur propre configuration d’Auto Backup Android. Si vous utilisez plusieurs SDK qui définissent des règles de sauvegarde, la fusion de 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/sample_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 manifest merger d’utiliser les valeurs de votre application pour les attributs liés à la sauvegarde.

• Fusionner les règles de sauvegarde d’Adapty et des autres SDK dans un seul fichier XML (ou une paire de fichiers pour Android 12+).

1. Ajoutez l’espace de noms tools à votre manifest

Si ce n’est pas déjà fait, ajoutez l’espace de noms tools à la balise racine <manifest> :

<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 fichier AndroidManifest.xml de votre application, mettez à jour la balise <application> afin que votre application fournisse les valeurs finales et indique au processeur de fusion de manifeste de remplacer les valeurs de la bibliothèque :

<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 des fichiers de règles de sauvegarde fusionnés

Créez des fichiers XML dans app/src/main/res/xml/ qui combinent les règles d’Adapty avec celles des autres SDK. Android utilise différents formats de règles de sauvegarde selon la version de l’OS, donc créer les deux fichiers garantit la compatibilité avec toutes les versions Android que votre application prend en charge.

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 versions inférieures (utilise le format legacy 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"/>



</full-backup-content>

Avec cette configuration :

• Les exclusions de sauvegarde d’Adapty (AdaptySDKPrefs.xml) sont préservées.

• Les exclusions des autres SDK (par exemple, appsflyer-data) sont également appliquées.

• Le fusion du manifeste utilise la configuration de votre application et n’échoue plus sur des attributs de sauvegarde en conflit.

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

Si l’Activity qui lance le flow d’achat utilise un launchMode non standard, Android peut la recréer ou la réutiliser de manière incorrecte lorsque l’utilisateur revient depuis Google Play, une application bancaire ou 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 lance le flow d’achat, et évitez tout autre mode.

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

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