Add Android Automotive OS support to your media app

Android Automotive OS allows users to install apps in the car. In order to reach users on this platform, you need to distribute a driver-optimized app that is compatible with Android Automotive OS. You can re-use almost all of the code and resources in your Android Auto app, but you must create a separate build that meets the requirements on this page.

Development overview

Adding Android Automotive OS support is simple and only requires a few steps:

  1. Enable automotive features in Android Studio
  2. Create an automotive module
  3. Update your gradle dependencies
  4. Add settings or sign-in activities (Optional)

Design considerations

Android Automotive OS takes care of laying out the media content that it receives from your app's media browser service. This means that your app doesn't draw the UI and your app does not start any of your activities when a user triggers media playback.

If you are implementing Settings or Sign-in activities, these activities must be vehicle-optimized. You should refer to the Design guidelines for Android Automotive OS while designing those areas of your app.

Set up your project

You need to set up several different parts of your app's project to enable support for Android Automotive OS.

Enable automotive features in Android Studio

Use Android Studio 4.0 or higher to ensure that all Automotive OS features are enabled.

Create an automotive module

Some components of Android Automotive OS, such as the manifest, have platform-specific requirements, so you need to create a module that can keep the code for these components separate from other code in your project, such as the code used for your phone app.

Follow these steps to add an automotive module to your project:

  1. In Android Studio, select File > New > New Module.
  2. Select Automotive Module, then click Next.
  3. Provide an Application/Library name. This is the name that users see for your app on Android Automotive OS.
  4. Provide a Module name.
  5. Adjust the Package name to match your app.

  6. Select API 28:Android 9.0 (Pie) for the Minimum SDK, and then click Next.

    All cars that support Android Automotive OS run on Android 9 (API level 28) or higher, so selecting this value targets 100% of cars that use Android Automotive OS.

  7. Select Add No Activity, and click Finish.

After creating your module in Android Studio, open the AndroidManifest.xml in your new automotive module:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.media">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme" />

    <uses-feature
        android:name="android.hardware.type.automotive"
        android:required="true" />

</manifest>

You'll notice some standard app information in the application element, but there's also a uses-feature element that declares support for Android Automotive OS. Also note that there are no activities declared in the manifest.

If you implement a Settings or Sign-in activities, add them here. These activities are triggered by the system using explicit intents and are the only activities that should be declared within the manifest for your Android Automotive OS app.

After adding any Settings or Sign-in activities, complete your manifest file by setting the android:appCategory="audio" attribute in the application element and adding the following users-features elements:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.media">

    <application
        android:allowBackup="true"
        android:appCategory="audio"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme" />

    <uses-feature
        android:name="android.hardware.type.automotive"
        android:required="true" />

    <uses-feature
        android:name="android.hardware.wifi"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.screen.portrait"
        android:required="false" />
    <uses-feature
        android:name="android.hardware.screen.landscape"
        android:required="false" />

</manifest>

Explicitly setting these features to not required ensures that your app doesn't conflict with available hardware features in Automotive OS devices.

Declare media support for Android Automotive OS

Use the following manifest entry to declare that your app supports Android Automotive OS:

<application>
    ...
    <meta-data android:name="com.android.automotive"
        android:resource="@xml/automotive_app_desc"/>
    ...
</application>

This manifest entry refers to an XML file that declares what automotive capabilities your app supports. To indicate that you have a media app, add an XML file named automotive_app_desc.xml to the res/xml/ directory in your project. This file should include the following content:

<automotiveApp>
    <uses name="media"/>
</automotiveApp>

Intent filters

Android Automotive OS uses explicit intents to trigger activities in your media app. The manifest file should not contain any activities that have CATEGORY_LAUNCHER or ACTION_MAIN intent filters.

Activities like the one in the following example usually target a phone, or some other mobile device. These activities should be declared in the module that builds the phone app, not in the module that builds your Android Automotive OS app.

<activity android:name=".MyActivity">
    <intent-filter>
        <!-- You can't use either of these intents for Android Automotive OS -->
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
        <!--
        In their place, you can include other intent filters for any activities
        that your app needs for Android Automotive OS, such as settings or
        sign-in activities.
        -->
    </intent-filter>
</activity>

Update your gradle dependencies

