Guide de démarrage rapide avec le SDK Maps pour Android

Créez une application Android qui affiche une carte en utilisant le modèle Google Maps Views pour Android Studio. Si vous souhaitez configurer un projet Android Studio existant, consultez Configurer un projet Android Studio.

Ce guide de démarrage rapide est destiné aux développeurs qui connaissent déjà les bases du développement Android avec Kotlin ou Java.

À propos de l'environnement de développement

Ce guide de démarrage rapide a été développé en utilisant Android Studio Hedgehog 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 votre environnement. Pour plus d'informations sur les versions d'Android Studio et de Gradle, consultez Compatibilité entre le plug-in Android Gradle et Android Studio.

Configurer 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 5.0 (ou une version ultérieure) et inclut les API Google.

• Pour utiliser un appareil Android, suivez les instructions 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 :

  

Créer un projet Google Maps dans Android Studio

La procédure à suivre pour créer un projet Google Maps dans Android Studio a été modifiée dans les versions Flamingo et ultérieures d'Android Studio.

1. Ouvrez Android Studio, puis cliquez sur New Project (Nouveau projet) dans la fenêtre Welcome to Android Studio (Bienvenue dans Android Studio).

2. Dans la fenêtre New project (Nouveau projet), dans la catégorie Phone and Tablet (Téléphone et tablette), sélectionnez No Activity (Aucune activité), puis cliquez sur Next (Suivant).

3. Remplissez le formulaire New Project (Nouveau projet) :

   • Définissez le paramètre Language (Langage) sur Java ou Kotlin. Les deux langages sont entièrement compatibles avec le SDK Maps pour Android. Pour en savoir plus sur Kotlin, consultez Développer des applications Android en Kotlin.

   • Définissez le Minimum SDK (SDK minimal) sur une version du SDK compatible avec votre appareil de test. Vous devez sélectionner une version supérieure à la version minimale requise par le SDK Maps pour Android version 19.0.x, qui est au niveau d'API Android 21 ("Lollipop", Android 5.0) ou une version ultérieure. Pour obtenir les dernières informations sur les versions requises du SDK, consultez les notes de version.

     Remarque : Si vous ne savez pas quelle version du SDK choisir, cliquez sur le lien Help me choose (Aidez-moi à choisir) pour afficher les informations de distribution liées aux SDK Android compatibles. Par exemple, si vous choisissez le niveau d'API Android 21 ("Lollipop", Android 5.0), votre application doit s'exécuter sur plus de 99% des appareils Android.

   • Définissez Build configuration language (Langage de configuration de compilation) sur le DSL Kotlin ou Groovy. Les extraits correspondant à ces deux langages de configuration de compilation sont indiqués dans les procédures ci-dessous.

4. Cliquez sur Finish (Terminer).

   Android Studio démarre Gradle et crée le projet. Cela peut prendre un certain temps.

5. Ajoutez l'activité Google Maps Views :

   1. Effectuez un clic droit sur le dossier app dans votre projet.

   2. Sélectionnez New > Google > Google Maps Views Activity (Nouveau > Google > Activité Google Maps Views).

      

   3. Dans la boîte de dialogue New Android Activity (Nouvelle activité Android), cochez la case Launcher Activity (Activité du lanceur).

   4. Sélectionnez Finish (Terminer).

      Pour en savoir plus, consultez Ajouter du code à partir d'un modèle.

6. Une fois le projet compilé, Android Studio ouvre les fichiers AndroidManifest.xml et MapsActivity. Votre activité peut avoir un nom différent, à savoir celui que vous avez défini durant la configuration.

   Attention : Le fichier AndroidManifest.xml contient des instructions pour obtenir une clé API Google Maps et l'ajouter à votre fichier local.properties. N'ajoutez pas votre clé API au fichier local.properties, car elle serait alors moins sécurisée. Suivez plutôt les instructions de la section Configurer votre projet Google Cloud pour créer un projet Cloud, puis configurer une clé API.

