Set up your project

This page describes how to install the Car App library and now to configure the manifest file for your app.

Install the Car App library

To add the library to your app, see the Jetpack library release page.

Configure your app's manifest files

Before you can create your car app, you must configure your app's manifest files.

Declare your CarAppService

The host connects to your app through your CarAppService implementation. You declare this service in your manifest to let the host discover and connect to your app.

You also need to declare your app's category in the <category> element of your app's intent filter. See the list of supported app categories for the values allowed for this element.

The following code snippet shows how to declare a car app service for a point of interest app in your manifest:

<application>
    ...
   <service
       ...
        android:name=".MyCarAppService"
        android:exported="true">
      <intent-filter>
        <action android:name="androidx.car.app.CarAppService"/>
        <category android:name="androidx.car.app.category.POI"/>
      </intent-filter>
    </service>

    ...
<application>

Supported app categories

When you declare your CarAppService as described in Declare your CarAppService, you must also declare your app's category by adding one or more of these values in the intent filter.

• androidx.car.app.category.NAVIGATION: Provides turn-by-turn navigation instructions. See Build navigation apps for cars.

• androidx.car.app.category.POI: Provides functionality relevant to finding points of interest such as parking spots, charging stations, and gas stations. See Build point of interest apps for cars.

• androidx.car.app.category.IOT: Enables users to take relevant actions on connected devices from within the car. See Build internet of things apps for cars.

• androidx.car.app.category.WEATHER: Lets users see relevant weather information related to their current location or along their route. See Build weather apps for cars.

• androidx.car.app.category.MEDIA: Lets users browse and play music, radio, audiobooks, and other audio content in the car. See Build templated media apps for cars.

• androidx.car.app.category.MESSAGING: Lets users communicate with short-form text messages. See Build templated messaging experiences for Android Auto.

• androidx.car.app.category.CALLING: Lets users communicate with voice calling. See Build calling experiences for Android Auto.

For detailed descriptions of each category and the criteria required to qualify for a category, see Android app quality for cars.

Specify the app name and icon

To represent your app in the system UI, carPermissionActivityLayout must specify an app name and an icon for the host. Use the label and icon attributes of your CarAppService to specify the app name and icon used by the host to represent your app:

...
<service
   android:name=".MyCarAppService"
   android:exported="true"
   android:label="@string/my_app_name"
   android:icon="@drawable/my_app_icon">
   ...
</service>
...

If you don't declare a label or icon in the <service> element, the host falls back to values specified by the <application> element.

Set a custom theme

To set a custom theme for your car app:

1. Add a <meta-data> element in your manifest file:

   <meta-data
       android:name="androidx.car.app.theme"
       android:resource="@style/MyCarAppTheme />
   

2. Declare your style resource to set the attributes for your custom car app theme:

   <resources>
     <style name="MyCarAppTheme">
       <item name="carColorPrimary">@color/my_primary_car_color</item>
       <item name="carColorPrimaryDark">@color/my_primary_dark_car_color</item>
       <item name="carColorSecondary">@color/my_secondary_car_color</item>
       <item name="carColorSecondaryDark">@color/my_secondary_dark_car_color</item>
       <item name="carPermissionActivityLayout">@layout/my_custom_background</item>
     </style>
   </resources>