Tutoriel pour afficher correctement des Maps Android en développement et en production

Depuis le début du tutoriel, je parle des modes développement et production. C'est quoi ces deux modes ?

Le mode développement (debogage) représente l'état d'une application en cours de développement. En effet, c'est un mode de test dans lequel les erreurs survenues pendant l'exécution sont affichées de façon détaillée et dans lequel l'EDI (environnement de développement intégré) permet de faire une exécution pas à pas du code source.

Par contre, le mode production (release) représente la version exécutable d'une application (.apk dans le cas d'une application Android). C'est une version dépourvue de tous les éléments de test par conséquent moins volumineuse.

Démarrez votre EDI Eclipse, allez au menu « File > New > Android Application Project ». L'interface de création de nouveaux projets Android s'affiche. Renseignez le nom de l'application, le nom du projet et le nom du package. Pour les autres champs, laissez les valeurs par défaut.

Ensuite, cliquez sur « Next » et pour tous les autres écrans laissez les valeurs par défaut puis validez avec « Finish ». Eclipse vous génère un MainActivity et le layout correspondant.

Pour afficher une carte avec Maps API V2, il est nécessaire d'inclure dans le projet la librairie Google Play services. Pour l'installer, lancez votre SDK Manager depuis la barre d'outils Eclipse.

Dans la boite de dialogue qui apparaît, déroulez « Extras » et installez  « Google Play services ».

Après l'installation, il faut importer la bibliothèque comme projet dans Eclipse. Allez au menu « File > New > Project », déroulez l'entrée « Android » et choisissez « Android Project from Existing Code » puis « Next ».

