Guida alla migrazione

La modifica più importante che Google ha apportato all'SDK di navigazione per la versione 2 è la sostituzione di diverse classi dell'SDK di navigazione con le rispettive controparti di Maps SDK for Android.

A partire dalla versione 2.2, l'SDK di navigazione sostituisce (quasi) l'API Maps di Google Play Services. Invece di ripacchettizzare tutte le API in com.google.android.libraries.maps, sono state pacchettizzate in com.google.android.gms.maps, proprio come Google Play Services. In questo modo, il passaggio tra una versione di Google Play Services e l'SDK di navigazione è molto più semplice.

Vantaggi

  • Migliore utilizzo della memoria. Ora utilizzi meno memoria e larghezza di banda rispetto a come avresti utilizzato contemporaneamente l'SDK di navigazione e l'SDK Maps for Android.
  • Il passaggio dalla modalità di visualizzazione mappa a quella di navigazione è ora più semplice e fluido da utilizzare.
  • Ora hai un controllo maggiore sulla videocamera.
  • Ora puoi eseguire operazioni come disegnare polilinee e sovrapposizioni e aggiungere stili personalizzati alla mappa.

Tuttavia, funzionalità come Street View e Modalità Lite non sono supportate.

Prerequisiti

  • La versione 2 dell'SDK di navigazione utilizza Android Jetpack, una suite di librerie, strumenti e indicazioni che semplifica la scrittura di app di alta qualità. Questo spostamento significa che dovrai eseguire la migrazione della tua app dalle librerie di supporto per usare AndroidX. Per ulteriori informazioni, consulta la pagina Migrazione ad AndroidX.

Passaggio 1: Eseguire la migrazione da Maps SDK for Android

Gran parte delle funzionalità di Maps SDK for Android è ora inclusa nella versione 2 dell'SDK Navigation. Abbiamo rimosso alcune funzionalità perché non erano necessarie in un contesto di navigazione.

Differenze importanti

Maps SDK for Android si trovava in Google Play Services.
Le funzionalità di Maps SDK for Android integrate nella versione 2 dell'SDK Navigation si basano sulla nuova versione di Maps SDK for Android e non sono presenti in Google Play Services. Queste nuove funzionalità vengono eseguite su un motore più recente rispetto a quello di Google Play Services e presentano diversi miglioramenti. Significa anche che la mappa viene eseguita nel processo dell'app e non nel processo di Google Play Service.
Alcuni corsi sono stati rinominati
Nella tabella seguente sono elencati i corsi che sono stati rinominati. Ciò è stato fatto per differenziarli dalla rispettiva controparte Maps SDK for Android.
Nome classe SDK Maps per AndroidNome classe SDK di navigazione
MapView.java NavigationView.java
MapFragment.java SupportNavigationFragment.java
Queste classi contengono una combinazione dei metodi disponibili nella classe NavigationView precedente e nella classe attuale MapView. Possono essere paragonate ai corsi MapView e MapFragment, ma con supporto alla navigazione.
Funzionalità rimosse
Alcune funzionalità di Maps sono state rimosse perché non avevano senso in un contesto di navigazione o perché erano presenti incompatibilità tecniche. Le funzionalità rimosse includono:
  • Street View.
  • Modalità Lite, insufficiente per la navigazione.
  • Non puoi impostare un LocationProvider quando la videocamera è in modalità Segui. Questo perché la navigazione si basa su RoadSnappedLocationProvider e il passaggio a questo provider può causare problemi durante la navigazione.
  • L'applicazione dello zoom Min/Max e dei limiti di LatLng non ha effetto quando la fotocamera è in modalità Segui.
  • Rivolgiti al tuo rappresentante clienti se queste funzionalità mancanti ti causano problemi.

Passi per la migrazione

  1. Rimuovi l'integrazione di Maps SDK for Android dalla build (ad es. Gradle). La presenza di entrambi gli SDK causerà errori di compilazione.
  2. Sostituisci le istanze di MapView con istanze di NavigationView.
  3. Sostituisci le istanze di MapFragment con istanze di NavigationSupportFragment.

Se la tua applicazione non utilizzava in precedenza l'SDK di navigazione, la migrazione è completa.

Passaggio 2: Esegui la migrazione dalla versione 1.x dell'SDK di navigazione

Per eseguire la migrazione dell'integrazione v1.x dell'SDK di navigazione alla versione v2, esegui i passaggi riportati di seguito.

1. Ottieni la mappa con nuovi metodi

Il modo in cui visualizzi una mappa è cambiato. Prima della versione 2, veniva visualizzata la mappa utilizzando una chiamata sincrona. A questo punto, utilizzerai una chiamata asincrona. Nella tabella seguente sono elencati i metodi precedenti e quelli nuovi per ottenere la mappa.

Metodo precedenteNuovo metodo
NavigationView.getMap() NavigationView.getMapAsync()
SupportNavigationFragment.getMap() SupportNavigationFragment.getMapAsync()

