---
title: "Installer et configurer le SDK Adapty Kotlin Multiplatform"
description: "Installez et configurez le SDK Adapty pour les applications 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](adapty-paywall-builder) avec la couche de rendu Compose Multiplatform (`view.present()`). Si votre projet n'utilise pas Compose Multiplatform, vous pouvez utiliser [`createNativePaywallView`](kmp-present-paywalls#without-compose-multiplatform) et [`createNativeOnboardingView`](kmp-present-onboardings#without-compose-multiplatform) depuis le module core.

:::tip
Vous voulez voir un exemple concret d'intégration du SDK Adapty dans une application mobile ? Consultez notre [exemple d'application](https://github.com/adaptyteam/AdaptySDK-KMP/tree/main/example), qui illustre la configuration complète, notamment l'affichage des paywalls, les achats et d'autres fonctionnalités de base.
:::

Pour un guide d'implémentation complet, vous pouvez également regarder la vidéo :

<iframe width="560" height="315" src="https://www.youtube.com/embed/JfwJvwnloNw?si=HskPxRk4WGkF_u9s" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Prérequis \{#requirements\}

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

:::info
À partir du SDK v3.17, le SDK Adapty utilise Google Play Billing Library v8.0.0 par défaut.
:::

:::info
L'installation du SDK correspond à l'étape 5 de la configuration d'Adapty. Avant que les achats fonctionnent dans votre app, vous devez également connecter votre app aux stores, puis créer des produits, un paywall et un placement dans l'Adapty Dashboard. Le [guide de démarrage rapide](quickstart) décrit toutes les étapes requises.
:::

## Installer le SDK Adapty via Gradle \{#install-adapty-sdk-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`

:::important
Le SDK Adapty Kotlin Multiplatform 4.0 est une version préliminaire. Gradle ne sélectionne pas les versions préliminaires via les plages de versions dynamiques (comme `+` ou `latest.release`), vous devez donc fixer la version exacte — par exemple `io.adapty:adapty-kmp:4.0.0-beta.1`, ou `adapty-kmp = "4.0.0-beta.1"` dans `libs.versions.toml`. Consultez [Migrer le SDK Adapty Kotlin Multiplatform vers v4](migration-to-kmp-sdk-v4).
:::

<Tabs>
<TabItem value="module-level build.gradle" label="module-level build.gradle" default>

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

</TabItem>
<TabItem value="module-level build.gradle.kts" label="module-level build.gradle.kts" default>

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

</TabItem>

<TabItem value="version-catalog" label="Versions library" default>

```toml showLineNumbers
// 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)
            }
        }
    }
}

```

</TabItem>
</Tabs>

:::note
Si vous obtenez une erreur liée à Maven, vérifiez que vous avez bien `mavenCentral()` dans vos scripts Gradle.

<details>
   <summary>Les instructions pour l'ajouter</summary>

Si votre projet n'a pas de `dependencyResolutionManagement` dans votre `settings.gradle`, ajoutez ce qui suit dans votre `build.gradle` de niveau supérieur, à la fin de la section repositories :

```groovy showLineNumbers title="top-level build.gradle"
allprojects {
    repositories {
        ...
        mavenCentral()
    }
}
```

Sinon, ajoutez ce qui suit dans votre `settings.gradle`, dans la section `repositories` de `dependencyResolutionManagement` :

```groovy showLineNumbers title="settings.gradle"
dependencyResolutionManagement {
    ...
    repositories {
        ...
        google()
        mavenCentral()
    }
}
```

</details>
:::

## Activer le SDK Adapty \{#activate-adapty-sdk\}

### Configuration de base \{#basic-setup\}

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

:::note
Le SDK Adapty ne doit être activé qu'une seule fois dans votre application.
:::

```kotlin title="Kotlin" showLineNumbers

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}")
    }
```

:::important
Attendez que `activate` se termine avant d'appeler toute autre méthode du SDK Adapty. Consultez [Ordre des appels dans le SDK Kotlin Multiplatform](kmp-sdk-call-order) pour la séquence complète.
:::

Pour obtenir votre **Public SDK Key** :

1. Accédez à l'Adapty Dashboard et rendez-vous dans [App settings → General](https://app.adapty.io/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.

:::info
- Assurez-vous d'utiliser la Public SDK Key pour initialiser Adapty ; la Secret Key doit être utilisée uniquement pour l'[API côté serveur](getting-started-with-server-side-api).
- Les clés SDK sont uniques pour chaque application, donc si vous avez plusieurs applications, assurez-vous de choisir la bonne.
  :::

Configurez maintenant les paywalls dans votre application :

- Si vous utilisez [Adapty Paywall Builder](adapty-paywall-builder), activez d'abord le [module AdaptyUI](#activate-adaptyui-module-of-adapty-sdk) ci-dessous, puis suivez le [démarrage rapide avec Paywall Builder](kmp-quickstart-paywalls).
- Si vous créez votre propre interface de paywall, consultez le [démarrage rapide pour les paywalls personnalisés](kmp-quickstart-manual).

## Activer le module AdaptyUI du SDK Adapty \{#activate-adaptyui-module-of-adapty-sdk\}

Si vous prévoyez d'activer le module **AdaptyUI** pour utiliser le [Adapty Paywall Builder](kmp-present-paywalls), veillez à définir `.withActivateUI(true)` dans votre configuration.

:::info
important
Dans votre code, vous devez activer le module core Adapty avant d'activer AdaptyUI.
:::

```kotlin title="Kotlin" showLineNumbers

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) \{#configure-proguard-android\}

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

## Configuration optionnelle \{#optional-setup\}

### Journalisation \{#logging\}

#### Configurer le système de journalisation \{#set-up-the-logging-system\}

Adapty enregistre les erreurs et d'autres informations importantes pour vous aider à comprendre ce qui se passe. Les niveaux suivants sont disponibles :

| Niveau                   | Description                                                                                                                              |
| :----------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `AdaptyLogLevel.ERROR`   | Seules les erreurs seront journalisées.                                                                                                  |
| `AdaptyLogLevel.WARN`    | Les erreurs et les messages du SDK qui ne causent pas d'erreurs critiques, mais méritent attention, seront journalisés.                  |
| `AdaptyLogLevel.INFO`    | Les erreurs, avertissements et divers messages d'information seront journalisés. Valeur par défaut.                                      |
| `AdaptyLogLevel.VERBOSE` | Toute information supplémentaire pouvant être utile lors du débogage, comme les appels de fonctions, les requêtes API, etc., sera journalisée. |
| `AdaptyLogLevel.DEBUG`   | Les informations les plus détaillées, y compris les données de débogage internes, seront journalisées.                                   |

Vous pouvez définir le niveau de journalisation dans votre application avant de configurer Adapty :

```kotlin title="Kotlin" showLineNumbers

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

### Politiques de données \{#data-policies\}

#### Désactiver la collecte et le partage de l'adresse IP \{#disable-ip-address-collection-and-sharing\}

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.

```kotlin title="Kotlin" showLineNumbers

val config = AdaptyConfig
     .Builder("PUBLIC_SDK_KEY")
     .withIpAddressCollectionDisabled(true)
     .build()
```
#### Désactiver la collecte et le partage de l'identifiant publicitaire \{#disable-advertising-id-collection-and-sharing\}

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.

```kotlin title="Kotlin" showLineNumbers

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

#### Configurer le cache média pour AdaptyUI \{#set-up-media-cache-configuration-for-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 :

```kotlin

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) \{#enable-local-access-levels-android\}

Par défaut, les [niveaux d'accès locaux](local-access-levels) sont désactivés pour Android. Pour les activer, définissez `withLocalAccessLevelAllowed` à `true` :

```kotlin title="Kotlin" showLineNumbers

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

### Effacer les données lors de la restauration d'une sauvegarde \{#clear-data-on-backup-restore\}

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`.

:::note
Seul le cache local du SDK est supprimé. L'historique des transactions avec Apple et les données utilisateur sur les serveurs Adapty restent inchangés.
:::

```swift showLineNumbers

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

## Dépannage \{#troubleshooting\}

####  Règles de sauvegarde Android (configuration Auto Backup) \{#android-backup-rules-auto-backup-configuration\}

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)`

:::note
Ces modifications doivent être effectuées dans votre répertoire de la plateforme Android (généralement situé dans le dossier `android/` de votre projet).
:::

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 \{#1-add-the-tools-namespace-to-your-manifest\}

Dans votre fichier `AndroidManifest.xml`, assurez-vous que la balise racine `<manifest>` inclut tools :

```xml
<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>` \{#2-override-backup-attributes-in-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 :

```xml
<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` :

```xml
tools:replace="android:allowBackup,android:fullBackupContent,android:dataExtractionRules"
```

#### 3. Créez les fichiers de règles de sauvegarde fusionnés \{#3-create-merged-backup-rules-files\}

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.

:::note
Les exemples ci-dessous utilisent AppsFlyer comme exemple de SDK tiers. Remplacez ou ajoutez des règles pour tout autre SDK que vous utilisez dans votre application.
:::

**Pour Android 12 et supérieur** (utilise le nouveau format de règles d'extraction de données) :

```xml title="sample_data_extraction_rules.xml"
<?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 title="sample_backup_rules.xml"
<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    
    <exclude domain="sharedpref" path="appsflyer-data"/>

    
    <exclude domain="sharedpref" path="AdaptySDKPrefs.xml"/>

:::important
Dans un projet Kotlin Multiplatform, appliquez ces modifications dans le module d'application Android (celui qui produit l'APK/AAB), par exemple `androidApp` ou `app` :
- Manifest : `androidApp/src/main/AndroidManifest.xml`
- XML des règles de sauvegarde : `androidApp/src/main/res/xml/`
:::

#### Les achats échouent après être revenu d'une autre application sur Android \{#purchases-fail-after-returning-from-another-app-in-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` :

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