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 requis pour qu’Adapty fonctionne correctement 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. AdaptyUI est automatiquement activé en même temps que le module principal.

Prérequis

Version SDK minimale requise : minSdkVersion 21

Installer le SDK Adapty

Choisissez votre méthode de gestion 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 ne se résout pas, vérifiez que vous avez bien 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 lorsque vous activez le 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 journalisation 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, mais vous pouvez mettre en œuvre des politiques de sécurité des données supplémentaires pour vous conformer aux directives du store ou du pays.

Désactiver la collecte et le partage de l’adresse IP

Lors de l’activation du module Adapty, définissez ipAddressCollectionDisabled à true pour désactiver la collecte et le partage de l’adresse IP de l’utilisateur. La valeur par défaut est false.

Utilisez ce paramètre pour renforcer la confidentialité des utilisateurs, vous conformer aux réglementations régionales sur la 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 requises 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 à 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 vous conformer aux politiques du Play Store, éviter de déclencher l’invite de permission pour l’identifiant publicitaire, ou si votre application ne nécessite pas d’attribution publicitaire ni d’analyses basées sur l’Ad ID.

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

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

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 remplacer la taille du cache et la durée de validité par défaut. C’est optionnel — si vous n’appelez pas cette méthode, les valeurs par défaut seront utilisées (100 Mo sur disque, 7 jours de validité).

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’usage 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 des fraudes et les analyses.

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 de confidentialité spécifiques. Les identifiants obscurcis permettent à Google Play de suivre les achats sans exposer les identifiants réels 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, n’initialisez Adapty qu’une seule fois ; sinon, un comportement inattendu peut survenir.

Si vous devez 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 tentez d’activer Adapty dans un autre processus sans définir cette valeur, le SDK enregistrera un avertissement et ignorera 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 à true :

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

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

Résolution des problèmes

Règles de sauvegarde Android (configuration 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 d’erreur typiques : 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 fusionneur de manifeste 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 SDKs dans un seul fichier XML (ou une paire de fichiers pour Android 12+).

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

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 AndroidManifest.xml de votre application, mettez à jour la balise <application> pour que votre application fournisse les valeurs finales et indique au fusionneur de manifeste 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 des fichiers de règles de sauvegarde fusionnées

Créez des fichiers XML dans app/src/main/res/xml/ qui combinent les règles d’Adapty avec celles des autres SDKs. Android utilise différents formats de règles de sauvegarde selon la version du système, 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 inférieur (utilise l’ancien format de contenu 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 SDKs (par exemple, appsflyer-data) sont également appliquées.

• Le fusionneur de manifeste utilise la configuration de votre application et n’échoue plus sur les attributs de sauvegarde conflictuels.

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

Si l’Activity qui démarre le flux 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 annulé.

Pour 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, vérifiez que l’Activity qui démarre le flux d’achat est définie sur standard ou singleTop :

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