Guide de migration

Avertissement :Ce document peut contenir des informations obsolètes. Nous nous efforçons de résoudre ce problème, mais nous vous invitons à consulter nos exemples d'applications sur la page Premiers pas. Ils présentent les comportements et les modèles d'utilisation des API qui vous aident à migrer depuis la version 1.

Le plus grand changement apporté par Google au SDK Navigation pour la version 2 est le remplacement de plusieurs classes du SDK de navigation par leurs équivalents dans le SDK Maps pour Android.

Depuis la version 2.2, le SDK Navigation est un remplacement (presque) direct de l'API Maps des services Google Play. Au lieu de empaqueter toutes les API dans com.google.android.libraries.maps, elles ont été empaquetées dans com.google.android.gms.maps comme les services Google Play. Cela facilite considérablement le passage d'une version des services Google Play au SDK de navigation.

Avertissement :Ces instructions ne sont valables que pour les versions 2.2 et ultérieures.

Avantages

• Meilleure utilisation de la mémoire. Vous utilisez maintenant moins de mémoire et de bande passante que si vous utilisiez à la fois le SDK et le SDK Maps pour Android.
• Passer du mode d'affichage à la carte au mode de navigation est désormais plus fluide et plus facile à utiliser.
• Vous bénéficiez désormais d'un meilleur contrôle de la caméra.
• Vous pouvez maintenant dessiner des polylignes et des superpositions, et ajouter des styles personnalisés à la carte.

Toutefois, des fonctionnalités telles que Street View et le mode simplifié ne sont pas compatibles.

Important :Le SDK Navigation remplacera le SDK Maps pour Android et vous devrez supprimer toute référence au client.

Prérequis

• La version 2 du SDK Navigation utilise Android Jetpack, une suite de bibliothèques, d'outils et de conseils qui facilite l'écriture d'applications de haute qualité. Cela signifie que vous devez migrer votre application pour qu'elle n'utilise plus les bibliothèques de support afin d'utiliser AndroidX. Pour en savoir plus, consultez Migrer vers AndroidX.

Étape 1 : Effectuer une migration à partir du SDK Maps pour Android

La plupart des fonctionnalités du SDK Maps pour Android sont désormais incluses dans la version 2 du SDK Navigation. Quelques fonctionnalités ont été supprimées, car elles n'étaient pas nécessaires dans un contexte de navigation.

Différences importantes

Le SDK Maps pour Android se trouvait dans les services Google Play.

Les fonctionnalités du SDK Maps pour Android incluses dans la version 2 du SDK Navigation sont basées sur la nouvelle version du SDK Maps pour Android et ne sont pas disponibles dans les services Google Play. Ces nouvelles fonctionnalités s'exécutent sur un moteur plus récent que celui des services Google Play et présentent plusieurs améliorations. Cela signifie également que la carte s'exécute dans le processus de votre application, et non dans le processus du service Google Play.

Certains cours ont été renommés

Le tableau suivant répertorie les cours renommés. Cela a permis de les différencier de leur équivalent SDK Maps pour Android.

Nom de classe du SDK Maps pour Android	Nom de classe du SDK de navigation
MapView.java	NavigationView.java
MapFragment.java	SupportNavigationFragment.java

Ces classes contiennent une combinaison des méthodes disponibles dans l'ancienne classe NavigationView et dans la classe MapView actuelle. Vous pouvez les considérer comme les classes MapView et MapFragment, mais avec un support de navigation.

Éléments géographiques supprimés

Certaines fonctionnalités de Maps ont été supprimées, car elles n'avaient pas de sens dans un contexte de navigation ou en raison d'incompatibilités techniques. Fonctionnalités supprimées :

• Street View.
• Mode simplifié, qui est insuffisant pour la navigation.
• Vous ne pouvez pas définir de LocationProvider lorsque l'appareil photo est en mode Suivre. En effet, la navigation s'appuie sur le RoadSnappedLocationProvider, et passer à ce fournisseur peut entraîner des problèmes lors de la navigation.
• L'application de limites de zoom min./max. et les limites de LatLng n'a aucun effet lorsque l'appareil photo est en mode Suivre.
• Veuillez contacter votre représentant client si ces fonctionnalités manquantes vous posent problème.

Procédure de migration

1. Supprimez l'intégration du SDK Maps pour Android de votre build (Gradle). Les deux SDK entraînent des erreurs de compilation.
2. Remplacez les instances de MapView par des instances de NavigationView.
3. Remplacez les instances de MapFragment par des instances de NavigationSupportFragment.

Si votre application n'utilisait pas auparavant le SDK Navigation, la migration est terminée.

Étape 2 : Migrer à partir de la version 1.x du SDK Navigation

Pour migrer votre intégration de la version 1.x du SDK Navigation vers la version 2, procédez comme suit :

1. Obtenir la carte à l'aide de nouvelles méthodes

La façon d'obtenir une carte a changé. Avant la version 2, vous obteniez la carte à l'aide d'un appel synchrone. Vous allez maintenant utiliser un appel asynchrone. Le tableau suivant répertorie les anciennes méthodes, ainsi que les nouvelles qui permettent d'obtenir la carte.

Ancienne méthode	Nouvelle méthode
NavigationView.getMap()	NavigationView.getMapAsync()
SupportNavigationFragment.getMap()	SupportNavigationFragment.getMapAsync()

Remarque :La classe NavigationFragment a été supprimée, car la classe Fragment a été abandonnée au profit de la classe SupportFragment.

