Google Maps Mobile SDK for Work antérieur : Android

Pour les clients disposant d'une licence antérieure de Google Maps APIs for Workou de Google Maps API for Business, Google Maps Android APIest inclus avec Google Maps Mobile SDK for Work. Cette section de la documentation décrit la configuration de ce SDK.

Cette page concerne uniquement les clients qui possèdent une ancienne licence Maps APIs for Work ou Maps API for Business. Cette page ne s'applique pas aux clients qui disposent du nouveau Google Maps APIs Premium Plan, sorti en janvier 2016.

Présentation

Suivez les instructions sur cette page pour télécharger le SDK, configurer votre projet et ajouter une carte. Voici un résumé des étapes requises :

  1. Téléchargez le SDK.
  2. Ajoutez le SDK à un projet Android nouveau ou existant.
  3. Ajoutez votre clé d'API dans le fichier manifeste de l'application.
  4. Spécifiez les autorisations Android requises et la version 2 d'OpenGL ES.
  5. Ajoutez une carte.

Télécharger le SDK

Vous pouvez télécharger le SDK en tant que bibliothèque statique ou utiliser Android SDK Manager.

Option 1 : Télécharger le SDK en tant que bibliothèque statique

Téléchargez la dernière version en tant que bibliothèque statique.

Option 2 : Télécharger le SDK en utilisant Android SDK Manager

Dans Android Studio :

  1. Sélectionnez Tools > Android > SDK Manager.
  2. Sélectionnez Appearance & Behavior > System Settings > Android SDK.
  3. Cliquez sur l'onglet SDK Update Sites.
  4. Cliquez sur l'icône plus (+) pour ajouter un nouveau site.
  5. Saisissez un nom, par ex. « Google Maps APIs » et l'URL : https://dl.google.com/geosdk/android-m4b-addon.xml
  6. Cliquez sur OK.
  7. Cliquez sur l'onglet SDK Tools.
  8. Sélectionnez Google Maps Mobile SDK for Work et cliquez sur OK pour terminer le téléchargement.

Android Studio installe la bibliothèque dans le répertoire <android-sdk-folder>/extras/google/maps_for_business_sdk/.

Reportez-vous au guide sur Android SDK Manager pour obtenir des instructions sur l'utilisation d'Android SDK Manager en tant qu'outil autonome.

Ajouter le SDK à votre projet

Les instructions pour Android Studio sont fournies ci-dessous. Si vous utilisez un autre outil, reportez-vous aux instructions de la documentation Android pour savoir comment utiliser la ligne de commande.

Google Maps Android API pour Google Maps Mobile SDK for Work est disponible sous deux formats : un groupe aar (google-maps-sdk-m4b.aar) et un module de bibliothèque (google-maps-sdk-m4b_lib). Vous pouvez choisir le format qui vous convient le mieux.

Option 1 : Importer le SDK depuis le groupe aar

Suivez les étapes suivantes pour inclure le groupe aar (google-maps-sdk-m4b.aar) dans votre projet Android Studio :

  1. Accédez à Google Maps Mobile SDK for Work à l'emplacement suivant :

    <android-sdk>/extras/google/maps_for_business_sdk

  2. Copiez le fichier google-maps-sdk-m4b.aar dans le répertoire libs de votre projet. (Créez le répertoire s'il n'existe pas.)

  3. Ajoutez le code suivant dans votre fichier build.gradle :

    dependencies {
        compile(name:'google-maps-sdk-m4b', ext:'aar')
    
    }
    
    repositories {
        flatDir{
            dirs 'libs'
        }
    }
    
  4. Terminez la configuration comme décrit ci-dessous.

Option 2: Importer le SDK en tant que module de bibliothèque

Au lieu d'utiliser le fichier aar, vous pouvez suivre ces étapes pour ajouter le module de bibliothèque du SDK (google-maps-sdk-m4b_lib) à un projet existant dans Android Studio :

  1. Dans Android Studio, choisissez l'option permettant d'importer un nouveau module (File -> New -> Import Module).
  2. Accédez au SDK à l'emplacement suivant :

    <android-sdk>/extras/google/maps_for_business_sdk

  3. Sélectionnez le répertoire google-maps-sdk-m4b_lib et cliquez sur Choose.

  4. Acceptez les valeurs par défaut dans l'assistant d'importation.
  5. Cliquez sur Finish. Un texte s'affichera pour résumer les résultats du processus d'importation.
  6. Assurez-vous que la bibliothèque est incluse dans le fichier settings.gradle :

    include ':googlemapssdkm4b_lib'

  7. Ajoutez une dépendance de module dans le fichier build.gradle de votre application :

    compile project(':googlemapssdkm4b_lib')

