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 Paywall Builder d’Adapty 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-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 Adapty Paywall Builder, commencez par activer le module AdaptyUI ci-dessous, puis suivez le guide de démarrage rapide du Paywall Builder.
• 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 Paywall Builder d’Adapty, 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()

Résolution des problèmes

Règles de sauvegarde Android (configuration d’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 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" />