2. Migrer des bibliothèques

La version 1.x du SDK de navigation contenait sa propre mise en œuvre de plusieurs classes du SDK Maps pour Android. Ces classes appartenaient au package com.google.android.libraries.navigation.

Dans la version 2, ces classes ont été remplacées par les implémentations du SDK Maps pour Android, qui se trouvent dans le package com.google.android.gms.maps.model. Vous pouvez migrer votre application pour intégrer les nouvelles classes en effectuant une recherche et un remplacement.

Le tableau suivant répertorie les anciens cours et les nouveaux.

Ancienne classe	Nouvelle classe
com.google.android.libraries.navigation.LatLng	com.google.android.gms.maps.model.LatLng
com.google.android.libraries.navigation.LatLngBounds	com.google.android.gms.maps.model.LatLngBounds
com.google.android.libraries.navigation.Marker	com.google.android.gms.maps.model.Marker
com.google.android.libraries.navigation.MarkerOptions	com.google.android.gms.maps.model.MarkerOptions
com.google.android.libraries.navigation.VisibleRegion	com.google.android.gms.maps.model.VisibleRegion

3. Tenez compte des modifications apportées aux API existantes

Le tableau suivant répertorie les principales modifications apportées par Google pour la version 2 du SDK Navigation.

Méthode	Changement
NavigationApi.cleanup()	Supprimé. Cette méthode n'a pas été utilisée dans le cadre d'un fonctionnement normal et peut entraîner un comportement imprévisible. Vous devez supprimer les appels à cette méthode.
RoadSnappedLocationProvider.requestLocationUpdates()	Supprimé. Utilisez plutôt addLocationListener().
RoadSnappedLocationProvider.stopRequestingLocationUpdates()	Supprimé. Utilisez removeLocationListener() à la place.

4. Passer à la nouvelle classe Marker

La version 2 du SDK Navigation utilise désormais la même implémentation de la classe Marker que le SDK Maps pour Android. Cela entraîne les modifications suivantes.

Méthodes liées aux repères

Méthode	Changement
addMarker(MarkerOptions markerOptions)	Utilise désormais la classe com.google.android.gms.maps.model.MarkerOptions.
removeMarker(Marker marker)	Cette méthode n'existe plus. À la place, la classe Marker dispose désormais d'une méthode marker.remove().
removeAllMarkers()	Cette méthode n'existe plus, mais il existe une méthode clear() qui supprime tous les repères, polylignes, polygones et superpositions de la carte.

Différences entre MarkerOptions

• La méthode describeContents() n'existe pas dans la version 2 du SDK Navigation. Elle vous a permis d'enregistrer les données de la vue en appelant onSaveInstanceState(). Vous devez maintenant suivre vous-même les détails de la vue afin de pouvoir la recréer en cas de modification de la configuration.
• La méthode navMarker#icon(BitMap) a été remplacée par mapMarker#icon(BitmapDescriptor). Pour effectuer cette modification, vous devez migrer depuis BitMap à l'aide de BitmapDescriptor.

Méthodes de repère

Vous allez maintenant utiliser la classe Marker du package com.google.android.gms.maps.model. Le tableau suivant répertorie les différences d'utilisation de cette nouvelle classe Marker.

Méthode	Changement
getAnchorU()	N'existe plus.
getAnchorV()	N'existe plus.
getIcon()	N'existe plus. Vous devez conserver une référence à l'icône vous-même, à utiliser après une modification de configuration lorsque vous devez recréer l'état de la carte.
getPosition()	Il existe toujours.
getTitle()	Il existe toujours.

Remarque :Si vous avez besoin des méthodes supprimées de la classe Marker, faites-le-nous savoir afin que nous puissions vous aider à résoudre votre problème.

5. Contrôle de la caméra

Les commandes de l'appareil photo fournies dans la version 1.x du SDK de navigation étaient relativement limitées. La version 2 du SDK Navigation utilise désormais le même modèle d'appareil photo que le SDK Maps pour Android, sauf que vous bénéficiez également d'un mode de suivi semblable à celui de la version 1.x du SDK Navigation.

Différences majeures

• La classe com.google.android.libraries.navigation.Camera a été supprimée dans la version 2.
  • Camera.showRouteOverview() a été déplacé vers NavigationView et SupportNavigationFragment.
  • La méthode Camera.followMyLocation() a été déplacée vers GoogleMap.
• Vous pouvez remplacer les appels à Camera.setLocation() par GoogleMap.moveCamera() ou GoogleMap.animateCamera().
• setOnFollowMyLocationCallback() et isCameraFollowingMyLocation() ont été ajoutés à GoogleMap pour fournir plus d'informations sur le mode de suivi.

Étape 3 : Fusionner les flux d'activité

Si vous utilisiez précédemment la version 1 du SDK Navigation et suivi les instructions ci-dessus, vous aurez migré vos cas d'utilisation de la carte pour utiliser la classe NavigationView, ainsi que vos cas d'utilisation de la navigation pour utiliser GoogleMap. Cependant, vous aurez deux instances de GoogleMap et deux instances de NavigationView. Cela signifie que vous utiliserez encore plus de mémoire que nécessaire. Le passage d'une instance à l'autre peut entraîner des pauses perceptibles dans le rendu fluide de l'interface utilisateur. Pour résoudre ce problème, vous devez fusionner vos flux d'activité/fragmentation afin qu'ils ne puissent partager qu'une seule instance. Cela permet une expérience utilisateur plus fluide et simplifie votre application.