MapboxNavigation

class 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:

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.

See also

Parameters

navigationOptions

a set of NavigationOptions used to customize various features of the SDK.

historyRecorder

Use the history recorder to save history files.

Functions

Link copied to clipboard
fun cancelMapMatchingRequest(requestId: Long)

Cancels a specific map matching request using the ID returned by requestMapMatching.

Link copied to clipboard
fun cancelRouteRequest(requestId: Long)

Cancels a specific route request using the ID returned by requestRoutes.

Link copied to clipboard
fun changeRoutesPreviewPrimaryRoute(newPrimaryRoute: NavigationRoute)

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.

Link copied to clipboard
fun currentLegIndex(): Int

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.

Link copied to clipboard
fun getAlternativeMetadataFor(navigationRoute: NavigationRoute): AlternativeRouteMetadata?

If the provided navigationRoute is an alternative route in the current session, this function will return the associated route metadata.

fun getAlternativeMetadataFor(navigationRoutes: List<NavigationRoute>): List<AlternativeRouteMetadata>

If the provided navigationRoutes are alternative routes in the current session, this function will return the associated with those route metadata.

Link copied to clipboard
fun getNavigationRoutes(): List<NavigationRoute>

Get a list of routes.

Link copied to clipboard
fun getNavigationSessionState(): NavigationSessionState

Provides the current navigation session state.

Link copied to clipboard
fun getRerouteController(): RerouteController?

Get currently used RerouteController. Null if isRerouteEnabled is false.

Link copied to clipboard
fun getRoutesPreview(): RoutesPreview?

Returns current state of routes preview

Link copied to clipboard
fun getTripSessionState(): TripSessionState

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.

Link copied to clipboard
fun getZLevel(): Int?

Provides the current Z-Level. Can be used to build a route from a proper level of a road.

Link copied to clipboard
fun isReplayEnabled(): Boolean

True when startReplayTripSession has been called. Will be false after stopTripSession is called.

Link copied to clipboard
fun isRerouteEnabled(): Boolean

Whether rerouting is enabled. True by default. It can be disabled by invoking setRerouteEnabled with false as a parameter.

Link copied to clipboard
fun isRunningForegroundService(): Boolean

Query if the MapboxNavigation is running a foreground service

Link copied to clipboard
fun moveRoutesFromPreviewToNavigator()

Convenience method that takes previewed routes and sets them to Navigator, clearing the previewed routes afterwards. Equivalent to:

Link copied to clipboard
fun navigateNextRouteLeg(callback: LegIndexUpdatedCallback)

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.

Link copied to clipboard
fun onEVDataUpdated(data: Map<String, String>)

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.

Link copied to clipboard
fun postUserFeedback(userFeedback: UserFeedback)

Send user feedback about an issue or problem with the Navigation SDK.

fun postUserFeedback(    feedbackType: String,     description: String,     feedbackSource: String,     screenshot: String,     feedbackSubType: Array<String>? = emptyArray())
fun postUserFeedback(    feedbackType: String,     description: String,     feedbackSource: String,     screenshot: String,     feedbackSubType: Array<String>? = emptyArray(),     feedbackMetadata: FeedbackMetadata)

This function is deprecated, use postUserFeedback(UserFeedback) instead.

Link copied to clipboard

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.

Link copied to clipboard
fun registerArrivalObserver(arrivalObserver: ArrivalObserver)

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.

Link copied to clipboard
fun registerBannerInstructionsObserver(bannerInstructionsObserver: BannerInstructionsObserver)

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.

Link copied to clipboard
fun registerDeveloperMetadataObserver(developerMetadataObserver: DeveloperMetadataObserver)

Registers a DeveloperMetadataObserver to be notified of DeveloperMetadata changes.

Link copied to clipboard
fun registerEHorizonObserver(eHorizonObserver: EHorizonObserver)

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

Link copied to clipboard
fun registerLocationObserver(locationObserver: LocationObserver)

Registers LocationObserver. The updates are available whenever the trip session is started.

Link copied to clipboard
fun registerNavigationSessionStateObserver(navigationSessionStateObserver: NavigationSessionStateObserver)

Register a NavigationSessionStateObserver to be notified of the various Session states.

Link copied to clipboard

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.

Link copied to clipboard
fun registerOffRouteObserver(offRouteObserver: OffRouteObserver)

Registers OffRouteObserver. The updates are available whenever SDK is in an Active Guidance state and detects an off route event.

Link copied to clipboard
fun registerRouteProgressObserver(routeProgressObserver: RouteProgressObserver)

Registers RouteProgressObserver. The updates are available whenever the trip session is started and a primary route is available.

Link copied to clipboard
fun registerRoutesInvalidatedObserver(observer: RoutesInvalidatedObserver)

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.

Link copied to clipboard
fun registerRoutesObserver(routesObserver: RoutesObserver)

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'.

Link copied to clipboard
fun registerRoutesPreviewObserver(observer: RoutesPreviewObserver)

Registers RoutesPreviewObserver to be notified when routes preview state changes. observer is immediately called with current preview state

Link copied to clipboard
fun registerTripSessionStateObserver(tripSessionStateObserver: TripSessionStateObserver)

Registers TripSessionStateObserver. Monitors the trip session's state.

Link copied to clipboard
fun registerVoiceInstructionsObserver(voiceInstructionsObserver: VoiceInstructionsObserver)

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.

Link copied to clipboard
fun replanRoute()

Triggers route recalculation for the case when user wants to change route options during active guidance.

Link copied to clipboard
fun requestMapMatching(mapMatchingOptions: MapMatchingOptions, callback: MapMatchingAPICallback): Long