Cliquez sur « Browse » pour rechercher la bibliothèque Google Play services (vous la trouverez à l'emplacement : chemin de votre sdk/extras/google/google_play_services/libproject.

Une fois la bibliothèque importée, il faut l'ajouter comme dépendance dans votre projet. Pour cela, sélectionnez le projet mapv2 ensuite allez dans le menu « Prroject > Properties », dans le panneau de gauche choisissez « Android ». À droite apparaît un panneau avec un bloc Library, cliquez sur le bouton « Add » et choisissez comme bibliothèque à importer googleplay services puis validez.

En principe si vous avez bien suivi les instructions, la structure de votre projet dans l'explorateur de paquets d'Eclipse devra ressembler à ceci:

À ce stade vous pouvez déjà utiliser les outils Maps API V2. Cependant vous ne pouvez pas encore afficher votre carte, car pour que ce soit possible il vous faut obtenir une API key de votre projet auprès de Google et donner les autorisations nécessaires dans votre fichier Manifest.

Pour obtenir cette clé, allez dans votre console Google Développeur Console Google.Console Google

Pour utiliser cette console, vous devez posséder un compte Gmail.

Créez un projet au niveau de la console, une fois votre projet créé, allez dans le panneau de gauche de votre console sous le Menu « APIs & auth », choisissez  « APIs ».

Dans la liste de services qui se chargent, recherchez « Google Maps Android API V2 », vous trouverez une ligne semblable à celle-ci :

Cliquez sur le bouton « Off » pour l'activer, une fois activé il apparaît tout en haut de la liste comme ci-dessous.

Revenez dans le panneau de gauche et cliquez sur « Credentials ».

C'est ici que vous allez générer une clé pour votre application. Choisissez « Create new Key », ensuite dans la Popup qui s'affiche choisissez « Android Key ». Vous remarquerez que Google demande de donner l'empreinte SHA1 de votre clé. Pour la retrouver, revenez dans l'EDI Eclipse dans le menu « Window > preferences ». Dans le panneau de gauche, déroulez « Android » puis cliquez sur « Build ». Dans le panneau de droite, vous voyez apparaître un contenu, le bloc qui vous intéresse est celui de la capture suivante.

Copiez la valeur dont la clé est SHA1 fingerprint et collez-la dans l'espace indiqué dans votre console suivi du nom de package de votre application séparé par un point-virgule. Vous obtenez quelque chose comme sur la figure ci-contre:

Validez pour générer votre clé.

La clé étant générée, il vous faut définir les autorisations dans le fichier de configuration Manifest de votre projet.

Pour afficher votre Map, l'application a besoin de certaines autorisations en plus de l'API key. Ces permissions sont à mettre avant la balise application du fichier Manifest.

 <!-- on crée une permission pour notre application -->
     <permission android:name="com.abyster.tuto.mapv2.permission.MAPS_RECEIVE" 
         android:protectionLevel="signature"/>
     <!-- on ajoute notre permission à la liste de permissions requises par l'API -->
     <uses-permission android:name="com.abyster.tuto.mapv2.permission.MAPS_RECEIVE" 
         android:protectionLevel="signature"/>
     
     <uses-permission android:name="android.permission.INTERNET"/>
 	<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
 	<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES"/>
 	<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
 	<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
 	<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
	
     <!-- la librairie Maps V2 nécessite openGL pour son bon fonctionnement -->
     <uses-feature android:glEsVersion="0x00020000" android:required="true"/>

Dans la balise application du même fichier Manifest, insérez les deux instructions du code ci-dessous. La première définit la clé de l'API générée précédemment (vous remarquerez que j'ai mis ma clé dans le fichier de déclaration de chaîne de caractères strings.xml avec pour nom api_debug_key et je l'appelle juste dans le Manifest) et la seconde définit la version de l'API Google Play services utilisée.

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

Le fichier manifest final devrait ressembler à ceci:

 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="com.abyster.tuto.mapv2"
     android:versionCode="1"
     android:versionName="1.0" >

     <uses-sdk
        android:minSdkVersion="8"
        android:targetSdkVersion="19" />

     <!-- on crée une permission pour notre application -->
     <permission android:name="com.abyster.tuto.mapv2.permission.MAPS_RECEIVE" 
        android:protectionLevel="signature"/>
     <!-- on ajoute notre permission à la liste de permissions requises par l'API -->
     <uses-permission android:name="com.abyster.tuto.mapv2.permission.MAPS_RECEIVE" 
        android:protectionLevel="signature"/>
    
    <uses-permission android:name="android.permission.INTERNET"/>
 	<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
 	<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES"/>
 	<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
 	<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
 	<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
 	
     <!-- la librairie Maps V2 nécessite openGL pour son bon fonctionnement -->
     <uses-feature android:glEsVersion="0x00020000" android:required="true"/>
   
     <application
         android:allowBackup="true"
         android:icon="@drawable/ic_launcher"
         android:label="@string/app_name"
         android:theme="@style/AppTheme" >
        
         <meta-data android:name="com.google.android.maps.v2.API_KEY"
 	    		   android:value="@string/api_debug_key"/>
         <meta-data android:name="com.google.android.gms.version"
 	    		   android:value="@integer/google_play_services_version" />
        
         <activity
             android:name="com.abyster.tuto.mapv2.MainActivity"
             android:label="@string/app_name" >
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
         </activity>
     </application>
  </manifest>

Remplacez le code de votre activity_main.xml par celui-ci :

 <?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.gms.maps.SupportMapFragment"/>

Au niveau de la ligne android:name, nous avons utilisé SupportMapFragment pour que notre carte puisse s'afficher sur tous les téléphones quelle que soit la version d'Android utilisée par ceux-ci. On aurait pu utiliser MapFragment, alors la carte ne se serait pas affichée sur des téléphones possédant des versions d'Android inférieures à Android 3.0.

MainActivity doit étendre FragmentActivity au lieu d'Activity.

Définissons le code de l'activité pour afficher un point sur la carte. Les explications sont en commentaire dans le code.

 package com.abyster.tuto.mapv2;
 import com.google.android.gms.maps.CameraUpdateFactory;
 import com.google.android.gms.maps.GoogleMap;
 import com.google.android.gms.maps.SupportMapFragment;
 import com.google.android.gms.maps.model.BitmapDescriptorFactory;
 import com.google.android.gms.maps.model.LatLng;
 import com.google.android.gms.maps.model.MarkerOptions;
 import android.os.Bundle;
 import android.support.v4.app.FragmentActivity;
 import android.view.Menu;

 public class MainActivity extends FragmentActivity {
	
 	private GoogleMap GMap;
 	private LatLng yaounde=new LatLng(3.881501,11.50818);
	
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.activity_main);
         
         //on récupère le fragment définit dans le layout qui va contenir la carte
         GMap= ((SupportMapFragment)getSupportFragmentManager().findFragmentById(R.id.map)).getMap();
         
		//on s'assure que l'objet map n'est pas vide
 		if(GMap!=null){
 			//mode d'affichage de la carte
 			GMap.setTrafficEnabled(true);
 			//on autorise l'api à afficher le bouton pour accéder à notre position courante
 			GMap.setMyLocationEnabled(true);
 			
 			//définition du marqueur qui va se positionner sur le point qu'on désire afficher
 			MarkerOptions markerOptions = new MarkerOptions();
		        markerOptions.title("YAOUNDE");
		        markerOptions.visible(true);
		        markerOptions.position(yaounde);
		        markerOptions.icon(BitmapDescriptorFactory.defaultMarker(BitmapDescriptorFactory.HUE_YELLOW));
		        
		        //ajout du marqueur sur la carte
		        GMap.addMarker(markerOptions);
		        //zoom de la caméra sur la position qu'on désire afficher
 			GMap.moveCamera(CameraUpdateFactory.newLatLngZoom(yaounde, 16));
 			//animation le zoom toute les 2000ms
 			GMap.animateCamera(CameraUpdateFactory.zoomTo(15), 2000, null);
 		}
    }
 }

