Installer et configurer le SDK Adapty 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 requis pour qu’Adapty fonctionne correctement dans votre application.
• AdaptyUI (io.adapty:adapty-kmp-ui) : ce module est nécessaire si vous utilisez le Adapty Paywall Builder avec 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.

Pour un guide d’implémentation complet, 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 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

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 rendez-vous dans 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 Adapty Paywall Builder, activez d’abord le module AdaptyUI ci-dessous, puis 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’activer le module AdaptyUI pour utiliser le Adapty Paywall Builder, veillez à 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 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 :

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 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, respecter les 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) à true pour désactiver la collecte des identifiants publicitaires. La valeur par défaut est false.

Utilisez ce paramètre pour vous conformer aux politiques de l’App Store/Play Store, éviter de déclencher la demande App Tracking Transparency, ou si votre application ne nécessite pas d’attribution publicitaire ni d’analyses basées sur les 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 (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 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 à true :

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

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

Lorsque withAppleClearDataOnBackup est défini à 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, y compris les informations de profil 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.

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

Dépannage

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 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 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 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 garantir le bon fonctionnement des achats, 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 définie sur standard ou singleTop :

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