Get started

Please review the Google developer documentation to learn how to develop apps for Android Auto. You should also review the functionality checklist 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, please refer to the Mapbox Android Auto Extension.

This library is open source! Feel free to request changes, or open pull requests.

1. Set up MAPBOX_DOWNLOADS_TOKEN

Refer to the Mapbox Navigation SDK install guide 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.

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 and the Jetpack car library. 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

dependencies {
  implementation "com.mapbox.navigation:ui-androidauto:0.2.0"
  
  // Optional upgrades
  implementation "com.mapbox.navigation:ui-dropin:2.7.0-alpha.1"
  implementation "androidx.car.app:app:1.+"
}

4. Add your CarAppService

In your AndroidManifest.xml add your own CarAppService to the application. The snippet below shows the setup required to create your own CarAppService with a reference to your Session.

<application
...
  <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>
class MainCarAppService : CarAppService() {
    override fun createHostValidator() = HostValidator.ALLOW_ALL_HOSTS_VALIDATOR

    override fun onCreateSession() = MainCarSession()
}

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

  • Setup the MapboxCarMap
  • Setup MapboxNavigationApp
  • Create an experience for accepting location permissions
  • Update the Map style when the configuration changes
  • Parse onNewIntent for voice activated navigation
  • Setup a mechanism to manage screen
  • Setup the MapboxCarNavigationManager

There are a working examples, use them as a guide to create your own experiences.

Below is a high level guide to what your Session will need to include.

class MainCarSession : Session() {

  // Keep a local reference to MapboxCarMap. Do not hold the MapboxCarMap
  // beyond the lifecycle of the Session. This instance should be passed
  // to the active Screen so they can register/unregister observers.
  // The lateinit propeities will be constructed in onCreate because the
  // CarContext is not available until then.
  private lateinit var mapboxCarMap: MapboxCarMap
  private lateinit var screenManager: MainScreenManager
  private val carMapLoader = MainCarMapLoader()

  private val carLifecycle = object : DefaultLifecycleObserver {
    
    // Communicate the navigation state with Android Auto
    lateinit var carNavigationManager: MapboxCarNavigationManager

    override fun onCreate(owner: LifecycleOwner) {
      // Optional, setup MapboxNavigationApp. This can also be done in
      // Application.onCreate

      // This is the earliest this can be done, because the carContext
      // is available after the session is created.
      carNavigationManager = MapboxCarNavigationManager(carContext)
      MapboxNavigationApp.registerObserver(carNavigationManager)

      // Setup the mapbox map and load the map
      mapboxCarMap = MapboxCarMap(MapInitOptions(context = carContext))
      mapboxCarMap.registerObserver(carMapLoader)

      // Set up a screen manager to handle screen changes. This is also
      // a good place to handle location permissions
      val mainCarContext = MainCarContext(carContext, mapboxCarMap)
      screenManager = MainScreenManager(mainCarContext)
    }

    override fun onDestroy(owner: LifecycleOwner) {
      // Unregister everything that was registered in onCreate
      MapboxNavigationApp.unregisterObserver(carNavigationManager)
      mapboxCarMap.unregisterObserver(carMapLoader)
    }
  }

  init {
      lifecycle.addObserver(carLifecycle)
  }

  override fun onCarConfigurationChanged(newConfiguration: Configuration) {
    // Notify your 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
  }
}

6. Customize your experience

To provide a default experience for Android Auto, we have prepared default Screens 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, please make requests so we can build an SDK that helps you build with Mapbox!