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 Name Navigation SDK Class Name MapView.java
NavigationView.java
MapFragment.java
SupportNavigationFragment.java
NavigationView
class, and the currentMapView
class. You can think of them like theMapView
andMapFragment
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 theRoadSnappedLocationProvider
, 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
- Remove the Maps SDK for Android integration from your build (i.e. gradle). Having both SDKs will cause compile errors.
- Replace instances of
MapView
with instances ofNavigationView
. - Replace instances of
MapFragment
with instances ofNavigationSupportFragment
.
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 Method | New 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 Class | New 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.
Method | Change |
---|---|
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.
Marker-related methods
Method | Change |
---|---|
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 callingonSaveInstanceState()
. 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 tomapMarker#icon(BitmapDescriptor)
. This change requires that you migrate from using theBitMap
, to use theBitmapDescriptor
.
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.
Method | Change |
---|---|
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 toNavigationView
andSupportNavigationFragment
.Camera.followMyLocation()
method was moved toGoogleMap
.
- You can replace calls to
Camera.setLocation()
with eitherGoogleMap.moveCamera()
orGoogleMap.animateCamera()
. setOnFollowMyLocationCallback()
andisCameraFollowingMyLocation()
were added toGoogleMap
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.