Convertir toutes les configurations existantes qui utilisent les services Google Play

  1. Si possédez une application qui utilise les services Google Play, remplacez toutes les références au package com.google.android.gms.maps par com.google.android.m4b.maps.
  2. Faites précéder toutes les références aux attributs de disposition XML par m4b_. Par exemple : m4b_mapType et m4b_cameraZoom.

Obtenir une clé d'API et l'ajouter à votre application

Générez une clé d'API pour votre projet et ajoutez-la au fichier AndroidManifest.xml, tel que décrit ci-dessous. Vous devez configurer une clé d'API restreinte à Android.

Votre clé d'API vous identifie en tant que client Google Maps Mobile SDK for Work et vous permet d'acheter des quotas et de bénéficier du support pour votre application. Vous pouvez générer une clé d'API sur un compte pour lequel le service Google Maps Mobile SDK est activé, en utilisant une combinaison du nom de package de votre application et de son certificat numérique.

Votre clé d'API se base sur une version abrégée du certificat numérique de votre application. Toutes les applications Android sont signées à l'aide d'un certificat numérique dont vous détenez la clé privée. (Pour plus d'informations sur les certificats numériques, voir le guide Android sur la signature des applications.)

Afficher les informations relatives au certificat de votre application

La restriction de clé d'API Android se base sur une version abrégée du certificat numérique de l'application, appelée empreinte SHA-1.

Obtenir les informations de certification d'Android Studio

Si vous suivez le guide de démarrage de Google Maps Android API, Android Studio crée un fichier google_maps_api.xml pratique avec les identifiants de votre application.

Choisissez l'une des méthodes suivantes pour obtenir votre clé d'API depuis Android Studio :

  • Méthode la plus simple et la plus rapide : Utilisez le lien fourni dans le fichier google_maps_api.xml qu'Android Studio a créé pour vous :
    1. Copiez le lien fourni dans le fichier google_maps_api.xml et collez-le dans votre navigateur. Ce lien vous dirige vers la Google API Console et fournit les informations requises pour la Google API Console via des paramètres d'URL, réduisant ainsi la saisie manuelle nécessaire de votre part.
    2. Suivez les instructions pour créer un nouveau projet sur la Google API Console ou sélectionnez un projet existant.
    3. Créez une clé d'API restreinte à Android pour votre projet.
    4. Copiez la clé d'API obtenue, retournez dans Android Studio et collez la clé d'API dans l'élément <string> du fichier google_maps_api.xml.
  • Méthode un peu moins rapide : Utilisez les informations d'identification fournies dans le fichier google_maps_api.xml qu'Android Studio a créé pour vous :
    1. Copiez les informations d'identification fournies dans le fichier google_maps_api.xml.
    2. Allez à la Google API Console dans votre navigateur.
    3. Utilisez les informations d'identification copiées pour ajouter votre application à une clé d'API existante ou pour en créer une nouvelle.

Obtenir vous-même les informations relatives au certificat

Si vous n'avez pas suivi le guide de démarrage lors de la création de votre application, vous devez obtenir vous-même l'empreinte SHA-1 pour votre certificat. Assurez-vous d'abord d'utiliser le bon certificat. Il existe deux types de certificats :

  • Un certificat de débogage : Les outils Android SDK génèrent ce certificat automatiquement lorsque vous créez une version de débogage. Utilisez ce certificat uniquement avec les applications que vous testez. N'essayez pas de publier une application signée avec un certificat de débogage. Le certificat de débogage est décrit plus en détail dans la section Signature en mode débogage de la documentation du développeur Android.
  • Certificat de production : Les outils Android SDK génèrent ce certificat lorsque vous créez une version de production. Vous pouvez également générer ce certificat à l'aide du programme keytool. Utilisez ce certificat lorsque vous êtes prêt à proposer une version publique de l'application.

Procédez comme suit pour afficher l'empreinte SHA-1 d'un certificat à l'aide du programme keytool et du paramètre -v. Pour plus d'informations sur le Keytool, voir la documentation Oracle.

Certificat de débogage

Afficher l'empreinte du certificat de débogage

  1. Recherchez le fichier keystore (magasin de clés) de débogage. Intitulé debug.keystore, il est généré la première fois que vous créez le projet. Par défaut, il est stocké dans le même répertoire que vos fichiers AVD (Android Virtual Device) :

    • macOS et Linux : ~/.android/
    • Windows Vista etWindows 7 : C:\Users\your_user_name\.android\
  2. Listez l'empreinte SHA-1 :

    • Pour Linux ou macOS, ouvrez une fenêtre sur le terminal et procédez comme suit :

      keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
    • Pour Windows Vista et Windows 7, exécutez la commande suivante :

      keytool -list -v -keystore "%USERPROFILE%\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android

