Add support for Android Automotive OS to your templated app

Android Automotive OS allows users to install apps in the car. 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 described on this page.

To run your car app on Android Automotive OS, you need the latest Templates Host, which comes as a system app.

Development overview

Adding Android Automotive OS support only requires a few steps, as described in sections on this page:

1. Create an automotive module
2. Declare support for Android Automotive OS
3. Declare your CarAppService and CarAppActivity
4. Update your Gradle dependencies

Use Android Studio Bumblebee or newer 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. 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.

For an existing project, follow these steps to add an automotive module to your project:

1. In Android Studio, click 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. Enter a Module name.
5. Edit the Package name to match your existing app.

6. Select API 29: Android 10 (Q) for the Minimum SDK, then click Next. All cars that support the Car App Library on Android Automotive OS run on Android 10 API level 29 or higher, so selecting this value targets all compatible cars.

7. Select Add No Activity, then click Finish.

If you are starting a new project:

1. In Android Studio, click File > New > New Project.
2. Select Automotive for Project Type.
3. Select No Activity, then click Next.
4. Provide a Name for your project. This is the name that users see for your app on Android Automotive OS.
5. Enter a Package name. See the Package names section for more details on selecting a package name.

6. Select API 29: Android 10 (Q) for the Minimum SDK, then click Next.

   All cars that support the Car App Library on Android Automotive OS run on Android 10 API level 29 or higher, so selecting this value targets all compatible cars.

After you create your module in Android Studio, open the AndroidManifest.xml file in your new automotive module:

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

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

The application element has some standard app information as well as a uses-feature element that declares support for Android Automotive OS. Note that there are no activities declared in the manifest.

Next, add the following uses-feature elements to your manifest:

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

    <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" />
    <uses-feature
        android:name="android.software.car.templates_host"
        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" />
    <uses-feature
        android:name="android.hardware.camera"
        android:required="false" />

</manifest>

The first uses-feature element declares that your app uses the Templates Host to run. Explicitly setting the remaining four uses-feature elements to required="false" ensures that your app doesn't conflict with available hardware features in Android Automotive OS devices.

Update your Gradle dependencies

Within you automotive module, you must add a dependency on the androidx.car.app:app-automotive artifact, which includes the CarAppActivity implementation required for your app to run on Android Automotive OS.

If you are developing your app to support both Android Auto and Android Automotive OS, we recommend that you keep your CarAppService in a separate module that you share between your mobile and automotive modules. If you are using this approach, you need to update your automotive module to include the shared module using Gradle's project dependencies , as shown in the following snippet:

buildscript {
    ...
    dependencies {
        ...
        implementation "androidx.car.app:app-automotive:car_app_library_version"
        implementation project(':shared_module_name')
    }
}

buildscript {
    ...
    dependencies {
        ...
        implementation("androidx.car.app:app-automotive:car_app_library_version")
        implementation(project(":shared_module_name"))
    }
}

Declare 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 the automotive capabilities that your app supports.

To indicate that you have a Car App Library app, add an XML file named automotive_app_desc.xml to the res/xml/ directory in your Android Automotive OS module. This file should include the following content:

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

Declare your CarAppService and CarAppActivity

As with Android Auto, Android Automotive OS uses your CarAppService implementation to run your app. Refer to Create your CarAppService and Session and Declare your CarAppService for instructions on implementing and declaring your CarAppService.

Unlike Android Auto, you must include an additional application component, the CarAppActivity, to serve as the entry point for your Android Automotive OS app. The implementation of this activity is included in the androidx.car.app:app-automotive artifact and is responsible for communicating with the template host application to render your app's UI. You should only have one instance of this activity in your manifest, and it must be declared as follows:

<activity
    android:exported="true"
    android:theme="@android:style/Theme.DeviceDefault.NoActionBar"
    android:name="androidx.car.app.activity.CarAppActivity"
    android:launchMode="singleTask"
    android:label="Your app name">

    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <meta-data android:name="distractionOptimized" android:value="true" />

</activity>

• android:name is set to the fully-qualified class name of the CarAppActivity class from the app-automotive artifact.
• android:exported is set to true as the activity must be launchable by an app other than itself (namely, the launcher).
• android:launchMode is set to singleTask so the user can return to the same instance of the activity from the launcher if they navigate away.
• android:theme is set to @android:style/Theme.DeviceDefault.NoActionBar so that the app takes up the full screen space available to it.
• The intent filter indicates that this is the launcher activity for the app.
• There is a <meta-data> element that indicates to the OS that the app can be used while UX restrictions are in place, such as when the vehicle is in motion.

Additional requirements for navigation apps

For navigation apps, there are a few more required manifest entries for the CarAppActivity as shown in the following snippet:

<activity
    android:exported="true"
    android:theme="@android:style/Theme.DeviceDefault.NoActionBar"
    android:name="androidx.car.app.activity.CarAppActivity"
    android:launchMode="singleTask"
    android:label="Your app name">

    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
        <!-- Include the category below ONLY for navigation apps -->
        <category android:name="android.intent.category.APP_MAPS" />
    </intent-filter>

    <!-- Include the intent-filter below ONLY for navigation apps -->
    <intent-filter>
        <action android:name="androidx.car.app.action.NAVIGATE" />
        <category android:name="android.intent.category.DEFAULT" />
        <data android:scheme="geo" />
    </intent-filter>

    <meta-data android:name="distractionOptimized" android:value="true" />

</activity>

• The additional android.intent.category.APP_MAPS category informs the system that your app is able to show the user's location.
• The androidx.car.app.action.NAVIGATE intent filter ensures that users have the option of using your app when handling an implicit navigation intent from another car app.

Other Considerations

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

Package names

Because you distribute a separate Android Package Kit (APK) for Android Automotive OS, you can reuse the package name from your mobile app or create a new package name. If you use a different package name, your app has two separate Play Store listings. If you reuse your current package name, your app has 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 separate team working on your Android Automotive OS app, then it might make sense to have separate package names and let each team manage its own Play Store listing. There is not a large difference in the technical effort required to use either approach.

The following table summarizes some other key differences between keeping your current package name or using a new package name:

Offline content

If applicable, implement offline support in your app. Cars with Android Automotive OS are expected to have their own data connectivity, meaning a data plan is 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.

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

• The best time to download content is while your app is in use.
• Do not assume that WiFi is available. A car might never come into WiFi range, or the Original Equipment Manufacturer (OEM) might have disabled WiFi in favor of a cellular network.
• While it is okay to smartly cache content you expect users to use, we recommend that you let the user change this behavior.
• The disk space on cars varies, so give users a way to delete offline content.

Frequently asked questions

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

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

There are no 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.

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

For details on how to publish your Android Automotive OS app using the Google Play Console, see Distribute to cars.

Troubleshooting

See the following for help with some common troubleshooting scenarios on Android Automotive OS.

• Even after uninstalling a Car App Library app from the system settings, I get an error when trying to install a new version.

  To be sure that the app is uninstalled, use the command adb uninstall app.package.name.