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 MapboxNavigationApp 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:
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 : NavigationRouterCallback {
override fun onRoutesReady(
routes: List<NavigationRoute>,
routerOrigin: RouterOrigin
) {
mapboxNavigation.setNavigationRoutes(routes)
}
override fun onFailure(reasons: List<RouterFailure>, routeOptions: RouteOptions) { }
override fun onCanceled(routeOptions: RouteOptions, routerOrigin: RouterOrigin) { }
}
)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.
Parameters
a set of NavigationOptions used to customize various features of the SDK.
Constructors
Functions
Cancels a specific route request using the ID returned by requestRoutes.
Changes primary route for current preview state without changing order of RoutesPreview.originalRoutesList. Order is important for a case when routes are displayed as a list on UI, the list shouldn't change order when a user choose different primary route.
If the provided navigationRoute is an alternative route in the current session, this function will return the associated route metadata.
If the provided navigationRoutes are alternative routes in the current session, this function will return the associated with those route metadata.
Get a list of routes.
Provides the current navigation session state.
Get currently set RerouteController.
Returns current state of routes preview
Return the current TripSession's state. The state is TripSessionState.STARTED when the session is active, running a foreground service and requesting and returning location updates. The state is TripSessionState.STOPPED when the session is inactive.
Query if the MapboxNavigation is running a foreground service
Convenience method that takes previewed routes and sets them to Navigator, clearing the previewed routes afterwards. Equivalent to:
After arriving at a stop, this can be used to manually decide when to start navigating to the next stop. Use the ArrivalController to control when to call navigateNextRouteLeg.
Call this method whenever this instance of the MapboxNavigation is not going to be used anymore and should release all of its resources.
Invoke when any component of EV data is changed so that it can be used in refresh requests. You can pass only changed components of EV data via data, all the previous values that have not changed will be cached on the SDK side. NOTE: Only provide parameters that are compatible with an EV route refresh. If you pass any other parameters via this method, the route refresh request will fail.
Send user feedback about an issue or problem with the Navigation SDK.
Provides wrapper of FeedbackMetadata. FeedbackMetadata is used to send deferred feedback attached to passed location. It contains data (like location, time) when method is invoked.
Registers ArrivalObserver. Monitor arrival at stops and destinations. For more control of arrival at stops, see setArrivalController. Use RouteProgressObserver to create custom experiences for arrival based on time or distance.
Registers BannerInstructionsObserver. The updates are available whenever SDK is in an Active Guidance state. The SDK will push this event only once per route step.
Registers a DeveloperMetadataObserver to be notified of DeveloperMetadata changes.
To start listening EHorizon updates EHorizonObserver should be registered. Observer will be called when the EHorizon changes. To save resources and be more efficient callbacks return minimum data. To get EHorizonEdge shape or EHorizonEdgeMetadata use MapboxNavigation.graphAccessor To get more data about EHorizon road object use MapboxNavigation.roadObjectsStore
Registers LocationObserver. The updates are available whenever the trip session is started.
Register a NavigationSessionStateObserver to be notified of the various Session states.
Start observing navigation tiles version switch via NavigationVersionSwitchObserver. Navigation might switch to a fallback tiles version when target tiles are not available and return back to the target version when tiles are loaded.
Registers OffRouteObserver. The updates are available whenever SDK is in an Active Guidance state and detects an off route event.
Registers an observer that gets notified whenever the route changes and provides the list of road objects on this new route, if there are any. The objects returned here are equal to the ones available in RouteProgress.upcomingRoadObjects, but they capture the whole route (not only what's ahead of us).
Start observing alternatives routes for a trip session via NavigationRouteAlternativesObserver. Route alternatives are requested periodically based on RouteAlternativesOptions.
Start observing alternatives routes for a trip session via RouteAlternativesObserver. Route alternatives are requested periodically based on RouteAlternativesOptions.
Registers RouteProgressObserver. The updates are available whenever the trip session is started and a primary route is available.
Register a RouteRefreshStatesObserver to be notified of Route refresh state changes.
Registers RoutesObserver. The updates are available when a new list of routes is set. The route at index 0, if exist, will be treated as the primary route for 'Active Guidance'.
Registers RoutesPreviewObserver to be notified when routes preview state changes. observer is immediately called with current preview state
Registers TripSessionStateObserver. Monitors the trip session's state.
Registers VoiceInstructionsObserver. The updates are available whenever SDK is in an Active Guidance state. The SDK will push this event only once per route step.
Requests an alternative route using the original RouteOptions associated with MapboxNavigation.setRoutes() call and Router implementation.
Requests road graph data update and invokes the callback on result. Use this method if the frequency of application relaunch is too low to always get the latest road graph data. Recreate MapboxNavigation instance in the callback when updates are available:
Requests a route using the available NavigationRouter implementation.
Requests a route using the available Router implementation.
Reset the session with the same configuration. The location becomes unknown, but the NavigationOptions stay the same.
Set your own controller to determine when drivers arrived at stops via ArrivalController. Use navigateNextRouteLeg to manually move navigator to the next stop. To reset to the automatic arrival controller, call setArrivalController.
Set a list of routes.
Set NavigationRerouteController that's automatically invoked when user is off-route.
Set RerouteController that's automatically invoked when user is off-route.
Set RerouteOptionsAdapter. It allows modify RouteOptions of default implementation of NavigationRerouteController (RerouteController).
Sets routes to preview. Triggers an update in RoutesPreviewObserver and changes MapboxNavigation.getRoutesPreview. Preview state is updated asynchronously as it requires the SDK to process routes and compute alternative metadata. Subscribe for updates using MapboxNavigation.registerRoutesPreviewObserver to receive new routes preview state when the processing will be completed.
Allows you to intercept the notification builder before it is passed to the android sdk. Use this interceptor to extend the notification, or apply your own modifications. Use null to clear the interceptor you have set previously.
Functionally the same as startTripSession except the locations do not come from the NavigationOptions.locationEngine. The events are emitted by the mapboxReplayer.
Starts listening for location updates and enters an Active Guidance state if there's a primary route available or a Free Drive state otherwise.
Stops listening for location updates and enters an Idle state.
Unregisters ArrivalObserver.
Unregisters BannerInstructionsObserver.
Unregisters a DeveloperMetadataObserver.
Unregisters a EHorizon observer.
Unregisters LocationObserver.
Unregisters a NavigationSessionStateObserver.
Stop observing tiles version switch via NavigationVersionSwitchObserver. Navigation might switch to a fallback tiles version when target tiles are not available and return back to the target version when tiles are loaded.
Unregisters OffRouteObserver.
Unregisters the route objects observer.
Stop observing the possibility of route alternatives.
Unregisters RouteProgressObserver.
Unregisters a RouteRefreshStatesObserver.
Unregisters RoutesObserver.
Unregisters observer which were registered using registerRoutesPreviewObserver
Unregisters TripSessionStateObserver.
Unregisters VoiceInstructionsObserver.
Properties
MapboxNavigation.graphAccessor provides methods to get edge (e.g. EHorizonEdge) shape and metadata.
Describes whether this instance of MapboxNavigation has been destroyed by calling onDestroy. Once an instance is destroyed, it cannot be used anymore.
Control the location events playback during a replay trip session. Start a replay trip session with startReplayTripSession.
MapboxNavigation.roadObjectMatcher provides methods to match custom road objects to the road graph. To make the road object discoverable by the electronic horizon module and the EHorizonObserver in particular it must be added to the RoadObjectsStore with RoadObjectsStore.addCustomRoadObject
MapboxNavigation.roadObjectsStore provides methods to get road objects metadata, add and remove custom road objects.
MapboxNavigation.tilesetDescriptorFactory provide methods to build navigation TilesetDescriptor