Configurer un projet Android Studio

Cette page explique comment configurer un projet Android Studio afin d'utiliser le SDK Maps pour Android sans avoir recours au modèle Google Maps détaillé dans le guide de démarrage rapide.

Le modèle Google Maps configure et ajoute automatiquement une carte de base à un nouveau projet Android Studio. Toutefois, vous pouvez également ajouter une carte à un projet Android qui utilise un autre modèle Android Studio. Pour ce faire, vous devez configurer manuellement votre projet, puis ajouter la carte.

É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 Maps pour Android est disponible via le dépôt Maven de Google. Pour ajouter le SDK à votre application, procédez comme suit :

1. Dans le fichier settings.gradle 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 {
           gradlePluginPortal()
           google()
           mavenCentral()
       }
   } 

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

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

3. Dans le fichier build.gradle au niveau du module, ajoutez la dépendance des services Google Play pour le SDK Maps pour Android.

   Groovy

   dependencies {
   
       // Maps SDK for Android
       implementation 'com.google.android.gms:play-services-maps:18.2.0'
   }

   Kotlin

   dependencies {
   
       // Maps SDK for Android
       implementation("com.google.android.gms:play-services-maps:18.2.0")
   }

4. Dans le fichier build.gradle 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 minSdk sur 19 ou plus.

   Groovy

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

   Kotlin

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

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 le fichier secrets.properties, qui se trouve dans le répertoire racine de votre projet. Pour en savoir plus sur le fichier secrets.properties, 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.

Remarque : Consultez la documentation du plug-in Secrets Gradle pour Android sur GitHub pour connaître la configuration système requise et lire les instructions d'installation.

Pour installer le plug-in Secrets Gradle pour Android dans votre projet Google Maps :

1. Dans Android Studio, ouvrez votre fichier build.gradle ou build.gradle.kts de premier niveau et ajoutez le code suivant à l'élément dependencies sous buildscript.

   Groovy

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }
   

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

   Groovy

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

   Kotlin

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

3. Dans le fichier build.gradle au niveau du module, assurez-vous que targetSdk et compileSdk sont définis sur 34.
4. Enregistrez le fichier et synchronisez votre projet avec Gradle.
5. 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. Stockez votre clé dans ce fichier, car secrets.properties n'est pas vérifié dans un système de 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.

   MAPS_API_KEY=YOUR_API_KEY

6. Enregistrez le fichier.

7. 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 comme indiqué. Ne remplacez pas DEFAULT_API_KEY par votre clé API.

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

8. Enregistrez le fichier.
9. Dans votre fichier AndroidManifest.xml, accédez à com.google.android.geo.API_KEY, puis modifiez le android:value attribute. Si le tag <meta-data> n'existe pas, créez-le comme enfant du tag <application>.

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

Étape 4 : Mettez à jour le fichier manifeste de l'application

Cette section décrit les paramètres à ajouter à votre fichier AndroidManifest.xml.

Numéro de version des services Google Play

Ajoutez la déclaration suivante à l'élément application pour intégrer la version des services Google Play avec laquelle l'application a été compilée.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Autorisation d'accéder à la position

Si votre application a besoin de géolocaliser l'utilisateur, vous devez demander l'autorisation d'accéder à sa position dans votre fichier AndroidManifest.xml. Les options sont ACCESS_FINE_LOCATION (indique la position exacte de l'appareil) et ACCESS_COARSE_LOCATION (indique une position moins précise). Pour plus d'informations, consultez le guide sur les données de localisation.

Remarque : Dans le guide de démarrage rapide, ACCESS_FINE_LOCATION est activé.

Pour demander l'autorisation ACCESS_FINE_LOCATION, ajoutez ce code à l'élément manifest :

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Autorisation de stockage externe

Si vous envisagez d'utiliser la version 8.3 ou ultérieure du SDK des services Google Play, vous n'avez pas besoin de l'autorisation WRITE_EXTERNAL_STORAGE. Si vous ciblez des versions antérieures du SDK des services Google Play, vous devez demander l'autorisation WRITE_EXTERNAL_STORAGE dans l'élément manifest.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Bibliothèque Apache HTTP Legacy

Si vous utilisez com.google.android.gms:play-services-maps:16.0.0 ou une version antérieure et que votre application cible le niveau d'API 28 (Android 9.0) ou supérieur, vous devez inclure la déclaration suivante dans l'élément <application> de AndroidManifest.xml. Sinon, ignorez cette déclaration.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

Étape 5 : Configurez un appareil Android

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

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

  

Étape 6 : Vérifiez la prise en charge des services Play (facultatif)

Pour utiliser le SDK Maps pour Android, les services Google Play doivent être installés sur l'appareil sur lequel vous déployez votre application. Pour vérifier leur présence, Google fournit une méthode que vous pouvez appeler depuis votre application. Pour en savoir plus, consultez Vérifier si les services Google Play sont installés.

Étapes suivantes

Une fois votre projet configuré, vous pouvez ajouter une carte.