Requests routes from Mapbox Map Matching API and transforms result to NavigationRoutes that could be used for setNavigationRoutes.

Link copied to clipboard
fun requestRoadGraphDataUpdate(callback: RoadGraphDataUpdateCallback)

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:

Link copied to clipboard
fun requestRoutes(routeOptions: RouteOptions, callback: NavigationRouterCallback): Long

Requests a route.

Link copied to clipboard
fun resetTripSession(callback: TripSessionResetCallback)

Reset the session with the same configuration. The location becomes unknown, but the NavigationOptions stay the same.

Link copied to clipboard
fun setArrivalController(arrivalController: ArrivalController? = AutoArrivalController())

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.

Link copied to clipboard
fun setContinuousAlternativesEnabled(enabled: Boolean)

Enables/disabled continuous alternatives automatic update. Enabled by default. When enabled, MapboxNavigation automatically:

Link copied to clipboard
fun setNavigationRoutes(    routes: List<NavigationRoute>,     initialLegIndex: Int = 0,     callback: RoutesSetCallback? = null)

Set a list of routes.

Link copied to clipboard
fun setRerouteEnabled(enabled: Boolean)

Enables/disables rerouting.

Link copied to clipboard
fun setRerouteOptionsAdapter(rerouteOptionsAdapter: RerouteOptionsAdapter?)

Set RerouteOptionsAdapter. It allows modify RouteOptions of default implementation of RerouteController.

Link copied to clipboard
fun setRoutesPreview(routes: List<NavigationRoute>, primaryRouteIndex: Int = 0)

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.

Link copied to clipboard
fun setTripNotificationInterceptor(interceptor: TripNotificationInterceptor?)

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.

Link copied to clipboard
fun startReplayTripSession(withForegroundService: Boolean = true)

Functionally the same as startTripSession except the locations do not come from the NavigationOptions.mockLocationProvider. The events are emitted by the mapboxReplayer.

Link copied to clipboard
@RequiresPermission(anyOf = ["android.permission.ACCESS_COARSE_LOCATION", "android.permission.ACCESS_FINE_LOCATION"])
fun startTripSession(withForegroundService: Boolean = true)

Starts listening for location updates and enters an Active Guidance state if there's a primary route available or a Free Drive state otherwise.

Link copied to clipboard
fun stopTripSession()

Stops listening for location updates and enters an Idle state.

Link copied to clipboard
fun unregisterArrivalObserver(arrivalObserver: ArrivalObserver)

Unregisters ArrivalObserver.

Link copied to clipboard
fun unregisterBannerInstructionsObserver(bannerInstructionsObserver: BannerInstructionsObserver)
Link copied to clipboard
fun unregisterDeveloperMetadataObserver(developerMetadataObserver: DeveloperMetadataObserver)
Link copied to clipboard
fun unregisterEHorizonObserver(eHorizonObserver: EHorizonObserver)

Unregisters a EHorizon observer.

Link copied to clipboard
fun unregisterLocationObserver(locationObserver: LocationObserver)

Unregisters LocationObserver.

Link copied to clipboard
fun unregisterNavigationSessionStateObserver(navigationSessionStateObserver: 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.

Link copied to clipboard
fun unregisterOffRouteObserver(offRouteObserver: OffRouteObserver)

Unregisters OffRouteObserver.

Link copied to clipboard
fun unregisterRouteProgressObserver(routeProgressObserver: RouteProgressObserver)
Link copied to clipboard
Link copied to clipboard
fun unregisterRoutesObserver(routesObserver: RoutesObserver)

Unregisters RoutesObserver.

Link copied to clipboard
fun unregisterRoutesPreviewObserver(observer: RoutesPreviewObserver)

Unregisters observer which were registered using registerRoutesPreviewObserver

Link copied to clipboard
fun unregisterTripSessionStateObserver(tripSessionStateObserver: TripSessionStateObserver)
Link copied to clipboard
fun unregisterVoiceInstructionsObserver(voiceInstructionsObserver: VoiceInstructionsObserver)

Properties

Link copied to clipboard
val etcGateAPI: EtcGateApi

Use this property to provide ETC gate update info.

Link copied to clipboard
val experimental: Experimental

THIS IS AN EXPERIMENTAL API, DO NOT USE IN A PRODUCTION ENVIRONMENT.

Link copied to clipboard
val graphAccessor: GraphAccessor

MapboxNavigation.graphAccessor provides methods to get edge (e.g. EHorizonEdge) shape and metadata.

Link copied to clipboard
val historyRecorder: MapboxHistoryRecorder
Link copied to clipboard
val isDestroyed: Boolean = false

Describes whether this instance of MapboxNavigation has been destroyed by calling onDestroy. Once an instance is destroyed, it cannot be used anymore.

Link copied to clipboard
val mapboxReplayer: MapboxReplayer

Control the location events playback during a replay trip session. Start a replay trip session with startReplayTripSession.

Link copied to clipboard
val navigationOptions: NavigationOptions
Link copied to clipboard
val roadObjectMatcher: RoadObjectMatcher

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

Link copied to clipboard
val roadObjectsStore: RoadObjectsStore

MapboxNavigation.roadObjectsStore provides methods to get road objects metadata, add and remove custom road objects.

Link copied to clipboard
val routeRefreshController: RouteRefreshController

Use route refresh controller to handle route refreshes.

Link copied to clipboard
val tilesetDescriptorFactory: TilesetDescriptorFactory

MapboxNavigation.tilesetDescriptorFactory provide methods to build navigation TilesetDescriptor