Configurer un projet Android Studio

AVIS : La version 2.0.0 et les versions ultérieures du SDK Places pour Android dépendent d' AndroidX. À partir de cette version, l'ancienne bibliothèque d'assistance ne sera plus compatible. Pour conserver la compatibilité, vous devez migrer vos projets afin d'utiliser AndroidX.

Pour configurer votre application afin qu'elle utilise le SDK Places pour Android, procédez comme suit. Ces étapes sont obligatoires pour toutes les applications qui utilisent le SDK Places pour Android.

Étape 1 : Configurez Android Studio

Ce document décrit un environnement de développement utilisant Android Studio Hedgehog et la version 8.2 du plug-in Android Gradle.

Remarque : Si votre environnement de développement utilise une autre version d'Android Studio ou de Gradle, vous devrez peut-être modifier les étapes en fonction de ces versions. Pour plus d'informations sur les versions d'Android Studio et de Gradle, consultez Compatibilité entre le plug-in Android Gradle et Android Studio.

Étape 2 : Configurez le SDK

La bibliothèque du SDK Places pour Android est disponible via le dépôt Maven de Google. Pour ajouter le SDK à votre application, procédez comme suit :

1. Dans votre fichier settings.gradle.kts de premier niveau, incluez le portail de plug-ins Gradle, le dépôt Maven de Google, et le dépôt central Maven sous le bloc pluginManagement. Dans le script, le bloc pluginManagement doit apparaître avant toute autre instruction.

   pluginManagement {
       repositories {
           google()
           mavenCentral()
           gradlePluginPortal()
       }
   } 

2. Dans votre fichier settings.gradle.kts de premier niveau, incluez le dépôt Maven de Google et le répertoire central Maven sous le bloc dependencyResolutionManagement :

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. Dans la section dependencies de votre fichier module au niveau build.gradle.kts, ajoutez une dépendance au SDK Places pour Android :

   Remarque : Le SDK Places pour Android version 3.5.0 nécessite kotlin-bom 1.8.0 ou version ultérieure. Pour en savoir plus sur la dépendance kotlin-bom, consultez Utilisation de la dernière version de kotlin-stdlib dans les dépendances transitives.

   Groovy

   dependencies {
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:$kotlin_version"))
       implementation("com.google.android.libraries.places:places:3.5.0")
   }

   Kotlin

             dependencies {
   
       // Places and Maps SDKs
       implementation("com.google.android.libraries.places:places:6.0.2")
   }

4. Dans votre fichier build.gradle.kts au niveau du module, définissez compileSdk et minSdk sur les valeurs suivantes :
   Remarque : Vérifiez que compileSdk est défini sur 34 ou plus, et que minSdk est défini sur 23 ou plus.

   Groovy

   android {
       compileSdk 34
   
       defaultConfig {
           minSdk 23
           // ...
       }
   }

   Kotlin

   android {
       compileSdk = 34
   
       defaultConfig {
           minSdk = 23
           // ...
       }
   }

5. Dans la section buildFeatures de votre fichier build.gradle au niveau du module, ajoutez la classe BuildConfig, qui vous permettra d’accéder aux valeurs de métadonnées définies ultérieurement dans cette procédure :

   Groovy

   android {
     // ...
     buildFeatures {
       buildConfig true
       // ...
     }
   }

   Kotlin

   android {
     // ...
     buildFeatures {
       buildConfig = true
       // ...
     }
   }

Étape 3 : Ajoutez votre clé API au projet

Cette section explique comment stocker votre clé API pour qu'elle puisse être référencée de manière sécurisée par votre application. Vous ne devez pas enregistrer votre clé API dans votre système de contrôle des versions. Nous vous recommandons donc de la stocker dans un fichier secrets.properties dans le répertoire racine de votre projet et d'exclure ce fichier du contrôle des versions. Pour en savoir plus sur les fichiers de propriétés Gradle, consultez Fichiers de propriétés Gradle.

Pour vous faciliter la tâche, nous vous recommandons d'utiliser le plug-in Secrets Gradle pour Android.

Pour installer le plug-in Secrets Gradle pour Android et stocker votre clé API :

1. Dans Android Studio, ouvrez votre fichier build.gradle.kts ou build.gradle de premier niveau et ajoutez le code suivant au bloc plugins.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
   }

