Migration Guide

The biggest change that Google made to the Navigation SDK for v2 is that we replaced several Navigation SDK classes with their counterparts from the Maps SDK for Android.

As of version 2.2, the Navigation SDK is a (nearly) drop-in replacement for the Google Play Services Maps API. Instead of repackaging all of the APIs into com.google.android.libraries.maps, they have been packaged in com.google.android.gms.maps just like Google Play Services. This makes switching between a Google Play Services version and the Navigation SDK much simpler.

Benefits

  • Better memory usage. You now use less memory and bandwidth than if you were using both the Navigation SDK and the Maps SDK for Android.
  • Switching from map view mode to navigation mode is now smoother and easier to work with.
  • You now have greater control of the camera.
  • You can now do things like draw polylines and overlays, and add custom styles to the map.

However, features like Street View and Lite Mode are not supported.

Prerequisites

  • Version 2 of the Navigation SDK uses Android Jetpack—a suite of libraries, tools, and guidance that makes it easier to write high-quality apps. This move means you must migrate your app from using support libraries to use AndroidX. For more information, see Migrating to AndroidX.

Step 1. Migrate from the Maps SDK for Android

Most of the functionality in the Maps SDK for Android is now included in version 2 of the Navigation SDK. A few features were removed because they weren't needed in a navigation context.

Important differences

The Maps SDK for Android was in Google Play Services.
The Maps SDK for Android features that are bundled in the v2 of the Navigation SDK are based on the new version of the Maps SDK for Android, and are not in Google Play Services. These new features run on a newer engine than the one in Google Play Services, and have several improvements. It also means that the map runs in your app's process, and not in the Google Play Service process.
Some classes were renamed
The following table lists the classes that were renamed. This was done to differentiate them from their Maps SDK for Android counterpart.
Maps SDK for Android Class NameNavigation SDK Class Name
MapView.java NavigationView.java
MapFragment.java SupportNavigationFragment.java
These classes contain a blend of the methods available in the old NavigationView class, and the current MapView class. You can think of them like the MapView and MapFragment classes, but with navigation support.
Removed features
Some Maps features were removed becaused they didn't make sense in a navigation context, or because there were technical incompatibilities. Removed features include:
  • Street View.
  • Lite mode, which is insufficient for navigation.
  • You cannot set a LocationProvider when the camera is in Follow mode. This is because navigation relies on the RoadSnappedLocationProvider, and switching to this provider can cause problems when navigating.
  • Applying Min/Max zoom and LatLng bounds has no effect when the camera is in Follow Mode.
  • Please speak with your customer representative if these missing features are causing you difficulty.

Migration steps

  1. Remove the Maps SDK for Android integration from your build (i.e. gradle). Having both SDKs will cause compile errors.
  2. Replace instances of MapView with instances of NavigationView.
  3. Replace instances of MapFragment with instances of NavigationSupportFragment.

If your application was not previously using Navigation SDK, your migration is complete.

Step 2. Migrate from v1.x of the Navigation SDK

Perform the following steps to migrate your v1.x integration of the Navigation SDK to v2.

1. Get the map using new methods

The way you get a map has changed. Prior to v2, you got the map by using a synchronous call. Now, you'll use an asynchronous call. The following table lists the old methods along with the new methods for getting the map.

Old MethodNew Method
NavigationView.getMap() NavigationView.getMapAsync()
SupportNavigationFragment.getMap() SupportNavigationFragment.getMapAsync()

2. Migrate libraries

v1.x of the Navigation SDK contained its own implementation of several Maps SDK for Android classes. These classes belonged to the com.google.android.libraries.navigation package.

In v2, these classes have been replaced with the Maps SDK for Android implementations, which are under the com.google.android.gms.maps.model package. You can migrate your app to integrate the new classes by performing a search and replace.

The following table lists the old classes along with the new ones.

Old ClassNew Class
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. Accommodate changes to existing APIs

The following table lists key changes that Google made for v2 of the Navigation SDK.

MethodChange
NavigationApi.cleanup() Removed. This method wasn't used for normal operation, and it could cause unpredictable behavior. You must remove calls to this method.
RoadSnappedLocationProvider.requestLocationUpdates() Removed. Use addLocationListener() instead.
RoadSnappedLocationProvider.stopRequestingLocationUpdates() Removed. Use removeLocationListener() instead.

4. Change to the new Marker class

v2 of the Navigation SDK now uses the same implementation of the Marker class as the Maps SDK for Android. This introduces the following changes.

MethodChange
addMarker(MarkerOptions markerOptions) Now uses the com.google.android.gms.maps.model.MarkerOptions class.
removeMarker(Marker marker) This method no longer exists. Instead, the Marker class now has a marker.remove() method.
removeAllMarkers() This method no longer exists, although there is a clear() method that removes all markers, polylines, polygons, and overlays from the map.

MarkerOptions differences

  • The method describeContents() doesn't exist in v2 of the Navigation SDK. It allowed you to save the view data by calling onSaveInstanceState(). Now, you'll have to track the view details yourself so you can reconstruct the view when there is a configuration change.
  • The method navMarker#icon(BitMap) has changed to mapMarker#icon(BitmapDescriptor). This change requires that you migrate from using the BitMap, to use the BitmapDescriptor.

Marker methods

You will now use the Marker class from the com.google.android.gms.maps.model package. The following table list the differences in using this new Marker class.

MethodChange
getAnchorU() No longer exists.
getAnchorV() No longer exists.
getIcon() No longer exists.
You must maintain a reference to the icon yourself, for use after a configuration change, when you need to recreate the map state.
getPosition() Still exists.
getTitle() Still exists.

5. Camera control

The camera controls provided in v1.x of the Navigation SDK were relatively limited. Version 2 of the Navigation SDK now uses the same camera model used by the Maps SDK for Android, except that you also get a Follow Mode similar to that in v1.x of the Navigation SDK.

Key differences

  • The com.google.android.libraries.navigation.Camera class was removed in v2.
    • Camera.showRouteOverview() was moved to NavigationView and SupportNavigationFragment.
    • Camera.followMyLocation() method was moved to GoogleMap.
  • You can replace calls to Camera.setLocation() with either GoogleMap.moveCamera() or GoogleMap.animateCamera().
  • setOnFollowMyLocationCallback() and isCameraFollowingMyLocation() were added to GoogleMap to provide more information about the follow mode.

Step 3. Merge activity flows

If you were previously using V1 of the Navigation SDK and followed the instructions above, then you'll have migrated your map use cases to use the NavigationView class, and you'll have migrated your navigation use cases to use GoogleMap. However, you'll have two instances of GoogleMap, and two instances of NavigationView. This means you will still be using more memory than necessary, and switching between the two instances can result in perceptible pauses in the smooth rendering of the user interface. To solve this problem, you should merge your activity/fragment flows so that they can share a single instance. This provides a smoother user experience, and streamlines your application.