---
title: "Installer et configurer le SDK Unity"
description: "Guide étape par étape pour installer le SDK Adapty sur Unity pour les applications basées sur des abonnements."
---

Le SDK Adapty comprend deux modules essentiels pour une intégration fluide dans votre application Unity :

- **Core Adapty** : ce SDK de base est nécessaire au bon fonctionnement d'Adapty dans votre application.
- **AdaptyUI** : ce module est requis si vous utilisez le [Paywall Builder d'Adapty](adapty-paywall-builder), un outil no-code convivial pour créer facilement des paywalls multiplateformes.

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

## Prérequis \{#requirements\}

Le SDK Adapty est compatible avec iOS 13.0+, mais nécessite iOS 15.0+ pour utiliser les paywalls créés dans le Paywall Builder. Le SDK Adapty 4.0 (bêta) — qui ajoute la prise en charge du [Flow Builder](adapty-flow-builder) — exige **iOS 15.0+** pour l'ensemble de l'application : un validateur de build dans l'Unity Editor bloque la compilation iOS si la cible de déploiement est inférieure.

:::info
Adapty est compatible avec Google Play Billing Library jusqu'à la version 8.x. Par défaut, Adapty utilise la version 7.0.0 de Google Play Billing Library. Pour utiliser une version plus récente, [remplacez la dépendance Billing](https://developer.android.com/google/play/billing/integrate#dependency) dans votre build Android.
:::

:::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 \{#install-adapty-sdk\}

[![Release](https://img.shields.io/github/v/release/adaptyteam/AdaptySDK-Unity.svg?style=flat&logo=unity)](https://github.com/adaptyteam/AdaptySDK-Unity/releases)

Choisissez votre méthode d'installation préférée :

<Tabs groupId="unity-install-method">

<TabItem value="git-url" label="Git URL">

Installez le SDK Adapty via Unity Package Manager en utilisant une URL Git :

1. Dans Unity, ouvrez **Window → Package Manager**.
2. Cliquez sur **+** en haut à gauche, puis sélectionnez **Add package from git URL...**.
3. Saisissez l'URL suivante et cliquez sur **Add** :

```
https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk
```

Pour plus de détails, consultez le guide Unity sur [l'installation d'un package UPM depuis une URL Git](https://docs.unity3d.com/Manual/upm-ui-giturl.html).

</TabItem>

<TabItem value="unity-package" label="Unity package" default>

Téléchargez le [`adapty-unity-plugin-*.unitypackage`](https://github.com/adaptyteam/AdaptySDK-Unity/tree/main/Releases) depuis GitHub et importez-le dans votre projet.

  <img src="/assets/shared/img/456bd98-adapty-unity-plugin.webp"
  style={{
    border: 'none', /* border width and color */
    width: '400px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

</TabItem>

</Tabs>

Après avoir installé le SDK, effectuez les étapes suivantes :

1. Installez le [plugin External Dependency Manager (EDM)](https://github.com/googlesamples/unity-jar-resolver#getting-started). Le SDK Adapty l'utilise pour gérer les dépendances iOS et les dépendances gradle Android.

2. Après avoir installé EDM, vous devrez peut-être invoquer le gestionnaire de dépendances :

   `Assets -> External Dependency Manager -> Android Resolver -> Force Resolve`

   et

   `Assets -> External Dependency Manager -> iOS Resolver -> Install Cocoapods`

3. Lors de la compilation de votre projet Unity pour iOS, vous obtiendrez un fichier `Unity-iPhone.xcworkspace`, que vous devez ouvrir à la place de `Unity-iPhone.xcodeproj`, sinon les dépendances Cocoapods ne seront pas utilisées.

### Adapty SDK 4.0 (bêta)

SDK 4.0 — qui ajoute la prise en charge du [Flow Builder](adapty-flow-builder) — est une version préliminaire. Pour l'installer via le Unity Package Manager, ajoutez le tag bêta à l'URL Git :

```
https://github.com/adaptyteam/AdaptySDK-Unity.git?path=/Packages/com.adapty.unity-sdk#4.0.0-beta.1
```

Si vous installez via le package Unity, téléchargez `adapty-unity-plugin-4.0.0-beta.1.unitypackage` depuis la [version 4.0.0-beta.1](https://github.com/adaptyteam/AdaptySDK-Unity/releases/tag/4.0.0-beta.1).

Deux modifications de configuration s'accompagnent de la v4 — le SDK natif iOS d'Adapty est déclaré en tant que package Swift distant et ne s'installe plus via CocoaPods :

- Mettez à jour l'External Dependency Manager vers la version **1.2.188 ou ultérieure** — les versions antérieures ne prennent pas en charge les dépendances Swift Package Manager. C'est la version que le SDK 4.0 déclare comme dépendance pair, donc Unity vous avertit si votre projet en possède une plus ancienne.
- Les étapes CocoaPods ci-dessus (`iOS Resolver -> Install Cocoapods`, ouverture de `Unity-iPhone.xcworkspace`) s'appliquent uniquement au SDK 3.x. Avec le SDK 4.0, EDM ajoute automatiquement le package Swift au projet Xcode généré.
- Définissez la cible de déploiement iOS à **15.0 ou ultérieure**. Un validateur de build dans l'éditeur Unity bloque sinon le build iOS.

Consultez le [guide de migration](migration-to-unity-sdk-v4) pour la liste complète des changements du SDK 4.0.

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

Activez le SDK dans le code de votre application.

:::note
Le SDK n'a besoin d'être activé qu'une seule fois dans votre application.
:::

Pour obtenir votre **Public SDK Key** :

1. Accédez à l'Adapty Dashboard et naviguez vers [**App settings → General**](https://app.adapty.io/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](developer-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](getting-started-with-server-side-api).
- Les **SDK keys** sont propres à chaque application, donc si vous avez plusieurs applications, veillez à choisir la bonne.

```csharp showLineNumbers title="C#"
using UnityEngine;
using AdaptySDK;

public class AdaptyListener : MonoBehaviour, AdaptyEventListener {
    void Start() {
        DontDestroyOnLoad(this.gameObject);
        Adapty.SetEventListener(this);

        var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY");

        Adapty.Activate(builder.Build(), (error) => {
            if (error != null) {
                // handle the error
                return;
            }
        });
    }

    public void OnLoadLatestProfile(AdaptyProfile profile) { }
    public void OnInstallationDetailsSuccess(AdaptyInstallationDetails details) { }
    public void OnInstallationDetailsFail(AdaptyError error) { }
}
```

:::note
Dans le SDK 4.0, les interfaces de listener suivent la convention de préfixe I du C# : implémentez `IAdaptyEventListener` plutôt que `AdaptyEventListener`. Les méthodes restent inchangées. Consultez le [guide de migration](migration-to-unity-sdk-v4).
:::

:::important
Attendez le callback de complétion d'`Activate` avant d'appeler toute autre méthode du SDK Adapty. Consultez [l'ordre d'appel dans le SDK Unity](unity-sdk-call-order) pour la séquence complète.
:::

## Configurer l'écoute des événements \{#set-up-event-listening\}

Créez un script pour écouter les événements Adapty. Nommez-le `AdaptyListener` dans votre scène. Nous recommandons d'utiliser la méthode `DontDestroyOnLoad` sur cet objet pour qu'il persiste pendant toute la durée de vie de l'application.

  <img src="/assets/shared/img/2ccd564-create_adapty_listener.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

Adapty utilise le namespace `AdaptySDK`. En haut de vos fichiers de script qui utilisent le SDK Adapty, vous pouvez ajouter :

```csharp showLineNumbers title="C#"
using AdaptySDK;
```

Abonnez-vous aux événements Adapty :

```csharp showLineNumbers title="C#"
using UnityEngine;
using AdaptySDK;

public class AdaptyListener : MonoBehaviour, AdaptyEventListener {
    public void OnLoadLatestProfile(AdaptyProfile profile) {
        // handle updated profile data
    }

    public void OnInstallationDetailsSuccess(AdaptyInstallationDetails details) { }
    public void OnInstallationDetailsFail(AdaptyError error) { }
}
```

Nous recommandons d'ajuster l'ordre d'exécution des scripts pour placer l'AdaptyListener avant Default Time. Cela garantit qu'Adapty s'initialise le plus tôt possible.

  <img src="/assets/shared/img/activate_unity.webp"
  style={{
    border: 'none', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

Configurez maintenant les paywalls dans votre application :

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

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

Si vous prévoyez d'utiliser le [Paywall Builder](adapty-paywall-builder) et avez installé le module AdaptyUI, vous devez activer AdaptyUI. Vous pouvez l'activer lors de la configuration :

```csharp showLineNumbers title="C#"
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetActivateUI(true);
```

## 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 :

| Level      | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `error`    | Seules les erreurs seront journalisées                                    |
| `warn`     | Les erreurs et les messages du SDK qui ne causent pas d'erreurs critiques, mais méritent attention, seront journalisés |
| `info`     | Les erreurs, avertissements et divers messages d'information seront journalisés |
| `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 |

Vous pouvez définir le niveau de log dans votre application lors de la configuration d'Adapty :

```csharp showLineNumbers title="C#"
// 'verbose' is recommended for development and the first production release
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY");
builder.LogLevel = AdaptyLogLevel.Verbose;
```

Vous pouvez également modifier le niveau de log à l'exécution :

```csharp showLineNumbers title="C#"
Adapty.SetLogLevel(AdaptyLogLevel.Verbose, (error) => {
    // handle result
});
```

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

Adapty ne stocke pas les données personnelles de vos utilisateurs sauf si vous les envoyez explicitement, mais vous pouvez mettre en place des politiques de sécurité des données supplémentaires pour vous conformer aux directives du store ou des pays.

#### Désactiver la collecte et le partage des adresses IP \{#disable-ip-address-collection-and-sharing\}

Lors de l'activation du module Adapty, définissez `SetIPAddressCollectionDisabled` 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'adresse IP ne sont pas nécessaires pour votre application.

```csharp showLineNumbers title="C#"
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetIPAddressCollectionDisabled(true);
```

#### 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 `SetAppleIDFACollectionDisabled` et/ou `SetGoogleAdvertisingIdCollectionDisabled` à `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/Google Play, éviter de déclencher l'invite App Tracking Transparency, ou si votre application n'a pas besoin d'attribution publicitaire ni d'analytiques basées sur les identifiants publicitaires.

```csharp showLineNumbers title="C#"
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAppleIDFACollectionDisabled(true)
    .SetGoogleAdvertisingIdCollectionDisabled(true);
```

#### 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 la consommation réseau. Vous pouvez personnaliser ces paramètres en fournissant une configuration personnalisée.

Utilisez `SetAdaptyUIMediaCache` pour remplacer les paramètres de cache par défaut :

```csharp showLineNumbers title="C#"
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAdaptyUIMediaCache(
        100 * 1024 * 1024, // MemoryStorageTotalCostLimit 100MB
        null, // MemoryStorageCountLimit
        100 * 1024 * 1024 // DiskStorageSizeLimit 100MB
    );
```

Paramètres :

| Paramètre                   | Requis   | Description                                                                                   |
|-----------------------------|----------|-----------------------------------------------------------------------------------------------|
| memoryStorageTotalCostLimit | optionnel | Taille totale du cache en mémoire en octets. Valeur par défaut spécifique à la plateforme.   |
| memoryStorageCountLimit     | optionnel | Nombre maximal d'éléments dans le stockage en mémoire. Valeur par défaut spécifique à la plateforme. |
| diskStorageSizeLimit        | optionnel | Taille limite des fichiers sur disque en octets. Valeur par défaut spécifique à la plateforme. |

### 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 activés sur iOS et désactivés sur Android. Pour les activer également sur Android, définissez `SetGoogleLocalAccessLevelAllowed` sur `true` :

```csharp showLineNumbers title="C#"
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetGoogleLocalAccessLevelAllowed(true);
```

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

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

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

```csharp showLineNumbers title="C#"
var builder = new AdaptyConfiguration.Builder("YOUR_PUBLIC_SDK_KEY")
    .SetAppleClearDataOnBackup(true);
```

## 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 Unity, appliquez ces modifications à `Assets/Plugins/Android/AndroidManifest.xml` et créez les fichiers de règles de sauvegarde dans `Assets/Plugins/Android/res/xml/`.
:::

#### Les achats échouent après un retour depuis une autre application sur Android \{#purchases-fail-after-returning-from-another-app-in-android\}

Si l'Activity qui démarre le flow d'achat utilise un `launchMode` non standard, Android peut la recréer ou la réutiliser incorrectement lorsque l'utilisateur revient depuis Google Play, une application bancaire ou un navigateur. Cela peut entraîner la perte du résultat d'achat ou son interprétation comme une annulation.

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

Dans votre `AndroidManifest.xml`, assurez-vous que l'Activity qui démarre le flow d'achat est configurée sur `standard` ou `singleTop` :

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

#### L'application plante lors de l'affichage d'un paywall sur Android \{#app-crashes-when-a-paywall-is-displayed-on-android\}

Si votre application plante sur Android lors de l'affichage d'un paywall, il est possible que le plugin Kotlin soit absent de votre configuration Gradle. Pour l'ajouter :

1. Dans **Player Settings**, assurez-vous que les options **Custom Launcher Gradle Template** et **Custom Base Gradle Template** sont sélectionnées.
   
   <img src="/assets/shared/img/kotlin-plugin1.webp"
   style={{
   border: 'none', /* border width and color */
   width: '700px', /* image width */
   display: 'block', /* for alignment */
   margin: '0 auto' /* center alignment */
   }}
   />
   

2. Ajoutez la ligne suivante à `/Assets/Plugins/Android/launcherTemplate.gradle` :

```groovy showLineNumbers
   apply plugin: 'com.android.application'
   // highlight-next-line
   apply plugin: 'kotlin-android'
   apply from: 'setupSymbols.gradle'
   apply from: '../shared/keepUnitySymbols.gradle'
   ```

3. Ajoutez la ligne suivante dans `/Assets/Plugins/Android/baseProjectTemplate.gradle` :

   ```groovy showLineNumbers
   plugins {
       // If you are changing the Android Gradle Plugin version, make sure it is compatible with the Gradle version preinstalled with Unity
       // See which Gradle version is preinstalled with Unity here https://docs.unity3d.com/Manual/android-gradle-overview.html
       // See official Gradle and Android Gradle Plugin compatibility table here https://developer.android.com/studio/releases/gradle-plugin#updating-gradle
       // To specify a custom Gradle version in Unity, go do "Preferences > External Tools", uncheck "Gradle Installed with Unity (recommended)" and specify a path to a custom Gradle version
       id 'com.android.application' version '8.3.0' apply false
       id 'com.android.library' version '8.3.0' apply false
   // highlight-next-line
       id 'org.jetbrains.kotlin.android' version '1.8.0' apply false
       **BUILD_SCRIPT_DEPS**
   }
   ```