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 setNavigationRoutes.
setNavigationRoutes 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 setNavigationRoutes 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: String
) {
mapboxNavigation.setNavigationRoutes(routes)
}
override fun onFailure(reasons: List<RouterFailure>, routeOptions: RouteOptions) { }
override fun onCanceled(routeOptions: RouteOptions, @RouterOrigin routerOrigin: String) { }
}
)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 setNavigationRoutes 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.
Use the history recorder to save history files.
See also
to enable and customize the directory
to read the files
Properties
Use this property to provide ETC gate update info.
THIS IS AN EXPERIMENTAL API, DO NOT USE IN A PRODUCTION ENVIRONMENT.
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.
Use route refresh controller to handle route refreshes.
MapboxNavigation.tilesetDescriptorFactory provide methods to build navigation TilesetDescriptor
Functions
Cancels a specific map matching request using the ID returned by requestMapMatching.
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.
Returns leg index the user is currently on. If no RouteProgress updates are available, returns the value passed as initialLegIndex parameter to setNavigationRoutes. If no routes are set, returns 0.
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 used RerouteController. Null if isRerouteEnabled is false.
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.
True when startReplayTripSession has been called. Will be false after stopTripSession is called.
Whether rerouting is enabled. True by default. It can be disabled by invoking setRerouteEnabled with false as a parameter.
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.
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.
This function is deprecated, use postUserFeedback(UserFeedback) instead.
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 RouteProgressObserver. The updates are available whenever the trip session is started and a primary route is available.
Registers RoutesInvalidatedObserver. Use this method to keep track of routes that become invalidated, which means they won't be refreshed anymore. It is recommended to rebuild the route when you receive a notification of it being invalidated.
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.
Triggers route recalculation for the case when user wants to change route options during active guidance.
Requests routes from Mapbox Map Matching API and transforms result to NavigationRoutes that could be used for setNavigationRoutes.
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.
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.
Enables/disabled continuous alternatives automatic update. Enabled by default. When enabled, MapboxNavigation automatically:
Set a list of routes.
Enables/disables rerouting.
Set RerouteOptionsAdapter. It allows modify RouteOptions of default implementation of 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.mockLocationProvider. The events are emitted by the mapboxReplayer.
Functionally the same as startReplayTripSession but throws IllegalStateException if the application doesn't have permissions to start foreground service with location type.
Starts listening for location updates and enters an Active Guidance state if there's a primary route available or a Free Drive state otherwise.
Functionally the same as startTripSession but throws IllegalStateException if the application doesn't have permissions to start foreground service with location type.
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 RouteProgressObserver.
Unregisters RoutesInvalidatedObserver.
Unregisters RoutesObserver.
Unregisters observer which were registered using registerRoutesPreviewObserver
Unregisters TripSessionStateObserver.
Unregisters VoiceInstructionsObserver.