We recommend that you keep your media browser service in a separate module that you share between your phone app and your automotive module. If you're using this approach, you need to update your automotive module to include the shared module, as shown in the following snippet:

my-auto-module/build.gradle

Groovy

buildscript {
    ...
    dependencies {
        ...
        implementation project(':shared_module_name')
    }
}

Kotlin

buildscript {
    ...
    dependencies {
        ...
        implementation(project(":shared_module_name"))
    }
}

Implement settings and sign-in activities

In addition to your media browser service, you can also provide vehicle-optimized Settings and Sign-in activities for your Android Automotive OS app. These activities allow you provide app functionality that isn't included in the Android Media APIs.

You should only implement these activities if your Android Automotive OS app needs to allow users to sign in or specify app settings. These activities aren't used by Android Auto.

Activity workflows

The following diagram shows how a user interacts with your Settings and Sign-in activities using Android Automotive OS:

Workflows for Settings and Sign-in activities

Figure 1. Settings and sign-in activity workflows

Add a settings activity

You can add a vehicle-optimized settings activity so that users can configure settings for your app in their car. Your settings activity can also provide other workflows, like signing in or out of a user's account or switching user accounts. Remember that this activity is only triggered by an app running on Android Automotive OS. Phone apps connected to Android Auto do not use it.

Declare a settings activity

You must declare your settings activity in your app's manifest file, as shown in the following code snippet:

<application>
    ...
    <activity android:name=".AppSettingsActivity"
              android:exported="true"
              android:theme="@style/SettingsActivity"
              android:label="@string/app_settings_activity_title">
        <intent-filter>
            <action android:name="android.intent.action.APPLICATION_PREFERENCES"/>
        </intent-filter>
    </activity>
    ...
</application>

Implement your settings activity

When a user launches your app, Android Automotive OS detects the settings activity that you declared and displays an affordance, such as an icon. The user can tap or select this affordance using their car's display to navigate to the activity. Android Automotive OS sends the ACTION_APPLICATION_PREFERENCES intent that tells your app to start your settings activity.

The rest of this section shows how you can adapt code from the Universal Android Music Player (UAMP) sample app to implement a settings activity for your app.

To begin, download the sample code:

# Clone the UAMP repository
git clone https://github.com/android/uamp.git

# Fetch the appropriate pull request to your local repository
git fetch origin pull/323/head:NEW_LOCAL_BRANCH_NAME

# Switch to the new branch
git checkout NEW_LOCAL_BRANCH_NAME

To implement your activity, follow these steps:

  1. Copy the automotive/automotive-lib folder into your automotive module.
  2. Define a preferences tree as in automotive/src/main/res/xml/preferences.xml.

  3. Implement a PreferenceFragmentCompat (see SettingsFragment.kt in UAMP) that your settings activity (see SettingsActivity.kt) will display. See the Android Settings guide for more information.

As you implement your settings activity, refer to these best practices for using some of the components in the Preference library:

  • Your app should have no more than 2 levels of depth below the main view in your settings activity.
  • Do not use a DropDownPreference. Use a ListPreference instead.
  • Organizational components:
  • All of the following components should have a key and title and may have a summary and/or icon:
    • Preference
      • Customize the logic in the onPreferenceTreeClick() callback of your PreferenceFragmentCompat implementation.
    • CheckBoxPreference
      • May have summaryOn or summaryOff instead of summary for conditional text.
    • SwitchPreference
      • May have summaryOn or summaryOff instead of summary for conditional text.
      • May have switchTextOn or switchTextOff.
    • SeekBarPreference
      • Should have a min, max, and defaultValue.
    • EditTextPreference
      • Should have dialogTitle, positiveButtonText, and negativeButtonText.
      • May have dialogMessage and/or dialogLayoutResource.
    • com.example.android.uamp.automotive.lib.ListPreference
      • Derives mostly from ListPreference
      • Used to display a single-choice list of Preference objects.
      • Must have an array of entries and corresponding entryValues.
    • com.example.android.uamp.automotive.lib.MultiSelectListPreference
      • Derives mostly from MultiSelectListPreference
      • Used to display a multiple-choice list of Preference objects.
      • Must have an array of entries and corresponding entryValues.

Add a sign-in activity

