> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/navigation/llms.txt)

# Initialize Navigation 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 three steps you need to complete to initialize the Navigation SDK and begin receiving data:

-   **Provide an `access token`**;
-   **Create a `MapboxNavigation` object**, which is the entry point for interacting with the SDK;
-   **Start a trip session**, which allows you to start consuming and processing data.

### Access token

Visit the [Access Token page](https://console.mapbox.com/account/access-tokens/) to access the access tokens affiliated with your account.

Add a `mapbox_access_token.xml` file to your project to the following location: `src/main/res/values/mapbox_access_token.xml` with the following contents:

```xml
<?xml version="1.0" encoding="utf-8"?>
    <resources xmlns:tools="http://schemas.android.com/tools">
    <string name="mapbox_access_token" translatable="false" tools:ignore="UnusedResources">MAPBOX_ACCESS_TOKEN</string>
</resources>
```

You can also set the token via:

```kotlin
MapboxOptions.accessToken = MAPBOX_ACCESS_TOKEN
```

and change it in runtime. First, the token from `MapboxOptions` will be used. If it's not set, it will be read from resources.

### Create the `MapboxNavigation` object

The [`MapboxNavigation`](https://docs.mapbox.com/android/navigation/api/coreframework/3.30.0-rc.1/navigation/com.mapbox.navigation.core/-mapbox-navigation/) object is the primary entity of the Navigation SDK and the producer of the majority of the data needed in a navigation application.

> **Note: 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 [`MapboxNavigationApp`](https://docs.mapbox.com/android/navigation/api/coreframework/3.30.0-rc.1/navigation/com.mapbox.navigation.core.lifecycle/-mapbox-navigation-app/) and pass the [`NavigationOptions`](https://docs.mapbox.com/android/navigation/api/coreframework/3.30.0-rc.1/base/com.mapbox.navigation.base.options/-navigation-options/). `MapboxNavigationApp` is essentially, a lifecycle reference counter. When an attached lifecycle is `CREATED`, `MapboxNavigationApp` will construct an instance of `MapboxNavigation` and notify all registered `MapboxNavigationObserver`.

### 1. Set up `MapboxNavigationApp`

You have many options for when or how to setup `MapboxNavigationApp`. The easiest solution is to add it to your `Application.onCreate`. The `NavigationOptionsProvider` will request `NavigationOptions` when an attached `LifecycleOwner` is at least `CREATED`.

```kotlin
if (!MapboxNavigationApp.isSetup()) {
    MapboxNavigationApp.setup {
        NavigationOptions.Builder(context)
            // additional options
            .build()
    }
}
```

### 2. Attach `LifecycleOwner`

`MapboxNavigationApp` will create `MapboxNavigation` when at least one attached `LifecycleOwner` is `CREATED`. This accepts any `LifecycleOwner`, like Activities or Fragments. It will also accept custom `LifecycleOwner`s if you need a custom experience. `MapboxNavigationObserver` will stay attached until both the car and app are destroyed, this makes for a seamless experience when your users change their Android Auto connection.

In this example, `MapboxNavigation` will be attached when `MyFragment` is `CREATED`.

```kotlin
class MyFragment : Fragment {
    override fun onCreateView() {
        if (!MapboxNavigationApp.isSetup()) {
            MapboxNavigationApp.setup {
                NavigationOptions.Builder(context).build()
            }
        }
        MapboxNavigationApp.attach(this)
    }
}
```

In this example, `MapboxNavigation` will be attached when the `MyActivity` is `RESUMED`.

```kotlin
class MyActivity : Activity {
  init {
    lifecycle.addObserver(object : DefaultLifecycleObserver {
      override fun onResume(owner: LifecycleOwner) {
        MapboxNavigationApp.attach(owner)
      }

      override fun onPause(owner: LifecycleOwner) {
        MapboxNavigationApp.detach(owner)
      }
    })
  }
  
  override fun onCreate() {
      if (!MapboxNavigationApp.isSetup()) {
          MapboxNavigationApp.setup {
              NavigationOptions.Builder(context).build()
          }
      }
  }
}
```

### 3. Registering `MapboxNavigationObserver`

Register the `MapboxNavigationObserver` inside `Lifecycle` callbacks, that will give `MapboxNavigationObserver` the ability to control a specific definition. Following this pattern will also avoid memory leaks. For each lifecycle state, there is a corresponding destruction event that you can use to unregister the `MapboxNavigationObserver`.

> **Note: Registering to the Application**
> 
> When registering observers to the Application, you do not unregister the observer. The `MapboxNavigationApp` will call `MapboxNavigationObserver.onDetached` when the Application is stopped. The Android system will destroy the application process and reclaim resources used by the `MapboxNavigationObserver`. You can control when the `MapboxNavigationObserver` is attached with `MapboxNavigationApp.attach(lifecycleOwner = *)`.

| MapboxNavigationApp.registerObserver | MapboxNavigationApp.unregisterObserver |
| --- | --- |
| `Application.onCreate` | unregister is optional |
| `onCreate` | `onDestroy` |
| `onStart` | `onStop` |
| `onResume` | `onPause` |

`MapboxNavigationObserver` can be registered when the resources are available.

```kotlin
class MyApplication : Application() {
    init {
        // The application context can be found in onAttached through
        // mapboxNavigation.navigationOptions.applicationContext
        MapboxNavigationApp.registerObserver(MyObserver())
    }

    override fun onCreate() {
        super.onCreate()

        // Or you can pass the applicationContext directly after the application is created 
        val observer = MyObserverWithContext(applicationContext)
        MapboxNavigationApp.registerObserver(observer)
    }
}
```

In this example, `MapboxNavigation` will be attached when the `LifecycleOwner` is `RESUMED`.

```kotlin
private val myObserver = MyMapboxNavigationObserver()

lifecycle.addObserver(object : DefaultLifecycleObserver {
    override fun onResume(owner: LifecycleOwner) {
        MapboxNavigationApp.registerObserver(myObserver)
    }

    override fun onPause(owner: LifecycleOwner) {
        MapboxNavigationApp.unregisterObserver(myObserver)
    }
})
```

### 4. Implement `MapboxNavigationObserver`

The `MapboxNavigationObserver` is a lifecycle aware object. You can control when the `onAttached` / `onDetached` calls will be triggered with `MapboxNavigationApp.setup`, `MapboxNavigationApp.attach(lifecycleOwner)`, and `MapboxNavigationApp.register(mapboxNavigationObserver)`. The `MapboxNavigationObserver` implementation handles declaring what it will do while it is attached. For example, the observer below will register onto the location observer.

```kotlin
class MyMapboxNavigationObserver : MapboxNavigationObserver {
    private val locationObserver = MyLocationObserver()
    val location: Flow<Location> = locationObserver.location()

    override fun onAttached(mapboxNavigation: MapboxNavigation) {
        mapboxNavigation.registerLocationObserver(locationObserver)
    }
    
    override fun onDetached(mapboxNavigation: MapboxNavigation) {
        mapboxNavigation.unregisterLocationObserver(locationObserver)
    }
}
```

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()`](https://docs.mapbox.com/android/navigation/api/coreframework/3.30.0-rc.1/navigation/com.mapbox.navigation.core/-mapbox-navigation/start-trip-session.html).

You can use `MapboxNavigationApp` to access `MapboxNavigation` synchronously anywhere in your application using the `current()` function.

```kotlin
// when lifecycle state of any attached components is at least CREATED `current()` will return non-null instance.
val mapboxNavigation = MapboxNavigationApp.current()
mapboxNavigation?.startTripSession()
```

Also you can use a `LifecycleOwner` extension.

```kotlin
val mapboxNavigation by requireMapboxNavigation()
// when lifecycle state is at least CREATED
mapboxNavigation.startTripSession()
```

> **Note: Location permissions**
> 
> Starting a trip session requires user location permissions. Read more about how to request the permissions in [the Android developer documentation](https://developer.android.com/training/location/permissions#request-location-access-runtime).

When you start a session, the `MapboxNavigation` object will:

1.  Request raw location updates from the `LocationProvider` passed in `NavigationOptions#locationOptions`. Read more about using default and custom location providers in the [Device location](https://docs.mapbox.com/android/navigation/guides/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:

```kotlin
mapboxNavigation.stopTripSession()
```

> **Note (pricing): Pricing and trip sessions**
> 
> To learn more about how sessions impact your usage costs, (for example: how a session lifecycle is measured or how sessions are counted), see our [Pricing documentation](https://docs.mapbox.com/android/navigation/guides/pricing/).