Guia de migração

Aviso: este documento pode conter informações desatualizadas. Estamos trabalhando para resolver isso, mas recomendamos que você consulte nossa página Primeiros passos enquanto isso para conferir nossos apps de exemplo. Elas mostram os comportamentos e os padrões de uso da API que ajudam você a migrar da v1.

A maior mudança que o Google fez no SDK do Navigation para a v2 é a substituição de várias classes do SDK do Navigation pelas equivalentes do SDK do Maps para Android.

A partir da versão 2.2, o SDK do Navigation é um substituto (quase) imediato da API Maps do Google Play Services. Em vez de reempacotar todas as APIs em com.google.android.libraries.maps, elas foram empacotados em com.google.android.gms.maps da mesma forma que o Google Play Services. Isso facilita muito a alternância entre uma versão do Google Play Services e o SDK do Navigation.

Aviso :estas instruções são válidas apenas para a versão 2.2 e mais recentes.

Vantagens

• Melhor uso da memória. Agora você usa menos memória e largura de banda do que se estivesse usando o SDK do Navigation e o SDK do Maps para Android.
• Mudar do modo de visualização de mapa para o de navegação agora é mais fácil e fácil.
• Agora você tem mais controle sobre a câmera.
• Agora você pode desenhar polilinhas e sobreposições, além de adicionar estilos personalizados ao mapa.

No entanto, recursos como o Street View e o modo Lite não são compatíveis.

Importante :o SDK do Navigation vai substituir o SDK do Maps para Android, e você precisará remover todas as referências ao cliente.

Pré-requisitos

• A versão 2 do SDK do Navigation usa o Android Jetpack, um pacote de bibliotecas, ferramentas e orientações que facilita a programação de apps de alta qualidade. Essa mudança significa que você precisa migrar seu app das Bibliotecas de Suporte para usar o AndroidX. Para mais informações, consulte Como migrar para o AndroidX.

Etapa 1. Migrar do SDK do Maps para Android

A maioria das funcionalidades do SDK do Maps para Android agora está incluída na versão 2. Alguns recursos foram removidos porque não eram necessários em um contexto de navegação.

Diferenças importantes

O SDK do Maps para Android estava no Google Play Services.

Os recursos do SDK do Maps para Android que são incluídos na v2 do SDK do Navigation são baseados na nova versão e não estão no Google Play Services. Esses novos recursos são executados em um mecanismo mais recente que o do Google Play Services e têm várias melhorias. Isso também significa que o mapa é executado no processo do seu app, e não no processo do Google Play Services.

Algumas turmas foram renomeadas

A tabela a seguir lista as classes que foram renomeadas. Isso foi feito para diferenciá-los do SDK do Maps para Android.

Nome da classe do SDK do Maps para Android	Nome da classe do SDK de navegação
MapView.java	NavigationView.java
MapFragment.java	SupportNavigationFragment.java

Essas classes contêm uma combinação dos métodos disponíveis na classe NavigationView antiga e na classe MapView atual. Elas são como as classes MapView e MapFragment, mas com compatibilidade com navegação.

Recursos removidos

Alguns recursos do Maps foram removidos porque não faziam sentido em um contexto de navegação ou devido a incompatibilidades técnicas. Os recursos removidos incluem:

• Street View
• Modo Lite, que é insuficiente para navegação.
• Não é possível definir um LocationProvider quando a câmera está no modo "Seguir". Isso ocorre porque a navegação depende do RoadSnappedLocationProvider, e alternar para esse provedor pode causar problemas durante a navegação.
• A aplicação de zoom mínimo/máximo e os limites de LatLng não tem efeito quando a câmera está no modo de acompanhamento.
• Entre em contato com o representante do cliente se esses recursos ausentes estiverem causando problemas.

Etapas de migração

1. Remova a integração do SDK do Maps para Android do seu build (ou seja, Gradle). Ter os dois SDKs causará erros de compilação.
2. Substitua as instâncias de MapView por instâncias de NavigationView.
3. Substitua as instâncias de MapFragment por instâncias de NavigationSupportFragment.

Se o aplicativo não estava usando o SDK do Navigation, a migração estará concluída.

Etapa 2: Migrar da v1.x do SDK do Navigation

Siga as etapas abaixo para migrar sua integração v1.x do SDK do Navigation para a v2.

1. Novos métodos para acessar o mapa

A forma de gerar mapas mudou. Antes da v2, você conseguia o mapa usando uma chamada síncrona. Agora, você usará uma chamada assíncrona. A tabela a seguir lista os métodos antigos e novos para receber o mapa.

