Navigation SDK for Android Reference (1.1.0)
All modules /  libnavigation-core / com.mapbox.navigation.core / MapboxNavigation

MapboxNavigation

@UiThread 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 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 a couple of internal states:

The SDK starts off in an Idle state.

Location

Whenever the startTripSession is called, the SDK will enter the Free Drive 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 Free Drive 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 OnboardRouterOptions 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 the request is successful and returns a non-empty list of routes in the RoutesObserver, the first route at index 0 is going to be chosen as a primary one.

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 Free Drive mode or entering it whenever a primary route is available, the SDK will enter the Active Guidance mode instead and propagate meaningful RouteProgress.

If a new routes request is made, or the routes are manually cleared, the SDK automatically fall back to either Idle or Free Drive state.

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

Parameters

navigationOptions - a set of NavigationOptions used to customize various features of the SDK. Use defaultNavigationOptionsBuilder to set default options

Constructors

<init>

Mapbox Navigation Core SDK

MapboxNavigation(navigationOptions: NavigationOptions)

Properties

navigationOptions

a set of NavigationOptions used to customize various features of the SDK. Use defaultNavigationOptionsBuilder to set default options

val navigationOptions: NavigationOptions

Functions

addHistoryEvent

API used to artificially add debug events to logs.

fun addHistoryEvent(eventType: String, eventJsonProperties: String): Unit

attachFasterRouteObserver

Start observing faster routes for a trip session via FasterRouteObserver

fun attachFasterRouteObserver(fasterRouteObserver: FasterRouteObserver): Unit

detachFasterRouteObserver

Stop observing the possibility of faster routes.

fun detachFasterRouteObserver(): Unit

getRerouteController

Get currently set RerouteController.

fun getRerouteController(): RerouteController?

getRoutes

Get a list of routes.

fun getRoutes(): List<DirectionsRoute>

getTripSessionState

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.

fun getTripSessionState(): TripSessionState

navigateNextRouteLeg

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.

fun navigateNextRouteLeg(): Boolean

onDestroy

Call this method whenever this instance of the MapboxNavigation is not going to be used anymore and should release all of its resources.

fun onDestroy(): Unit

postUserFeedback

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(), appMetadata: AppMetadata? = null): Unit

registerArrivalObserver

Registers ArrivalObserver. Monitor arrival at stops and destinations. For more control of arrival at stops, see setArrivalController.

fun registerArrivalObserver(arrivalObserver: ArrivalObserver): Unit

registerBannerInstructionsObserver

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.

fun registerBannerInstructionsObserver(bannerInstructionsObserver: BannerInstructionsObserver): Unit

registerLocationObserver

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

fun registerLocationObserver(locationObserver: LocationObserver): Unit

registerOffRouteObserver

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

fun registerOffRouteObserver(offRouteObserver: OffRouteObserver): Unit

registerRouteAlertsObserver

Registers an observer that gets notified whenever the route changes and provides the list of alerts on this new route, if there are any. The alerts returned here are equal to the ones available in RouteProgress.upcomingRouteAlerts, but they capture the whole route (not only what's ahead of us) and don't have the UpcomingRouteAlert.distanceToStart data.

fun registerRouteAlertsObserver(routeAlertsObserver: RouteAlertsObserver): Unit

registerRouteProgressObserver

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

fun registerRouteProgressObserver(routeProgressObserver: RouteProgressObserver): Unit

registerRoutesObserver

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

fun registerRoutesObserver(routesObserver: RoutesObserver): Unit

registerTripSessionStateObserver

Registers TripSessionStateObserver. Monitors the trip session's state.

fun registerTripSessionStateObserver(tripSessionStateObserver: TripSessionStateObserver): Unit

registerVoiceInstructionsObserver

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.

fun registerVoiceInstructionsObserver(voiceInstructionsObserver: VoiceInstructionsObserver): Unit

requestRoutes

Requests a route using the provided Router implementation. If the request succeeds and the SDK enters an Active Guidance state, meaningful RouteProgress updates will be available.

fun requestRoutes(routeOptions: RouteOptions, routesRequestCallback: RoutesRequestCallback? = null): Unit

retrieveHistory

API used to retrieve logged location and route progress samples for debug purposes.

fun retrieveHistory(): String

retrieveSsmlAnnouncementInstruction

API used to retrieve the SSML announcement for voice instructions.

fun retrieveSsmlAnnouncementInstruction(index: Int): String?

setArrivalController

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.

fun setArrivalController(arrivalController: ArrivalController? = AutoArrivalController()): Unit

setRerouteController

Set RerouteController that's automatically invoked when user is off-route.

fun setRerouteController(rerouteController: RerouteController? = defaultRerouteController): Unit

setRoutes

Set a list of routes.

fun setRoutes(routes: List<DirectionsRoute>): Unit

startTripSession

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

fun startTripSession(): Unit

stopTripSession

Stops listening for location updates and enters an Idle state.

fun stopTripSession(): Unit

toggleHistory

API used to enable/disable location and route progress samples logs for debug purposes.

fun toggleHistory(isEnabled: Boolean): Unit

unregisterArrivalObserver

Unregisters ArrivalObserver.

fun unregisterArrivalObserver(arrivalObserver: ArrivalObserver): Unit

unregisterBannerInstructionsObserver

Unregisters BannerInstructionsObserver.

fun unregisterBannerInstructionsObserver(bannerInstructionsObserver: BannerInstructionsObserver): Unit

unregisterLocationObserver

Unregisters LocationObserver.

fun unregisterLocationObserver(locationObserver: LocationObserver): Unit

unregisterOffRouteObserver

Unregisters OffRouteObserver.

fun unregisterOffRouteObserver(offRouteObserver: OffRouteObserver): Unit

unregisterRouteAlertsObserver

Unregisters the route alerts observer.

fun unregisterRouteAlertsObserver(routeAlertsObserver: RouteAlertsObserver): Unit

unregisterRouteProgressObserver

Unregisters RouteProgressObserver.

fun unregisterRouteProgressObserver(routeProgressObserver: RouteProgressObserver): Unit

unregisterRoutesObserver

Unregisters RoutesObserver.

fun unregisterRoutesObserver(routesObserver: RoutesObserver): Unit

unregisterTripSessionStateObserver

Unregisters TripSessionStateObserver.

fun unregisterTripSessionStateObserver(tripSessionStateObserver: TripSessionStateObserver): Unit

unregisterVoiceInstructionsObserver

Unregisters VoiceInstructionsObserver.

fun unregisterVoiceInstructionsObserver(voiceInstructionsObserver: VoiceInstructionsObserver): Unit

updateSensorEvent

Sends an event to improve navigation positioning. See SensorEventEmitter to register

fun updateSensorEvent(sensorEvent: SensorEvent): Unit

Companion Object Functions

defaultNavigationOptionsBuilder

Returns a pre-build set of NavigationOptions with smart defaults.

fun defaultNavigationOptionsBuilder(context: Context, accessToken: String?): Builder