If your app requires a user to sign in before they can use your app, you can add a vehicle-optimized sign-in activity that handles signing in and out of your app. You can also add sign-in and sign-out workflows to a settings activity, but you should use a dedicated sign-in activity if your app cannot be used until a user signs in. Remember that this activity is only triggered by an app running on Android Automotive OS. Phone apps connected to Android Auto do not use it.

Require sign in at app start

To require a user to sign in before they can use your app, your media browser service must do the following things:

  1. In your service's onLoadChildren() method, send a null result using the sendResult() method.
  2. Set the media session's PlaybackState to STATE_ERROR using the setState() method. This tells Android Automotive OS that no other operations can be performed until the error has been resolved.
  3. Set the media session's PlaybackState error code to ERROR_CODE_AUTHENTICATION_EXPIRED. This tells Android Automotive OS that the user needs to authenticate.
  4. Set the media session's PlaybackState error message using the setErrorMessage() method. Because this error message is user-facing, the message must be localized for the user's current locale.

  5. Set the media session's PlaybackState extras using the setExtras() method. Include the following two keys:

The following code snippet shows how your app can require the user to sign in before using your app:

Kotlin

import androidx.media.utils.MediaConstants

val signInIntent = Intent(this, SignInActivity::class.java)
val signInActivityPendingIntent = PendingIntent.getActivity(this, 0,
    signInIntent, 0)
val extras = Bundle().apply {
    putString(
        MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_ERROR_RESOLUTION_ACTION_LABEL,
        "Sign in"
    )
    putParcelable(
        MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_ERROR_RESOLUTION_ACTION_INTENT,
        signInActivityPendingIntent
    )
}

val playbackState = PlaybackStateCompat.Builder()
        .setState(PlaybackStateCompat.STATE_ERROR, 0, 0f)
        .setErrorMessage(
            PlaybackStateCompat.ERROR_CODE_AUTHENTICATION_EXPIRED,
            "Authentication required"
        )
        .setExtras(extras)
        .build()
mediaSession.setPlaybackState(playbackState)

Java

import androidx.media.utils.MediaConstants;

Intent signInIntent = new Intent(this, SignInActivity.class);
PendingIntent signInActivityPendingIntent = PendingIntent.getActivity(this, 0,
    signInIntent, 0);
Bundle extras = new Bundle();
extras.putString(
    MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_ERROR_RESOLUTION_ACTION_LABEL,
    "Sign in");
extras.putParcelable(
    MediaConstants.PLAYBACK_STATE_EXTRAS_KEY_ERROR_RESOLUTION_ACTION_INTENT,
    signInActivityPendingIntent);

PlaybackStateCompat playbackState = new PlaybackStateCompat.Builder()
    .setState(PlaybackStateCompat.STATE_ERROR, 0, 0f)
    .setErrorMessage(
            PlaybackStateCompat.ERROR_CODE_AUTHENTICATION_EXPIRED,
            "Authentication required"
    )
    .setExtras(extras)
    .build();
mediaSession.setPlaybackState(playbackState);

After the user has successfully authenticated, your app must set the PlaybackState back to a state other than STATE_ERROR and then take the user back to Android Automotive OS by calling the activity's finish() method.

Implement your sign-in activity

Google offers a variety of identity tools that you can use to help users sign in to your app in their cars. Some tools, such as Firebase Authentication, provide full-stack toolkits that can help you build customized authentication experiences. Other tools leverage a user's existing credentials or other technologies to help you build seamless sign-in experiences for users.

We recommend the following tools to help you build an easier sign-in experience for users that have previously signed in on another device:

  • Google Sign-in: If you've already implemented Google Sign-in for other devices (such as your phone app), you should also implement Google Sign-in for your Android Automotive OS app to support existing Google Sign-in users.
  • Autofill with Google: If users have opted into Autofill with Google on their other Android devices, their credentials are saved to the Google password manager. Then, when the user signs in to your Android Automotive OS app, Autofill with Google suggests relevant saved credentials. Using Autofill with Google requires no application development effort; however, application developers should optimize their apps for better quality results. Autofill with Google is supported by all devices running Android Oreo 8.0 (API level 26) or higher (including Android Automotive OS).

Use AccountManager

