Premiers pas avec le plan Premium sur Android

Votre licence Google Maps APIs Premium Plan offre une prise en charge améliorée de Google Maps Android API. Ce document vous indique comment créer une application Android qui utilise Google Maps Android API avec Premium Plan.

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, comme « Google Maps for Work », ainsi que 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 Premium Plan est disponible en 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 APIs Premium Plan à 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.

Spécifier les paramètres dans le fichier manifeste de l'application

Une application Android qui utilise Google Maps Android API doit spécifier les paramètres suivants dans le fichier manifeste, AndroidManifest.xml :

Clé d'API

Générez une clé d'API pour votre projet et ajoutez-la au fichierAndroidManifest.xml, tel que décrit dans le guide sur l'authentification.

Autorisations

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 :

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 ne s'affiche, 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 APIs Premium Plan.

  • 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 conflit 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 Premium Plan 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 Premium Plan 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 Premium Plan.

  Standard Google Maps Android API Premium Plan
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 APIs Premium Plan .

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 APIs Premium Plan, 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 Premium Plan, il n'est pas nécessaire de supprimer le SDK des services Google Play de votre projet. Vous devez toutefois supprimer toute référence au packagecom.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 Premium Plan (le package com.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 Premium Plan. Dans l'échantillon, les applications requièrent également le SDK des services Google Play, car elles utilisent les API de géolocalisation 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 sur notre site constituent la principale source d'informations sur Google Maps APIs Premium Plan.