Installer et configurer le SDK Adapty pour Kotlin Multiplatform

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 (io.adapty:adapty-kmp-ui) : Ce module affiche les flows et les paywalls créés avec l’ancien builder via la couche de rendu Compose Multiplatform (view.present()). Si votre projet n’utilise pas Compose Multiplatform, vous pouvez utiliser createNativePaywallView et createNativeOnboardingView depuis le module core à la place.

Pour une présentation complète de l’implémentation, vous pouvez également regarder la vidéo :

Prérequis

Le SDK Adapty Kotlin Multiplatform est compatible avec Xcode 16.2 et versions ultérieures.

Installer le SDK Adapty via Gradle

L’installation du SDK Adapty avec Gradle est requise pour les applications Android et iOS.

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

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

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation libs.adapty.kmp
            }
        }
    }
}

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(libs.adapty.kmp)
            }
        }
    }
}

// libs.versions.toml
[versions]
..
adapty-kmp    = "<the latest SDK version>"

[libraries]
..
adapty-kmp = { module = "io.adapty:adapty-kmp", version.ref = "adapty-kmp" }

// build.gradle.kts

kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(libs.adapty.kmp)
            }
        }
    }
}

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

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

Activer le SDK Adapty

Configuration de base

Ajoutez l’initialisation le plus tôt possible — généralement dans votre code Kotlin partagé pour les deux plateformes.

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .build()

Adapty.activate(configuration = config)
    .onSuccess {
        Log.d("Adapty", "SDK initialised")
    }
    .onError { error ->
        Log.e("Adapty", "Adapty init error: ${error.message}")
    }

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 (PAS la Secret Key).
3. Remplacez "YOUR_PUBLIC_SDK_KEY" dans le code.

Configurez maintenant les paywalls dans votre application :

• Si vous utilisez le Flow & Paywall Builder, commencez par activer le module AdaptyUI ci-dessous, puis 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 prévoyez d’activer le module AdaptyUI pour utiliser le Flow & Paywall Builder, assurez-vous de définir .withActivateUI(true) dans votre configuration.

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withActivateUI(true)           // true for activating the AdaptyUI module
    .build()

Adapty.activate(configuration = config)
    .onSuccess {
        Log.d("Adapty", "SDK initialised")
    }
    .onError { error ->
        Log.e("Adapty", "Adapty init error: ${error.message}")
    }

Configurer Proguard (Android)

Avant de lancer votre application en production, vous devrez peut-être ajouter -keep class com.adapty.** { *; } à votre configuration Proguard.

Configuration optionnelle

Journalisation

Configurer le système de journalisation

Adapty enregistre les erreurs et 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 :

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withLogLevel(AdaptyLogLevel.VERBOSE) // recommended for development
     .build()

Politiques de données

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 requises pour votre application.

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withIpAddressCollectionDisabled(true)
     .build()

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 l’invite App Tracking Transparency, ou si votre application ne nécessite pas d’attribution publicitaire ni d’analytics basés sur des identifiants publicitaires.

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withGoogleAdvertisingIdCollectionDisabled(true)        // Android only
     .withAppleIdfaCollectionDisabled(true)                  // iOS only
     .build()

Configurer le cache média pour AdaptyUI

Par défaut, AdaptyUI met en cache les médias (comme les images et les 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 mediaCache pour remplacer les paramètres de cache par défaut :

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withMediaCacheConfiguration(
        AdaptyConfig.MediaCacheConfiguration(
            memoryStorageTotalCostLimit = 200 * 1024 * 1024, // 200 MB
            memoryStorageCountLimit = Int.MAX_VALUE,
            diskStorageSizeLimit = 200 * 1024 * 1024 // 200 MB
        )
    )
    .build()

Activer les niveaux d’accès locaux (Android)

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

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withGoogleLocalAccessLevelAllowed(true)
    .build()

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

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

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withAppleClearDataOnBackup(true)
    .build()

Activer l’attribution Adapty

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

val config = AdaptyConfig
    .Builder("PUBLIC_SDK_KEY")
    .withAdaptyAttributionEnabled(true)
    .build()

Résolution des problèmes

Règles de sauvegarde Android (configuration d’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 après le retour depuis une autre application sous Android

Si l’Activity qui lance le processus 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 annulé.

Pour que les achats fonctionnent correctement, utilisez uniquement les modes de lancement standard ou singleTop pour l’Activity qui lance le processus d’achat, et évitez tout autre mode.

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

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