Le résultat doit ressembler à ce qui suit :

Alias name: androiddebugkey
Creation date: Jan 01, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4aa9b300
Valid from: Mon Jan 01 08:04:04 UTC 2013 until: Mon Jan 01 18:04:04 PST 2033
Certificate fingerprints:
     MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6A:AC:F9
     SHA1: BB:0D:AC:74:D3:21:E1:43:07:71:9B:62:90:AF:A1:66:6E:44:5D:75
     Signature algorithm name: SHA1withRSA
     Version: 3
Certificat de production

Afficher l'empreinte du certificat de production

  1. Recherchez le fichier keystore du certificat de production. Il n'existe pas d'emplacement ou de nom par défaut pour le keystore de production. Si vous n'en spécifiez aucun lors du développement de votre application pour publication, le fichier .apk de la version n'est pas signé et vous devez le signer avant la publication. Pour le certificat de production, vous avez également besoin de l'alias du certificat et des mots de passe pour le keystore et le certificat. Vous pouvez afficher les alias de toutes les clés d'un keystore en saisissant :

    keytool -list -keystore your_keystore_name

    Remplacez le paramètre your_keystore_name par le chemin complet valide et le nom du keystore en ajoutant l'extension .keystore. Vous êtes alors invité à saisir le mot de passe du keystore. L'outil keytool affiche tous les alias du keystore.

  2. Saisissez la commande suivante sur un terminal ou dans une invite de commande :

    keytool -list -v -keystore your_keystore_name -alias your_alias_name

    Remplacez le paramètre your_keystore_name par le chemin complet valide et le nom du keystore en ajoutant l'extension .keystore. Remplacez le paramètre your_alias_name par l'alias que vous avez affecté au certificat lors de sa création.

Le résultat doit ressembler à ce qui suit :

Alias name: <alias_name>
Creation date: Feb 02, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4cc9b300
Valid from: Mon Feb 02 08:01:04 UTC 2013 until: Mon Feb 02 18:05:04 PST 2033
Certificate fingerprints:
    MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6B:AC:F9
    SHA1: BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:90:AF:A1:66:6E:44:5D:75
    Signature algorithm name: SHA1withRSA
    Version: 3

La ligne commençant par SHA1 contient l'empreinte SHA-1 du certificat. L'empreinte est une séquence de 20 nombres hexadécimaux à deux chiffres séparés par un deux-points.

Pour plus d'informations sur les certificats numériques, voir le guide Android sur la signature des applications.

Vérifier que votre compte est activé pour le

service Google Maps Mobile SDKL'équipe

Google Cloud Support active le service Google Maps Mobile SDKlorsque vous vous inscrivez pour Google Maps Mobile SDK for Work. Le service est activé sur un nouveau projet. Vous pouvez ensuite obtenir une clé d'API depuis Google API Console.

Remarque : Seul le propriétaire initial du projet peut voir le service Google Maps Mobile SDK. Pour demander à ce qued'autres propriétaires soient autorisés à voir le service, soumettez une demande non technique dans le Google Cloud Support Portal.

Vérifiez comme suit que votre compte a bien été activé :

  1. Accédez à la Google API Console et connectez-vous à l'aide de votre compte Google.
  2. Sélectionnez le projet Google Maps Mobile SDK for Work qui a été créé pour vous lorsque vous avez commandé Google Maps Mobile SDK for Work. Le nom du projet commence par Google Maps APIs for Business or Google Maps for Work or Google Maps. Si vous n'avez pas encore acheté l'accès au SDK, contactez l'[équipe commerciale].
  3. Dans la liste APIs du Dashboard, vérifiez que Google Maps Mobile SDK* est activé.

Obtenir une clé d'API depuis la Google API Console

Une fois le service Google Maps Mobile SDK for Work activé pour votre projet, vous devez générer une nouvelle clé.

  1. Accédez à la page Credentials de Google API Console et connectez-vous à l'aide de votre compte Google.
  2. Sélectionnez le projet Google Maps Mobile SDK for Work qui a été créé pour vous lorsque vous avez commandé Google Maps Mobile SDK for Work. Le nom du projet commence par Google Maps APIs for Business or Google Maps for Work or Google Maps. Si vous n'avez pas encore acheté l'accès au SDK, contactez l'[équipe commerciale].
  3. Dans la liste API keys, recherchez une clé indiquant Android restriction.
  4. Si votre projet ne dispose pas déjà d'une clé d'API restreinte à Android, créez-en une maintenant en sélectionnant Create credentials > API key.
  5. Dans la boîte de dialogue qui s'affiche, sélectionnez Restrict key.
  6. Dans la section Restrictions, sélectionnez Android apps, puis saisissez l'empreinte SHA-1 et le nom de package de votre application. Par exemple :

    BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75
    com.example.android.mapexample
    
  7. Cliquez sur Save.

    Votre nouvelle clé d'API restreinte à Android s'affiche dans la liste des clés d'API de votre projet. Une clé d'API est une chaîne de caractères semblable à ce qui suit :

    AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0
    

