Route updates and rerouting
The Navigation SDK has built-in logic to make sure your users are on the best route as traffic conditions change or the user goes off route. This includes:
- Off-route detection to get users back on track if they have strayed from the current route.
- Route refresh to make sure the current route is still a viable route.
- Alternative routes to offer users alternative routes as available.
Off-route detection
The Navigation SDK detects when a device strayed from a route it was navigating. When a device is determined to be off route, the SDK automatically requests a redirected route by default. If the reroute request is successful, the new route will be delivered via RoutesObserver
.
If you want to customize your application's behavior when a user goes off route, you can observe the event using OffRouteObserver
or control what triggers an off-route event using NavigationRerouteController
.
Observe off-route events
The OffRouteObserver
interface provides a boolean whenever the Navigation SDK is in turn-by-turn navigation and is off route. When the device is determined to be off route, the Navigation SDK will automatically request a new route.
To listen for changes in the off-route state, create the OffRouteObserver
interface object:
val offRouteObserver = object : OffRouteObserver {
override fun onOffRouteStateChanged(offRoute: Boolean) {
// do something when the off route state changes
}
}
Then, register the OffRouteObserver
object with your already-instantiated MapboxNavigation
object.
override fun onStart() {
super.onStart()
mapView.onStart()
mapboxNavigation.registerOffRouteObserver(offRouteObserver)
}
Don’t forget to unregister the OffRouteObserver
interface:
override fun onStop() {
super.onStop()
mapView.onStop()
mapboxNavigation.unregisterOffRouteObserver(offRouteObserver)
}
Customize off-route triggers
To customize the conditions that trigger off-route conditions, you can provide a custom NavigationRerouteController
:
mapboxNavigation.setRerouteController(object : NavigationRerouteController {
// set the conditions that will trigger off-route conditions
})
Or, you can disable off-route detection entirely by passing null
:
mapboxNavigation.setRerouteController(null)
Observe changes to reroute states
Whether you are using the default triggers or a custom NavigationRerouteController
, the controller produces reroute state updates that can be listened to with the RerouteStateObserver
:
mapboxNavigation.getRerouteController()?.registerRerouteStateObserver(object : RerouteStateObserver {
// do something when the reroute state changes
})
NavigationRerouteController
if you would like to retry the reroute request if the first request fails.Route refresh
Traffic conditions along a route can change while you're navigating, causing the initial route information to be out of date. The Navigation SDK can refresh a route to make sure your users stay on track as they progress along a route.
Route refresh interval is configured with the RouteRefreshOptions.intervalMillis
parameter. By default, the SDK will refresh the current route every five minutes, and if the refresh request is successful, an updated route will be delivered via RoutesObserver
.
RouteOptions.enableRefresh
is true.Alternative routes
Traffic conditions along a route can change while you're navigating, causing the initial route to no longer be as fast as it was when you departed. The Navigation SDK can provide alternative routes to make sure your users are on the best route.
The Navigation SDK is continuously looking for route alternatives and triggers request based on two internal conditions:
- Passing a fork point with an existing alternative route - the existing alternative becomes invalid and the Navigation SDK requests new alternative routes.
- There are no tracked alternative routes - the Navigation SDK requests alternatives with the interval
RouteAlternativesOptions.intervalMillis
until it gets successful response with valid alternatives, default interval is 5 minutes.
New routes will be delivered via NavigationRouteAlternativesObserver
.
NavigationRouteAlternativesObserver
.