Método antigo	Novo método
NavigationView.getMap()	NavigationView.getMapAsync()
SupportNavigationFragment.getMap()	SupportNavigationFragment.getMapAsync()

Observação: a classe NavigationFragment foi removida porque a classe Fragment foi descontinuada e substituída pela classe SupportFragment.

2. Migrar bibliotecas

A v1.x do SDK do Navigation continha a própria implementação de várias classes do SDK do Maps para Android. Essas classes pertenciam ao pacote com.google.android.libraries.navigation.

Na v2, essas classes foram substituídas pelas implementações do SDK do Maps para Android, que estão no pacote com.google.android.gms.maps.model. Você pode migrar seu app para integrar as novas classes, realizando uma pesquisa e substituição.

A tabela a seguir lista as classes antigas e as novas.

Classe antiga	Nova turma
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. Acomodar mudanças em APIs existentes

A tabela a seguir lista as principais mudanças que o Google fez na v2 do SDK de navegação.

Método	Mudar
NavigationApi.cleanup()	Removido. Esse método não era usado em operações normais e poderia causar um comportamento imprevisível. Remova as chamadas para esse método.
RoadSnappedLocationProvider.requestLocationUpdates()	Removido. Use addLocationListener().
RoadSnappedLocationProvider.stopRequestingLocationUpdates()	Removida. Use removeLocationListener()

4. Mudar para a nova classe Marker

A v2 do SDK do Navigation agora usa a mesma implementação da classe Marker que o SDK do Maps para Android. Isso introduz as mudanças a seguir.

Métodos relacionados a marcadores

Método	Mudar
addMarker(MarkerOptions markerOptions)	Agora usa a classe com.google.android.gms.maps.model.MarkerOptions.
removeMarker(Marker marker)	Este método não existe mais. Em vez disso, a classe Marker agora tem um método marker.remove().
removeAllMarkers()	Esse método não existe mais, embora exista um método clear() que remove todos os marcadores, polilinhas, polígonos e sobreposições do mapa.

Diferenças de MarkerOptions

• O método describeContents() não existe na v2 do SDK do Navigation. Ela permite que você salve os dados de visualização chamando onSaveInstanceState(). Agora, você precisará rastrear os detalhes da visualização para poder reconstruí-la quando houver uma alteração de configuração.
• O método navMarker#icon(BitMap) mudou para mapMarker#icon(BitmapDescriptor). Essa mudança exige que você migre do BitMap para o BitmapDescriptor.

Métodos de marcador

Agora você usará a classe Marker do pacote com.google.android.gms.maps.model. A tabela a seguir lista as diferenças no uso dessa nova classe Marker.

Método	Mudar
getAnchorU()	Não existe mais.
getAnchorV()	Não existe mais.
getIcon()	Não existe mais. Você precisa manter uma referência ao ícone para usar após uma alteração de configuração, quando precisar recriar o estado do mapa.
getPosition()	Ainda existe.
getTitle()	Ainda existe.

Observação :se você precisar dos métodos removidos na classe Marker, entre em contato para ajudarmos a resolver o problema.

5. Controle da câmera

Os controles de câmera fornecidos na v1.x do SDK do Navigation eram relativamente limitados. A versão 2 do SDK do Navigation agora usa o mesmo modelo de câmera usado pelo SDK do Maps para Android, mas você também recebe um Modo de acompanhamento semelhante ao da v1.x.

Principais diferenças

• A classe com.google.android.libraries.navigation.Camera foi removida na v2.
  • Camera.showRouteOverview() foi movido para NavigationView e SupportNavigationFragment.
  • O método Camera.followMyLocation() foi movido para GoogleMap.
• Você pode substituir chamadas para Camera.setLocation() por GoogleMap.moveCamera() ou GoogleMap.animateCamera().
• setOnFollowMyLocationCallback() e isCameraFollowingMyLocation() foram adicionados a GoogleMap para fornecer mais informações sobre o modo "Acompanhar".

Etapa 3. Mesclar fluxos de atividades

Se você usava a V1 do SDK do Navigation e seguiu as instruções acima, terá migrado os casos de uso do mapa para a classe NavigationView e os casos de uso de navegação migrados para a GoogleMap. No entanto, você terá duas instâncias de GoogleMap e duas instâncias de NavigationView. Isso significa que você ainda vai usar mais memória do que o necessário, e alternar entre as duas instâncias pode resultar em pausas perceptíveis na renderização suave da interface do usuário. Para resolver esse problema, mescle seus fluxos de atividades/fragmentos para que eles possam compartilhar uma única instância. Isso proporciona uma experiência do usuário mais suave e simplifica o aplicativo.