Configurer votre projet Google Cloud

Suivez les étapes de configuration requises dans la console Cloud en cliquant sur les onglets suivants :

Étape 1

Console

1. Dans la console Google Cloud, sur la page du sélecteur de projet, cliquez sur Créer un projet pour créer un projet Cloud.

   Accéder à la page du sélecteur de projet

2. Assurez-vous que la facturation est activée pour votre projet Cloud. Vérifier si la facturation est activée sur un projet

   Vous pouvez tester Google Cloud sans frais. La période d'essai expire au bout de 90 jours ou après que le compte a enregistré 300 $ de frais (selon la première échéance atteinte). Vous pouvez résilier à tout moment. Google Maps Platform propose un crédit mensuel récurrent de 200 $. Pour en savoir plus, consultez Crédits de compte de facturation et Facturation.

Cloud SDK

gcloud projects create "PROJECT"

En savoir plus sur le Google Cloud SDK, l'installation du Cloud SDK et les commandes suivantes :

• gcloud projects create

Remarque : Si vous ne comptez pas conserver les ressources générées au cours de cet exercice d'apprentissage, créez un projet au lieu de sélectionner un projet existant. Une fois l'exercice terminé, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

Étape 2

Pour utiliser Google Maps Platform, vous devez activer les API ou les SDK que vous prévoyez d'utiliser avec votre projet.

Console

Activer le SDK Maps pour Android

Cloud SDK

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

En savoir plus sur le Google Cloud SDK, l'installation du Cloud SDK et les commandes suivantes :

• gcloud services enable
• gcloud services disable

Étape 3

Cette étape concerne uniquement le processus de création de la clé API. Si vous utilisez votre clé API en production, nous vous recommandons vivement de la restreindre. Vous trouverez plus d'informations sur la page Utiliser des clés API spécifique au produit.

Une clé API est un identifiant unique qui permet d'authentifier les requêtes associées à votre projet à des fins d'utilisation et de facturation. Vous devez associer au moins une clé API à votre projet.

Pour créer une clé API :

Console

1. Accédez à la page Google Maps Platform > Identifiants.

   Accéder à la page "Identifiants"

2. Sur la page Identifiants, cliquez sur Créer des identifiants > Clé API.
   La boîte de dialogue Clé API créée affiche la clé API que vous venez de créer.
3. Cliquez sur Fermer.
   La nouvelle clé API figure sur la page Identifiants sous Clés API.
   (N'oubliez pas de restreindre la clé API avant de l'utiliser en production.)

Cloud SDK

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

En savoir plus sur le Google Cloud SDK, l'installation du Cloud SDK et les commandes suivantes :

• gcloud alpha services api-keys create

Ajouter la clé API à votre application

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.kts ou build.gradle de premier niveau et ajoutez le code suivant à l'élément dependencies sous buildscript.

   Kotlin

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

   Groovy

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

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

   Kotlin

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

   Groovy

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

3. Dans votre fichier build.gradle.kts ou 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}" />

   Remarque:com.google.android.geo.API_KEY est le nom de métadonnées recommandé pour la clé API. Une clé portant ce nom peut être utilisée pour l'authentification auprès de diverses API basées sur Google Maps et s'exécutant sur la plate-forme Android, y compris le SDK Maps pour Android. Pour assurer la rétrocompatibilité, l'API accepte également le nom com.google.android.maps.v2.API_KEY. Cet ancien nom autorise l'authentification auprès de l'API Google Maps Android v2 uniquement. Une application ne peut spécifier qu'un seul des noms de métadonnées de clé API. Si les deux noms sont spécifiés, l'API génère une exception.

10. Dans Android Studio, ouvrez votre fichier build.gradle.kts ou build.gradle au niveau du module, puis 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, defaultPropertiesFileName sur local.defaults.properties et d'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 same folder as the 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"
    
        // 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.*"
    }
            

    Groovy

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the 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"
    
        // 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.*"
    }
            

