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

# 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`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/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/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.lifecycle/-mapbox-navigation-app/) and pass the [`NavigationOptions`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-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)
            .accessToken("YOUR_ACCESS_TOKEN")
            // 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)
                  .accessToken("YOUR_ACCESS_TOKEN")
                  .attach(lifecycleOwner = this)
                  .build()
            }
        }
    }
}
```

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)
                .accessToken("YOUR_ACCESS_TOKEN")
                .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/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core/-mapbox-navigation/start-trip-session.html). You can also use `MapboxNavigationApp` to access `MapboxNavigation` synchronously anywhere in your application using the `current()` function.

```kotlin
MapboxNavigationApp.current()?.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 `LocationEngine` provided in the `NavigationOptions`. Read more about using default and custom location engines in the [Device location](https://docs.mapbox.com/android/navigation/v2/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
MapboxNavigationApp.current()?.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/v2/guides/pricing/).