Ajouter la clé d'API à votre application

Suivez les étapes ci-dessous pour intégrer la clé d'API au manifeste de votre application, dans le fichier AndroidManifest.xml.

  1. Dans AndroidManifest.xml, ajoutez l'élément suivant en tant qu'enfant de l'élément <application>, en l'insérant juste avant la balise fermante </application> :
        <meta-data
            android:name="com.google.android.geo.API_KEY"
            android:value="YOUR_API_KEY"/>
        

    Remplacez YOUR_API_KEY par votre clé d'API dans l'attribut value. Cet élément définit la clé com.google.android.geo.API_KEY sur la valeur de votre clé d'API.

  2. Enregistrez AndroidManifest.xml et recréez l'application.

Remarque : Comme indiqué ci-dessus, com.google.android.geo.API_KEY est le nom de métadonnées recommandé pour la clé d'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 plateforme Android, notamment Google Maps Android API. Pour assurer la rétrocompatibilité, l'API prend également en charge le nom com.google.android.maps.v2.API_KEY. Cet ancien nom autorise l'authentification auprès des Android Maps API v2 uniquement. Une application ne peut spécifier qu'un seul des noms de métadonnées de clé d'API. Si les deux noms sont spécifiés, l'API renvoie une exception.

Spécifier les autorisations de l'application

Spécifiez les autorisations dont votre application a besoin en ajoutant les éléments <uses-permission> en tant qu'enfants de l'élément <manifest> dans le fichier AndroidManifest.xml.

Autorisations de géolocalisation

Si votre application accède à la position actuelle de l'utilisateur en activant la couche My Location, vous devez demander des autorisations de géolocalisation comme décrit dans le guide des données de géolocalisation.

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 plus besoin de l'autorisation WRITE_EXTERNAL_STORAGE pour utiliser Google Maps Android API.

En revanche, si vous prévoyez d'utiliser des versions antérieures du SDK des services Google Play, vous devez demander l'autorisation android.permission.WRITE_EXTERNAL_STORAGE.

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

Remarque : Si votre application cible l'API 23 (Android 6.0), qui nécessite l'utilisation d'autorisations d'exécution, vous devez cibler la version 8.3 ou ultérieure du SDK des services Google Play.

Autorisations fusionnées automatiquement dans votre manifeste

Les autorisations suivantes sont définies dans le manifeste des services Google Play et sont automatiquement fusionnées avec le manifeste de votre application lors de la création. Vous n'avez pas besoin de les ajouter directement à votre manifeste :

Spécifier OpenGL ES version 2

Google Maps Android API utilise OpenGL ES version 2 pour effectuer le rendu de la carte. Le paramètre suivant est défini dans le manifeste des services Google Play et est automatiquement fusionné avec le manifeste de votre application lors de la création. Vous n'avez pas besoin de l'ajouter directement à votre manifeste :

<uses-feature
        android:glEsVersion="0x00020000"
        android:required="true"/>

Cela permet de notifier les services externes de cette condition requise. En particulier, cela a pour effet d'empêcher Google Play Store d'afficher votre application sur les appareils qui ne prennent pas en charge OpenGL ES version 2.

Ajouter une carte

La façon la plus simple de vérifier si votre application est correctement configurée consiste à lui ajouter une carte simple.

Remarque : Ce code ne doit pas être utilisé dans une application en production.

  1. Dans le fichier activity_main.xml, ajoutez le fragment suivant.

    <?xml version="1.0" encoding="utf-8"?>
    <fragment xmlns:android="http://schemas.android.com/apk/res/android"
              android:id="@+id/map"
              android:layout_width="match_parent"
              android:layout_height="match_parent"
              android:name="com.google.android.m4b.maps.MapFragment"/>
    
  2. Dans MainActivity.java, ajoutez le code suivant.

    package com.example.mapdemo;
    
    import android.app.Activity;
    import android.os.Bundle;
    
    public class MainActivity extends Activity {
    
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_main);
        }
    }
    

Créer et exécuter votre application

