MapboxNavigation

Mapbox Navigation Core SDK

An entry point for interacting with the Mapbox Navigation SDK.

Only one instance of this class should be used per application process. Use MapboxNavigationProvider to easily manage the instance across lifecycle.

Feel free to visit our docs pages and examples before diving in!

The MapboxNavigation implementation can enter into the following NavigationSessionStates:

• Idle

• FreeDrive

• ActiveGuidance

The SDK starts off in an Idle state.

Location

Whenever the startTripSession is called, the SDK will enter the FreeDrive state starting to request and propagate location updates via the LocationObserver.

This observer provides 2 location update values in mixed intervals - either the raw one received from the provided LocationEngine or the enhanced one map-matched internally using SDK's native capabilities.

In FreeDrive mode, the enhanced location is computed using nearby to user location's routing tiles that are continuously updating in the background. This can be configured using the RoutingTilesOptions in the NavigationOptions.

If the session is stopped, the SDK will stop listening for raw location updates and enter the Idle state.

Routing

A route can be requested with:

• requestRoutes, if successful, returns a route reference without acting on it. You can then pass the generated routes to setRoutes.

• setRoutes sets new routes, clear current ones, or changes the route at primary index 0. The routes are immediately available via the RoutesObserver and the first route (at index 0) is going to be chosen as the primary one.

Route reason update

When routes are updated via setRoutes the reason that is spread via RoutesObserver.onRoutesChanged might be:

• RoutesExtra.ROUTES_UPDATE_REASON_CLEAN_UP if list of routes is empty;

• RoutesExtra.ROUTES_UPDATE_REASON_ALTERNATIVE if any of the routes received via RouteAlternativesObserver.onRouteAlternatives are set. Order does not matter.

• RoutesExtra.ROUTES_UPDATE_REASON_NEW otherwise. If current routes are internally refreshed then the reason is RoutesExtra.ROUTES_UPDATE_REASON_REFRESH. In case of re-route (see RerouteController) the reason is RoutesExtra.ROUTES_UPDATE_REASON_REROUTE.

Make sure to use the applyDefaultNavigationOptions for the best navigation experience (and to set required request parameters). You can also use applyLanguageAndVoiceUnitOptions get instructions' language and voice unit based on the device's Locale. It's also worth exploring other available options (like enabling alternative routes, specifying destination approach type, defining waypoint types, etc.).

Example:

val routeOptions = RouteOptions.builder()
  .applyDefaultNavigationOptions()
  .applyLanguageAndVoiceUnitOptions(context)
  .accessToken(token)
  .coordinatesList(listOf(origin, destination))
  .alternatives(true)
  .build()
mapboxNavigation.requestRoutes(
    routeOptions,
    object : RouterCallback {
        override fun onRoutesReady(routes: List<DirectionsRoute>) {
            mapboxNavigation.setRoutes(routes)
        }
        override fun onFailure(reasons: List<RouterFailure>, routeOptions: RouteOptions) { }
        override fun onCanceled(routeOptions: RouteOptions) { }
    }
)

If the SDK is in an Idle state, it stays in this same state even when a primary route is available.

If the SDK is already in the FreeDrive mode or entering it whenever a primary route is available, the SDK will enter the ActiveGuidance mode instead and propagate meaningful RouteProgress.

When the routes are manually cleared, the SDK automatically fall back to either Idle or FreeDrive state.

You can use setRoutes to provide new routes, clear current ones, or change the route at primary index 0.