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

# Get started

Review the [Google developer documentation](https://developer.android.com/training/cars/apps) to learn how to develop apps for Android Auto. You should also review the [functionality checklist](https://developer.android.com/docs/quality-guidelines/car-app-quality#functionality) to make sure your app meets the Google Play requirements. This guide will help you add Mapbox Navigation to a new or existing app. It will also refer you to other documentation when necessary. If you are looking to use Mapbox Maps in Android Auto without Mapbox Navigation, refer to the [Mapbox Android Auto Extension](https://github.com/mapbox/mapbox-maps-android/tree/main/extension-androidauto).

[This library is open source](https://github.com/mapbox/mapbox-navigation-android/tree/main/androidauto)! Feel free to [request changes](https://github.com/mapbox/mapbox-navigation-android/issues/new), or open pull requests.

### 1. Set up `MAPBOX_DOWNLOADS_TOKEN`

Refer to the Mapbox Navigation SDK [install guide](https://docs.mapbox.com/android/ja/navigation/v2/guides/get-started/install/) to get permission to download SDKs. If you have already set up a `MAPBOX_DOWNLOADS_TOKEN`, you can skip this step.

### 2. Make sure `minSdk` 23+

Android Auto is only compatible with phones running Android 6.0 (API level 23) or higher.

```kotlin
android {
  defaultConfig {
    minSdk 23
    ...
  }
```

### 3. Add the dependency

Add the library dependency to your build.gradle. The library brings the minimum versions of the dependencies. For this reason you should plan to upgrade [Mapbox Navigation library](https://docs.mapbox.com/android/ja/navigation/v2/guides/get-started/choose-an-approach/) and the [`Jetpack` car library](https://developer.android.com/jetpack/androidx/releases/car-app). Review the Mapbox Dependencies for the version you choose. `ui-androidauto` releases include the `androidauto-v*` prefix. [https://github.com/mapbox/mapbox-navigation-android/releases](https://github.com/mapbox/mapbox-navigation-android/releases)

```kotlin
dependencies {
  implementation "com.mapbox.navigation:ui-androidauto:0.23.0"
  
  // Optional upgrades
  implementation "com.mapbox.navigation:ui-dropin:2.20.0-beta.1"
  implementation "androidx.car.app:app:1.+"
}
```

### 4. Add your `meta-data` and `CarAppService`

You need to add elements to the `application` in your `AndroidManifest.xml`. The `meta-data` specifies support for [Android Auto](https://developer.android.com/training/cars/apps/auto#declare-android-auto-support) or [Android Automotive](https://developer.android.com/training/cars/apps/automotive-os#manifest-car-app). You do not need to add the `automotive_app_desc` because it is included by the Mapbox Navigation Android Auto SDK. The `CarAppService` has an `intent-filter` to specify the `category` of your app. If you specify the wrong `meta-data` or `category`, your app will be rejected by Google Play.

```xml
{/* Add if your app supports Android Auto */}
<meta-data
    android:name="com.google.android.gms.car.application"
    android:resource="@xml/automotive_app_desc" />

{/* Add if your app supports Android Automotive */}
<meta-data
    android:name="com.android.automotive"
    android:resource="@xml/automotive_app_desc" />

<service
    android:name=".car.MainCarAppService"
    android:exported="true"
    android:label="@string/app_name"
    android:icon="@mipmap/ic_launcher"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:foregroundServiceType="location">

    <intent-filter>
        <action android:name="androidx.car.app.CarAppService" />
        <category android:name="androidx.car.app.category.NAVIGATION" />
    </intent-filter>

</service>
```

```kotlin
class MainCarAppService : CarAppService() {
    override fun createHostValidator() = HostValidator.ALLOW_ALL_HOSTS_VALIDATOR

    override fun onCreateSession() = MainCarSession()
}
```

### 5. Managing state between the car and app

When integrating Android Auto with your application, an issue you are likely to face, is determining when the car or app is in use. Luckily, the car and app have something in common, [The `Jetpack` Lifecycle Library](https://developer.android.com/topic/libraries/architecture/lifecycle). To create `Lifecycle` aware services, we have introduced [`MapboxNavigationApp`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core.lifecycle/-mapbox-navigation-app/). This is built on top of the `Lifecycle`. It is recommended to set up `MapboxNavigation` as explained in [Initialize the SDK](https://docs.mapbox.com/android/ja/navigation/v2/guides/get-started/initialization/#1-set-up-mapboxnavigationapp) guide before following the steps outlined below. Also, refer to [Android Auto `Lifecycle` documentation](https://developer.android.com/training/cars/apps#carappservice-session-screen-lifecycles) for questions about Session and Screen `Lifecycle`.

### 6. Implement your `Session`

The `Session` is a `LifecycleOwner` and serves as the entry point for Android Auto. This is where you can create experiences that fit your domain and complete the [functionality checklist](https://developer.android.com/docs/quality-guidelines/car-app-quality#functionality).

-   Set up the [`MapboxCarMap`](https://github.com/mapbox/mapbox-maps-android/tree/main/extension-androidauto)
-   Set up `MapboxNavigationApp`
-   Prepare the `MapboxScreenManager`
-   Create an experience for accepting location permissions
-   Update the Map style when the configuration changes
-   Parse `onNewIntent` for voice activated navigation

The following are working examples. Use them as a guide to create your own experiences.

-   Latest API changes [are being tested here](https://github.com/mapbox/mapbox-navigation-android/blob/main/androidauto)
-   An example of [Android Auto integrated with an app is here](https://github.com/mapbox/mapbox-navigation-android-examples/blob/main/android-auto-app)
-   An example of [Android Automotive is here](https://github.com/mapbox/mapbox-navigation-android-examples/tree/main/android-automotive-app)
-   Latest `MapboxCarMap` examples are part of the [Mapbox Android Auto Extension](https://github.com/mapbox/mapbox-maps-android/tree/main/extension-androidauto)

The following is an example of what your Session can look like.

```kotlin
class MainCarSession : Session() {

  // Create the MapboxCarContext and MapboxCarMap. You can use them to build
  // your own customizations.
  private val carMapLoader = MapboxCarMapLoader()
  private val mapboxCarMap = MapboxCarMap().registerObserver(carMapLoader)
  private val mapboxCarContext = MapboxCarContext(lifecycle, mapboxCarMap)

  init {
    // Attach the car lifecycle to MapboxNavigationApp.
    // You do not need to detach because it will interally detach when the lifecycle is detroyed.
    // But you will need to unregister any observer that was registered within the car lifecycle.
    MapboxNavigationApp.attach(lifecycleOwner = this)

    // Prepare a screen graph for the session. If you want to customize
    // any screens, use the MapboxScreenManager.
    mapboxCarContext.prepareScreens()

    // At any point you can customize the MapboxCarOptions available.
    mapboxCarContext.customize {
      // You need to tell the car notification which app to open when a
      // user taps it.
      notificationOptions = MapboxCarNotificationOptions.Builder()
          .startAppService(MainCarAppService::class.java)
          .build()
    }
        
    lifecycle.addObserver(object : DefaultLifecycleObserver {
      override fun onCreate(owner: LifecycleOwner) {
        // Ensure MapboxNavigationApp has an access token and a application context. 
        // This can also be done in Application.onCreate. Use the isSetup condition in case the
        // options have been set by a separate lifecycle event, like an Activity onCreate.
        if (!MapboxNavigationApp.isSetup()) {
          MapboxNavigationApp.setup(
            NavigationOptions.Builder(carContext)
                .accessToken(Utils.getMapboxAccessToken(carContext))
                .build()
            )
        }

        // Once a CarContext is available, pass it to the MapboxCarMap.
        mapboxCarMap.setup(carContext, MapboxInitOptions(context = carContext))
      }

      override fun onDestroy(owner: LifecycleOwner) {
        // The car session is destroyed you so should remove any observers. This
        // will ensure every MapboxCarMapObserver.onDetached is called.
        mapboxCarMap.clearObservers()
      }
    })
  }

  override fun onCreateScreen(intent: Intent): Screen {
    // You can control the MapboxScreenManager from a mobile device, in which case you will
    // want to get the first screen from there. Most of the MapboxScreens require location
    // permission and the default NEEDS_LOCATION_PERMISSION will assume location permissions
    // are requested from a mobile app.
    val firstScreenKey = if (PermissionsManager.areLocationPermissionsGranted(carContext)) {
      MapboxScreenManager.current()?.key ?: MapboxScreen.FREE_DRIVE
    } else {
      MapboxScreen.NEEDS_LOCATION_PERMISSION
    }

    // Use the MapboxScreenManager to keep track of the screen stack.
    return mapboxCarContext.mapboxScreenManager.createScreen(firstScreenKey)
  }

  override fun onCarConfigurationChanged(newConfiguration: Configuration) {
    // Notify a map loader of the dark mode style change
    carMapLoader.updateMapStyle(carContext.isDarkMode)
  }

  override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    
    // Use the GeoDeeplinkNavigateAction or GeoDeeplinkParser to parse
    // incomming intents and change the navigation screen
    GeoDeeplinkNavigateAction(mapboxCarContext).onNewIntent(intent)
  }
}
```

### 7. Customize your experience

To provide a default experience for Android Auto, we have prepared default [Screens](https://developer.android.com/reference/androidx/car/app/Screen) with default experiences. See the screenshot available in the following sections, that should give you an idea for what is included inside this library. You are free to use what is available. If you are unable to build your custom experience, [make requests](https://github.com/mapbox/mapbox-navigation-android/issues/new) so we can build an SDK that helps you build with Mapbox!