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 pour Android Studio. Si vous souhaitez configurer un projet Android Studio existant, consultez Configuration d'un projet existant.

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

Configurer l'environnement de développement

  1. Android Studio est nécessaire. Si vous ne l'avez pas encore fait, téléchargez-le et installez-le.

  2. Ajoutez le SDK des services Google Play à Android Studio. Le SDK Maps pour Android est intégré au SDK des services Google Play, que vous pouvez ajouter via SDK Manager.

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

Créer un projet Google Maps

  1. Ouvrez Android Studio, puis cliquez sur Create New Project (Créer un 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 Google Maps Activity (Activité Google Maps), puis cliquez sur Next (Suivant).

  3. Remplissez le formulaire Google Maps Activity (Activité Google Maps) :

    • 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 avec Kotlin.

    • Définissez le Minimum SDK (SDK minimal) sur une version du SDK Android compatible avec votre appareil de test.

  4. Cliquez sur Finish (Terminer).

Lorsque vous aurez terminé de créer le projet, Android Studio démarrera Gradle et compilera le projet. Cette opération pourra prendre un certain temps. Une fois le projet compilé, Android Studio ouvrira les fichiers google_maps_api.xml et MapsActivity. Votre activité peut avoir un nom différent, à savoir celui que vous avez défini durant la configuration.

Pour savoir comment créer un projet, consultez Créer un projet Android.

Le fichier google_maps_api.xml contient des instructions pour obtenir une clé API Google Maps et l'ajouter au fichier. N'ajoutez pas votre clé API au fichier, car elle serait alors moins sécurisée. À la place, suivez les instructions fournies dans la section suivante.

Configurer dans Cloud Console

Suivez les étapes de configuration de Cloud Console requises en cliquant sur les onglets suivants :

Étape 1

Console

  1. Dans Google Cloud Console, sur la page de sélection du 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

    Google Cloud propose un essai gratuit de 300 $, et Google Maps Platform un crédit mensuel récurrent de 200 $. Pour en savoir plus, consultez Crédits de compte de facturation et Facturation.

SDK Cloud

gcloud projects create "PROJECT"

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

É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

SDK Cloud

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

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

É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 est répertoriée sur la page Identifiants sous Clés API.
    (N'oubliez pas de restreindre la clé API avant de l'utiliser en production.)

SDK Cloud

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

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

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 plus 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 local.properties, qui se trouve dans le répertoire racine de votre projet. Pour en savoir plus sur le fichier local.properties, consultez Fichiers de propriétés Gradle.

Pour vous faciliter la tâche, vous pouvez utiliser le plug-in Secrets Gradle pour Android.

Pour installer le plug-in et stocker votre clé API :

  1. Dans Android Studio, ouvrez votre fichier build.gradle au niveau racine et ajoutez le code suivant à l'élément dependencies sous buildscript.
    buildscript {
        dependencies {
            // ...
            classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.0"
        }
    }
        
  2. Ensuite, ouvrez le fichier build.gradle au niveau de l'application et ajoutez le code suivant à l'élément plugins.
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
        
  3. Enregistrez le fichier et synchronisez votre projet avec Gradle.
  4. Ouvrez local.properties dans votre répertoire au niveau du projet, puis ajoutez le code suivant. Remplacez YOUR_API_KEY par votre clé API.
    MAPS_API_KEY=YOUR_API_KEY
        
  5. Enregistrez le fichier et synchronisez votre projet avec Gradle.
  6. Dans votre fichier AndroidManifest.xml, accédez à com.google.android.geo.API_KEY et mettez à jour le android:value attribute comme suit :
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
        

Remarque : Comme indiqué ci-dessus, 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 Google Maps 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 renvoie une exception.

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é Google 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.

Le fichier d'activité Google Maps contient le code suivant :

Java

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;

import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney and move the camera
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions()
                .position(sydney)
                .title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

      

Kotlin

// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package com.google.maps.example.kotlin

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions
import com.google.maps.example.R

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // Add a marker in Sydney and move the camera
        val sydney = LatLng(-34.0, 151.0)
        mMap.addMarker(MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"))
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}
      

Fichier Gradle au niveau de l'application

Le fichier build.gradle au niveau de l'application inclut la dépendance Maps suivante, qui est nécessaire au SDK Maps pour Android.

dependencies {
    implementation 'com.google.android.gms:play-services-maps:17.0.1'
    // ...
}

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:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

Déployer et exécuter l'application

Capture d&#39;écran avec la carte et le repère centrés sur Sydney, en Australie

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