2. Esegui la migrazione delle librerie

La versione 1.x dell'SDK Navigation conteneva la propria implementazione di varie classi di Maps SDK for Android. Queste classi appartenevano al pacchetto com.google.android.libraries.navigation.

Nella versione 2, queste classi sono state sostituite dalle implementazioni di Maps SDK for Android, che si trovano all'interno del pacchetto com.google.android.gms.maps.model. Puoi eseguire la migrazione della tua app per integrare le nuove classi eseguendo una ricerca e sostituzione.

Nella tabella seguente sono elencati i corsi precedenti insieme a quelli nuovi.

Vecchio corsoNuovo corso
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. Applica le modifiche alle API esistenti

La seguente tabella elenca le modifiche principali apportate da Google per la versione 2 dell'SDK di navigazione.

MetodoCambio
NavigationApi.cleanup() Rimosso. Questo metodo non è stato utilizzato per il normale funzionamento e potrebbe causare comportamenti imprevedibili. Devi rimuovere le chiamate a questo metodo.
RoadSnappedLocationProvider.requestLocationUpdates() Rimosso. Usa invece il criterio addLocationListener().
RoadSnappedLocationProvider.stopRequestingLocationUpdates() Rimosso. Usa invece il criterio removeLocationListener().

4. Passa al nuovo corso Indicatore

La versione 2 dell'SDK Navigation utilizza ora la stessa implementazione della classe Marker dell'SDK Maps for Android. Vengono introdotte le seguenti modifiche.

MetodoCambio
addMarker(MarkerOptions markerOptions) Ora utilizza la classe com.google.android.gms.maps.model.MarkerOptions.
removeMarker(Marker marker) Questo metodo non esiste più. Ora la classe Marker ha un metodo marker.remove().
removeAllMarkers() Questo metodo non esiste più, anche se esiste un metodo clear() che rimuove tutti gli indicatori, le polilinee, i poligoni e gli overlay dalla mappa.

Differenze di MarkerOptions

  • Il metodo describeContents() non esiste nella versione 2 dell'SDK di navigazione. Ti ha consentito di salvare i dati della visualizzazione chiamando onSaveInstanceState(). Ora dovrai monitorare autonomamente i dettagli della vista per ricostruire la vista in caso di modifica alla configurazione.
  • Il metodo navMarker#icon(BitMap) è stato modificato in mapMarker#icon(BitmapDescriptor). Questa modifica richiede l'esecuzione della migrazione dall'BitMap per l'utilizzo di BitmapDescriptor.

Metodi degli indicatori

Ora utilizzerai la classe Marker del pacchetto com.google.android.gms.maps.model. La seguente tabella elenca le differenze nell'utilizzo di questa nuova classe Marker.

MetodoCambio
getAnchorU() Non esiste più.
getAnchorV() Non esiste più.
getIcon() Non esiste più.
Devi gestire personalmente un riferimento all'icona, da utilizzare dopo una modifica alla configurazione, quando devi ricreare lo stato della mappa.
getPosition() Esiste ancora.
getTitle() Esiste ancora.

5. Controllo della fotocamera

I controlli della fotocamera forniti nella versione 1.x dell'SDK di navigazione erano relativamente limitati. La versione 2 dell'SDK di navigazione ora utilizza lo stesso modello di fotocamera utilizzato da Maps SDK for Android, ma è disponibile anche una modalità Follow simile a quella nella versione 1.x dell'SDK di navigazione.

Differenze principali

  • La classe com.google.android.libraries.navigation.Camera è stata rimossa nella versione 2.
    • Camera.showRouteOverview() è stato spostato in NavigationView e SupportNavigationFragment.
    • Il metodo Camera.followMyLocation() è stato spostato in GoogleMap.
  • Puoi sostituire le chiamate a Camera.setLocation() con GoogleMap.moveCamera() o GoogleMap.animateCamera().
  • setOnFollowMyLocationCallback() e isCameraFollowingMyLocation() sono stati aggiunti a GoogleMap per fornire ulteriori informazioni sulla modalità Segui.

Passaggio 3: Unisci flussi di attività

Se in precedenza utilizzavi la versione 1 dell'SDK di navigazione e seguivi le istruzioni riportate sopra, avrai eseguito la migrazione dei casi d'uso delle mappe in modo da utilizzare la classe NavigationView e dei casi d'uso per la navigazione in modo da utilizzare GoogleMap. Tuttavia, avrai due istanze di GoogleMap e due istanze di NavigationView. Ciò significa che utilizzerai comunque più memoria del necessario e il passaggio da un'istanza all'altra può comportare pause percepibili nella fluidità del rendering dell'interfaccia utente. Per risolvere questo problema, devi unire i flussi attività/frammento in modo che possano condividere una singola istanza. Ciò fornisce un'esperienza utente più fluida e semplifica l'applicazione.