Le niveau de zoom est très important, si vous définissez une mauvaise valeur votre Map n'affichera que la carte du monde. Les deux dernières lignes de code (ligne 40 et 42) vont de paires. La carte ne s'afficherait pas bien sans ces deux instructions. Vous pouvez faire varier la valeur du zoom pour voir les différents effets que cela produit.

Faites un clic droit sur le projet puis « Run As > Android Application », vous devriez obtenir ceci :

Pour afficher votre position, cliquez sur le bouton représenté par une boussole et la carte se déplace et signale votre position avec un point bleu.

Ce test est fait sur un vrai téléphone et non sur un émulateur, car l'application installée directement sur l'émulateur n'affiche pas la carte.

Cependant, après quelques recherches sur la toile, il se pourrait que cela soit possible moyennant certaines configurations préalables sur l'émulateur.

• http://hmkcode.com ;
• http://javamvp.blogspot.com.

Si quelqu'un a déjà eu à le faire autrement, ce serait généreux de sa part de le partager avec nous.

Pour résoudre ce problème, il faut donc générer une autre clé depuis la console API Google, mais cette fois-ci avec l'empreinte SHA-1 du certificat que nous avons créé pour signer notre APK. Pour le faire, lancez l'invite de commande et positionnez-vous dans le répertoire d'installation de votre JDK.

Saisissez la commande : keytool -list -kystore « chemin vers votre keystore ».

Ensuite il vous est demandé de donner le mot de passe de votre certificat (c'est celui utilisé pour créer votre keystore).

Copiez l'empreinte SHA-1 et générez une nouvelle API Key dans la console Google.

Une fois cette tâche accomplie, copiez cette nouvelle clé dans le Manifest pour remplacer la clé de debogage ci-dessous.

 <meta-data android:name="com.google.android.maps.v2.API_KEY" android:value="@string/api_debug_key"/>

Regénérez votre APK cette fois en utilisant le keystore créé précédemment (Use existing keystore). Votre Map devrait s'afficher très bien cette fois-ci.

Ce sont des formes ou schémas fournis par l'API qu'on peut ajouter à une carte en vue de la personnaliser. On distingue :

• Polyline : c'est une classe fournissant des segments d'interconnexions de coordonnées(LatLng) successives sur une carte, elle peut par exemple permettre de représenter un chemin ;
• Polygon : elle fournit à la base la même fonctionnalité que Polyline sauf qu'ici elle interconnecte des coordonnées successives dans un espace fermé, c'est-à-dire que le point d'arrivée rejoint le point de départ ;
• Circle : permet d'ajouter un cercle sur la carte, cercle centré autour d'une coordonnée spécifique et d'un rayon défini.

Les données de localisation fournissent les informations de localisation d'un appareil Android, elles le font via des fournisseurs de position tels que le GPS et Internet. Cela va de la localisation de l'emplacement actuel de l'appareil à la direction et à la méthode de mouvement. Selon les besoins d'une application, vous pouvez choisir entre plusieurs façons de travailler avec des données de localisation.

• La couche MyLocation : fournit les outils pour afficher la position d'un appareil sur la carte.
• Google Play Services Location API : est utilisé dans la programmation pour toutes les requêtes sur les données de localisation.
• LocationSource : interface permettant à l'utilisateur de définir son propre fournisseur de position.

Maps API V2 permet de personnaliser les actions qu'un utilisateur peut réaliser. Cela va de l'ajout de composants d'interface graphique sur la carte à l'ajout des événements autorisés à l'utilisateur et quels comportements adoptés quand ces derniers surviennent.