Initialize the SDK

Navigation applications require many types of data that are constantly updated to provide information to the user. To being accessing this data you need to initialize the Navigation SDK and start a trip session. Then, you can use this data to power two kinds of navigation experiences: passive navigation (also known as free-drive mode) or active guidance (or turn-by-turn navigation).

Initialize the Navigation SDK

There are two steps you need to complete to initialize the Navigation SDK and begin receiving data:

  • Create a MapboxNavigation object, which is the entry point for interacting with the Navigation SDK.
  • Start a trip session, which allows you to start consuming and processing data.

Create the MapboxNavigation object

The MapboxNavigation object is the primary entity of the Navigation SDK and the producer of the majority of the data needed in a navigation application.

MapboxNavigation instance

MapboxNavigation is a singleton-like object, there should only be one instance running per application process. This object can be safely used across different activities and fragments, or accessed from a ViewModel. The instance can also be safely destroyed and recreated if needed.

To create the object use the MapboxNavigationProvider and pass the NavigationOptions. The MapboxNavigationProvider ensures you will only have one MapboxNavigation instance in your application.

val navigationOptions = NavigationOptions.Builder(this)
    .accessToken("YOUR_ACCESS_TOKEN")
    .build()
val mapboxNavigation = MapboxNavigationProvider.create(navigationOptions)

You can also use MapboxNavigationProvider to access MapboxNavigation anywhere in your application using the retrieve() function.

fun registerObservers() {
    if (MapboxNavigationProvider.isCreated()) {
        MapboxNavigationProvider.retrieve().registerRouteProgressObserver(this)
    }
}

Whenever your navigation experience ends, you should destroy the instance:

fun onCleared() {
    MapboxNavigationProvider.destroy()
}

Once the MapboxNavigation object is initialized, the Navigation SDK starts in an internal idle state. There's no location data being consumed or processed and no updates are generated.

Start a trip session

To start consuming and processing data, you need to start a trip session using startTripSession():

mapboxNavigation.startTripSession()
Location permissions

Starting a trip session requires user location permissions. Read more about how to request the permissions in the Android developer documentation.

When you start a session, the MapboxNaivgation object will:

  1. Request raw location updates from the LocationEngine provided in the NavigationOptions. Read more about using default and custom location engines in the Device location guide.
  2. Process the incoming raw location updates and deliver various data observers updates with processed data.

When a trip session is running, there's also an Android foreground service running and displaying a notification so the Navigation SDK can keep receiving raw location updates, even if the app is minimized.

To shutdown the foreground location service and stop data processing, you need to stop a session by calling:

mapboxNavigation.stopTripSession()
Pricing and trip sessions

Learn what is a billable lifecycle of a session, how sessions are counted, and how does that impact your usage costs in the Pricing documentation.