2. Ouvrez votre fichier build.gradle.kts ou build.gradle au niveau du module et ajoutez le code suivant à l'élément plugins.

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       id 'com.android.application'
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. Si vous utilisez Android Studio, synchronisez votre projet avec Gradle.
4. Ouvrez le fichier secrets.properties dans votre répertoire de premier niveau, et ajoutez le code suivant. Remplacez YOUR_API_KEY par votre clé API. Veillez à ajouter secrets.properties à votre .gitignore fichier (ou à l'exclure de votre système de contrôle des versions) afin de ne pas enregistrer votre clé API dans le contrôle des versions.
   Remarque : Si le fichier secrets.properties n'existe pas, créez-le dans le même dossier que le fichier local.properties.

   PLACES_API_KEY=YOUR_API_KEY

5. Créez le fichier local.defaults.properties dans votre répertoire de premier niveau (même dossier que le fichier secrets.properties), puis ajoutez le code suivant.

   Remarque : Saisissez le code tel qu'il est indiqué. Ne remplacez pas DEFAULT_API_KEY par votre clé API.

   PLACES_API_KEY=DEFAULT_API_KEY

   Ce fichier a pour but de fournir un emplacement de sauvegarde de la clé API à utiliser si le fichier secrets.properties est introuvable pour éviter l'échec des créations. Cette situation peut se produire si vous clonez l'application à partir d'un système de contrôle des versions qui omet secrets.properties et que vous n'avez pas encore créé de fichier secrets.properties localement pour fournir votre clé API.

6. Dans Android Studio, ouvrez votre fichier build.gradle.kts ou build.gradle au niveau du module et modifiez la propriété secrets. Si la propriété secrets n'existe pas, ajoutez-la.

   Modifiez les propriétés du plug-in pour définir propertiesFileName sur "secrets.properties", définir defaultPropertiesFileName sur "local.defaults.properties" et toutes les autres propriétés.

   Kotlin

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }

   Groovy

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }

Étape 4 : Initialisez le client de l'API Places

Pour initialiser le SDK Places pour Android dans une activité ou un fragment, transmettez la clé API lorsque vous appelez Places.initializeWithNewPlacesApiEnabled() :

Kotlin

    // Define a variable to hold the Places API key.
    val apiKey = BuildConfig.PLACES_API_KEY

    // Log an error if apiKey is not set.
    if (apiKey.isEmpty() || apiKey == "DEFAULT_API_KEY") {
        Log.e("Places test", "No api key")
        finish()
        return
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(applicationContext, apiKey)

    // Create a new PlacesClient instance
    val placesClient = Places.createClient(this)
    

Java

    // Define a variable to hold the Places API key.
    String apiKey = BuildConfig.PLACES_API_KEY;

    // Log an error if apiKey is not set.
    if (TextUtils.isEmpty(apiKey) || apiKey.equals("DEFAULT_API_KEY")) {
      Log.e("Places test", "No api key");
      finish();
      return;
    }

    // Initialize the SDK
    Places.initializeWithNewPlacesApiEnabled(getApplicationContext(), apiKey);

    // Create a new PlacesClient instance
    PlacesClient placesClient = Places.createClient(this);
    

IMPORTANT : N'ajoutez jamais de clés API directement au code de l'application. Dans les environnements de production, nous vous recommandons d'utiliser un mécanisme sécurisé pour gérer les clés API.

Vous êtes maintenant prêt à commencer à utiliser le SDK Places pour Android.

Étape 5 : Configurez un appareil Android

Pour exécuter une application qui utilise le SDK Places pour Android, vous devez la déployer sur un appareil Android ou sur un Android Emulator qui exécute Android 6.0 (ou une version ultérieure) et inclut les Google APIs.

• Pour utiliser un appareil Android, suivez les instructions fournies dans Exécuter des applications sur un appareil matériel.
• Pour utiliser un Android Emulator, vous pouvez créer un appareil virtuel et installer l'émulateur à l'aide du Gestionnaire d'appareils fourni avec Android Studio.
  Remarque : Si vous choisissez d'utiliser un émulateur Android, assurez-vous de sélectionner un profil d'appareil signalé par l'icône Play dans la colonne Play Store. L'icône indique que ces profils sont entièrement CTS et qu'ils peuvent utiliser des images système incluant l'application Play Store.

Étapes suivantes

Une fois votre projet configuré, vous pouvez explorer les exemples d'applications.