Créez et exécutez votre application. Vous devriez voir une carte.

Résolution des erreurs :

  • Si aucune carte n'est affichée, vérifiez que vous avez bien suivi toutes les étapes décrites plus haut. Assurez-vous en particulier que votre clé d'API est correcte et que votre compte est activé pour le service Google Maps Mobile SDK for Work.

  • Si le nombre de méthodes dans votre projet dépasse la limite, il se peut que vous receviez l'erreur suivante :

    « Unable to execute dex: method ID not in [0, 0xffff]: 65536 »

    Pour plus d'informations sur les causes et les solutions, voir le Guide du développeur Android qui explique comment créer des applications avec plus de 65 000 méthodes.

  • Si votre projet dépend déjà de Guava, il se peut que vous receviez des erreurs de collision de classes comme celle-ci :

    « com.android.dex.DexException: Multiple dex files define Lcom/google/common/annotations/Beta`

    Pour résoudre ce problème, vous pouvez supprimer la copie de Guava du répertoire google-maps-sdk-m4b_lib/libs.

Plus d’infos

Comment migrer une application existante

L'API Android disponible avec Google Maps Mobile SDK for Work a été conçue pour être très similaire à la version standard de Google Maps Android API. Le processus de migration est donc très simple.

  1. Téléchargez Google Maps Android API pour Google Maps Mobile SDK for Work et ajoutez le SDK à votre projet, tel que décrit plus haut.
  2. Remplacez toutes les références au package com.google.android.gms.maps par com.google.android.m4b.maps.
  3. Faites précéder toutes les références aux attributs de disposition XML par m4b_. Par exemple : m4b_mapType et m4b_cameraZoom.
  4. Générez une nouvelle clé d'API pour votre projet et ajoutez-la au fichier AndroidManifest.xml, tel que décrit dans le guide sur l'authentification.
  5. Créez votre application.

Comparer les versions

Le tableau suivant décrit les principales différences entre l'utilisation de la version standard de Google Maps Android API et l'utilisation de l'API avec Google Maps Mobile SDK for Work.

  Standard Google Maps Android API Google Maps Mobile SDK for Work
Nom du package com.google.android.gms.maps com.google.android.m4b.maps
Attributs XML dans le fichier de disposition Utiliser le nom de l'attribut sans préfixe. Par exemple : mapType. Faire précéder tous les noms d'attribut par m4b_. Par exemple : m4b_mapType. Pour plus de détails, voir la documentation sur les attributs XML.
Méthode de téléchargement Inclus dans les services Google Play. Disponible en tant que bibliothèque statique.
Types de support Support de la communauté Accès au support Premium
Conditions Soumis aux Google Maps APIs Conditions de service. Soumis aux conditions générales de Google Maps Mobile SDK for Work .

Services Google Play

La version standard de Google Maps Android API requiert à la fois l'APK des services Google Play et la bibliothèque client des services Google Play. Toutefois, lorsqu'il est utilisé avec Google Maps Mobile SDK for Work, le SDK nécessite uniquement que l'APK des services Google Play soit installé sur l'appareil cible ; la bibliothèque client n'est pas requise.

Lorsque vous migrez votre application vers Google Maps Mobile SDK for Work, il n'est pas nécessaire de supprimer le SDK des services Google Play de votre projet. Toutefois, vous devez supprimer toute référence au package com.google.android.gms.maps. Les services Google Play contiennent une version de Google Maps Android API ainsi que d'autres services Google. Si vous faites appel aux services Play dans votre application pour utiliser d'autres API Google, assurez-vous de n'utiliser que le SDK Google Maps Mobile SDK for Work (le packagecom.google.android.m4b.maps) pour accéder à Maps.

Bien que la bibliothèque client des services Google Play ne soit pas requise, vous pourriez trouver utile de l'inclure afin de pouvoir tirer parti d'autres API Google, telles que Google+ ou l'API de géolocalisation.

Échantillon de code

Le référentiel Google Maps sur GitHub inclut plusieurs échantillons illustrant l'utilisation de Google Maps Android API dans votre application Android. Notez que dans l'échantillon, les applications utilisent le package com.google.android.gms.maps, et non pas le package com.google.android.m4b.maps utilisé avec Google Maps Mobile SDK for Work. Dans l'échantillon, les applications requièrent également le SDK des services Google Play, car elles utilisent les API Location pour certaines parties de la démo.

Vous trouverez par ailleurs des extraits de code sur chaque page du Guide du développeur.

Documentation

Le Guide du développeur et la documentation de référence disponibles Google Maps Mobile SDK for Work sur notre site constituent la principale source d'informations sur .