Android Automotive OS apps that have authentication must use AccountManager for the following reasons:

  • Better UX and ease of account management: Users can easily manage all of their accounts from the accounts menu in the system settings, including sign in and sign out.
  • "Guest" experiences: Because cars are shared devices, OEMs can enable "guest" experiences in the vehicle, where accounts cannot be added. This restriction is achieved using DISALLOW_MODIFY_ACCOUNT for AccountManager.

Permissions

If you need to request permissions from the user, use the same flow as the authentication activity or the settings activity in the activity workflows diagram.

Error Handling

Errors in media apps on Android Automotive OS are communicated via the media session’s PlaybackState. For all errors, you should set an appropriate error code and error message in the PlaybackState. This causes a Toast to appear in the UI.

When an error occurs but playback can continue, you should issue a non-fatal error. For example, a user might be able to play music in an app before signing in, but they must sign in before they can skip a song. By using a non-fatal error, the system can suggest that the user should log in without interrupting playback for the current media item. In this case, you should preserve the rest of the PlaybackState as-is (aside from the error code and error message). Using this approach allows playback for the current media item to continue while the user decides whether to sign in or not.

When playback is not possible, for example if there is no internet connection and no offline content, you should set the PlaybackState state to STATE_ERROR.

On subsequent updates to your PlaybackState, you should clear the error code and error message to avoid displaying multiple warnings for the same error.

If at any point you are unable to load a browse tree—for example, if you require authentication and the user is not signed in—you should send an empty browse tree. To signify this, onLoadChildren() for the root media node should return a null result. When this happens the system displays a full-screen error with the error message set in the PlaybackState.

Actionable errors

If an error is actionable, additionally set the following two extras in the PlaybackState:

Actionable errors appear as a Dialog and can resolved by users only when the car is stopped.

Testing error cases

You should verify that your app handles gracefully in all scenarios, including:

  • Different tiers of your product: For example, free versus premium or signed in versus signed out.
  • Different drive states: For example, parked versus driving.
  • Different connectivity states: For example, online versus offline.

Other Considerations

Keep these other considerations in mind when developing your Android Automotive OS app:

Offline content

If applicable, implement offline playback support. Cars with Android Automotive OS are expected to have their own data connectivity, that is to say either a data plan included in the cost of the vehicle or paid for by the user. However, cars are also expected to have more variable connectivity than mobile devices. As such, we recommend thinking about the best offline support strategy for your content. The disk space on cars may vary, so ensure that users can delete offline content, for example through an option in your settings activity.

Here are a few things to keep in mind as you consider your offline support strategy:

  • The best time to download content is when your app is currently in use.
  • Do not assume that WiFi is available. A car might never come into WiFi range or the OEM might have disabled WiFi in favor of a cellular network.
  • While it is okay to smartly cache the content that you think users are likely to use, we highly recommend allowing the user to change this behavior through your settings activity.

Commerce support

Android Automotive OS does not currently support any commerce functionality. This means that you can't have a paid app nor any in-app purchases in your app. Users can purchase IAPs outside your Android Automotive OS app, but must not be required to do any additional commerce-related steps once in the car to use any new paid content or features.

WebView support

WebViews are supported in Android Automotive OS but are only allowed for your settings and sign-in activities. Activities that use a WebView must have a close and/or back affordance outside of the WebView.

Here are some examples of acceptable use-cases for WebViews:

  • Displaying your privacy policy, terms of service, or other legal-related links in your settings activity.
  • A web-based sign-in flow in your sign-in activity.

When using a WebView, you are allowed to enable Javascript.

Secure your WebView

Take all precautions possible to ensure that your WebView does not act as an entry point into the greater internet. See the code snippet below for an example on how to lock the WebView to the URL used in the loadUrl() call and prevent redirects. It is highly recommended to implement safeguards such as this when the use-case makes sense (for example, when displaying legal-related links).

Kotlin

override fun shouldOverrideUrlLoading(webView: WebView,
                             webResourceRequest: WebResourceRequest): Boolean {
  val originalUri: Uri = Uri.parse(webView.originalUrl)
  // Check for allowed URLs
  if (originalUri.equals(Uri.parse(BLANK_URL))
      || originalUri.equals(webResourceRequest.url)) {
    return false
  }
  if (webResourceRequest.isRedirect) {
    logger.w("Redirect detected, not following")
    return true
  }
  setupWizardWebViewClientListener.onUriBlocked(webResourceRequest.url)
  logger.w(
    String.format(
      "Navigation prevented to %s original is %s", webResourceRequest.url, originalUri))
  return true
}