Examiner le code

Examinez le code fourni par le modèle. Observez plus particulièrement les fichiers suivants dans votre projet Android Studio.

Fichier d'activité Maps

Le fichier d'activité Google Maps correspond à l'activité principale de l'application. Il contient le code permettant de gérer et d'afficher la carte. Par défaut, le fichier qui définit l'activité est nommé MapsActivity.java, ou MapsActivity.kt si vous sélectionnez Kotlin comme langage pour votre application.

Principaux éléments de l'activité Google Maps :

• L'objet SupportMapFragment gère le cycle de vie de la carte et constitue l'élément parent de l'UI de l'application.

• L'objet GoogleMap permet d'accéder aux données et à la vue de la carte. Il s'agit de la classe principale du SDK Maps pour Android. Le guide Objets de carte décrit plus en détail les objets SupportMapFragment et GoogleMap.

• La fonction moveCamera centre la carte aux coordonnées LatLng de Sydney, en Australie. Les premiers paramètres à configurer pour ajouter une carte sont généralement la position de la carte et la caméra (par exemple, l'angle de vue, l'orientation de la carte et le niveau de zoom). Pour plus d'informations, consultez le guide Caméra et vue.

• La fonction addMarker ajoute un repère aux coordonnées de Sydney. Consultez le guide Repères pour en savoir plus.

Fichier Gradle du module

Le fichier build.gradle.kts du module inclut la dépendance Maps suivante, qui est nécessaire au SDK Maps pour Android.

dependencies {

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

Remarque :La version exacte peut changer en fonction de la version actuelle du SDK Maps pour Android.

Pour en savoir plus sur la gestion des dépendances Maps, consultez Gestion des versions.

Fichier de mise en page XML

Le fichier activity_maps.xml est le fichier de mise en page XML qui définit la structure de l'UI de l'application. Il se trouve dans le répertoire res/layout. Le fichier activity_maps.xml déclare un fragment qui inclut les éléments suivants :

• tools:context définit l'activité par défaut du fragment sur MapsActivity, spécifié dans le fichier d'activité Google Maps.
• android:name définit le nom de classe du fragment sur SupportMapFragment, qui est le type de fragment utilisé dans le fichier d'activité Google Maps.

Le fichier de mise en page XML contient le code suivant :

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

Déployer et exécuter l'application

Une fois l'application exécutée correctement, elle affiche une carte centrée sur Sydney, en Australie, avec un repère sur la ville tel qu'illustré dans la capture d'écran suivante.

Pour déployer et exécuter l'application :

1. Dans Android Studio, cliquez sur l'option de menu Run (Exécuter) ou sur l'icône du bouton de lecture pour exécuter l'application.
2. Lorsque vous êtes invité à choisir un appareil, sélectionnez l'une des options suivantes :
   • Sélectionnez l'appareil Android qui est connecté à votre ordinateur.
   • Vous pouvez également sélectionner la case d'option Launch emulator (Lancer l'émulateur) et choisir l'appareil virtuel que vous avez configuré.
3. Cliquez sur OK. Android Studio démarrera Gradle pour compiler votre application, puis affichera les résultats sur votre appareil ou votre émulateur. Le lancement de l'application peut prendre plusieurs minutes.

Étapes suivantes

• Configurer une carte : ce document explique comment configurer les paramètres initiaux et d'exécution de votre carte, comme la position de la caméra, le type de carte, les composants d'UI et les gestes.

• Ajouter une carte à votre application Android (Kotlin) : cet atelier de programmation vous propose de créer une application qui présente certaines fonctionnalités supplémentaires du SDK Maps pour Android.

• Utiliser la bibliothèque Maps Android KTX : cette bibliothèque d'extensions Kotlin (KTX) vous permet de bénéficier de plusieurs fonctionnalités en langage Kotlin, tout en utilisant le SDK Maps pour Android.