Java

@Override
public boolean shouldOverrideUrlLoading(WebView webView, WebResourceRequest webResourceRequest) {
  Uri originalUri = Uri.parse(webView.getOriginalUrl());
  // Check for allowed URLs
  if (originalUri.equals(Uri.parse(BLANK_URL))
      || originalUri.equals(webResourceRequest.getUrl())) {
    return false;
  }
  if (webResourceRequest.isRedirect()) {
    logger.w("Redirect detected, not following");
    return true;
  }
  setupWizardWebViewClientListener.onUriBlocked(webResourceRequest.getUrl());
  logger.w(
      String.format(
          "Navigation prevented to %s original is %s", webResourceRequest.getUrl(), originalUri));
  return true;
}

Package names

Because you distribute a separate APK for Android Automotive OS, you have the option to reuse the package name from your mobile app or create a new package name. The main difference is that with a different package name your app has two completely separate Play Store listings, whereas if you reuse your current package name then you'll have a single listing across both platforms.

This is predominantly a business decision. For example, if you have one team working on the mobile app and a completely separate team working on your Android Automotive OS app, then it might make sense to have separate package names and let each team manage their own Play Store listing. There is not a large difference in the technical effort required to use either approach.

The following table summarizes some of the other key differences between each approach:

Feature Same package name New package name
Store listing Single Multiple
Mirrored install Yes. “Fast app reinstall” during the setup wizard No
Play Store Review process Blocking reviews. Currently, if the review fails for one APK, other APKs submitted in the same release are blocked Individual reviews
Statistics, metrics, and vitals Combined. Note: You can filter by device name for automotive-specific data (for example, 2 cars in year 2020) Separate
Indexing and search ranking Build off of current standing Does not carry over
Integrating with other apps Most likely no changes needed, assuming media code is shared between both APKs Might have to update the corresponding app (for example, for URI playback with Google Assistant)

Frequently asked questions

See the following sections for answers to some frequently asked questions about Android Automotive OS.

Hardware

Can my app get access to the microphone?

For apps targeting Android 10 (API level 29) or higher, refer to the sharing audio input documentation. This is not feasible prior to API level 29.

Which car APIs can we get access to and how?

You are limited to the APIs that are exposed by the OEM. We are in the process of standardizing how you access these APIs.

Apps can access car APIs using SetProperty() and GetProperty() in CarPropertyManager. Refer to the source code or reference documentation to see a list of all available properties. If the property is annotated with @SystemApi, it is limited to System (preloaded) apps.

What types of audio codecs are supported?

Refer to the audio codec details in the Android CDD.

Is Widevine DRM supported?

Yes. Widevine DRM is supported.

Development and testing

Are there any restrictions or recommendations for using third-party SDKs and libraries?

We don’t have any specific guidelines on using third-party SDKs and libraries. If you choose to use third-party SDKs and libraries, you are still responsible for complying with all the car app quality requirements.

Can I use a foreground service?

The only allowed use-case for a foreground service is downloading content for offline use. If you have another use case for a foreground service that you'd like to see support for, get in touch with us using the Android Automotive OS discussion group.

Publishing Android Automotive OS apps

How do I publish my Android Automotive OS app using the Google Play Console?

The app publishing process is similar to publishing your phone app, but you use a different release type. To opt in your app to use the Android Automotive OS release type, follow these steps:

  1. Open the Play Console.
  2. Select your app.
  3. From the left menu, select Release > Setup > Advanced settings > Release types.
  4. Select Add release type > Android Automotive OS, then follow the instructions in the Play Console.

Additional resources

To learn more about Android Automotive OS, see the following additional resources.

Samples

Guides

Blogs

Videos

Report an Android Automotive OS Media issue

If you run into an issue while developing your media app for Android Automotive OS, you can report it using the Google Issue Tracker. Be sure to fill out all the requested information in the issue template.

Create a new issue

Before filing a new issue, please check if it is already reported in the issues list. You can subscribe and vote for issues by clicking the star for an issue in the tracker. For more information, see Subscribing to an Issue.

Previous
Add support for Android Auto