Car App

User Guide Code Sample

API Reference
androidx.car.app
androidx.car.app.model
androidx.car.app.navigation
androidx.car.app.notification
androidx.car.app.serialization
androidx.car.app.validation
androidx.car.app.versioning

Build navigation and point of interest apps for Android Auto and Android Automotive OS.

Latest Update	Stable Release	Release Candidate	Beta Release	Alpha Release
September 7, 2022	1.1.0	1.2.0-rc01	1.3.0-beta01	-

Declaring dependencies

To add a dependency on the Car App Library, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

Groovy

dependencies {
    implementation "androidx.car.app:app:1.1.0"

    // For Android Auto specific functionality
    implementation "androidx.car.app:app-projected:1.1.0"

    // For Android Automotive specific functionality
    implementation "androidx.car.app:app-automotive:1.1.0"

    // For testing
    testImplementation "androidx.car.app:app-testing:1.3.0-beta01"
}

Kotlin

dependencies {
    implementation("androidx.car.app:app:1.1.0")

    // For Android Auto specific functionality
    implementation("androidx.car.app:app-projected:1.1.0")

    // For Android Automotive specific functionality
    implementation("androidx.car.app:app-automotive:1.1.0")

    // For testing
    testImplementation("androidx.car.app:app-testing:1.3.0-beta01")
}

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.3

Version 1.3.0-beta01

September 7, 2022

androidx.car.app:app:1.3.0-beta01, androidx.car.app:app-projected:1.3.0-beta01, androidx.car.app:app-automotive:1.3.0-beta01, and androidx.car.app:app-testing:1.3.0-beta01 are released. Version 1.3.0-beta01 contains these commits.

Car apps built using this library can now go to the Play Store using API Level 5 (see our development guide). Features annotated with API level 5 and under are compatible with both Android Auto 8.1+ and the Google Automotive App Host 1.4+.

New Features

In addition to capabilities added in Car App Library 1.3.0-alpha01, the following features have been added as part of beta01 (All features here only involve with host side changes without any API changes):

The floating navigation bar will continue to show even when a user is in a map-based selection screen in PlaceListNavigationTemplate, RoutePreviewNavigationTemplate, and MapTemplate. This can be done by updating navigation info through NavigationManager.updateTrip().
Enable the action button with FLAG_DEFAULT to have a timeout animation. This button will be clicked by default after the timeout. ([API 5 - All Templates])
A Rows subtext is not truncated when the car is parked, but truncated to 2 lines while driving. ([API 5 - All Templates])
Support disabled state for Action, Toggle, Row ([API 5 - All Templates])

API Changes

Relax constraints in MapTemplate list to support selectable lists (I961ed)
Remove the constraint for Header Actions to allow for custom icons. (Iad28f)
Add a constraint setOnClickListenerAllowed() to ActionsConstraints. Where it allowed Action to set OnClickDelegate() to actions except the standard icon types. (TYPE_APP_ICON, TYPE_BACK, and TYPE_PAN) (I3c745)

Bug Fixes

Added compatibility of Android Automotive Template Host 1.4+ with curved displays ([Host change])

Version 1.3.0-alpha01

July 27, 2022

androidx.car.app:app:1.3.0-alpha01, androidx.car.app:app-projected:1.3.0-alpha01, androidx.car.app:app-automotive:1.3.0-alpha01, and androidx.car.app:app-testing:1.3.0-alpha01 are released. Version 1.3.0-alpha01 contains these commits.

Features annotated with API level 5 are compatible with Android Auto 7.9 and above.

New Features

API Level 5: new MapTemplate that can be used by navigation apps to display pane or list content alongside a map (If5826, If44b8)
API Level 5: new CarAudioRecord API to allow recording audio input via the host vehicle's microphone (I5e71a)
API Level 5: new SuggestionManager API to allow apps to provide suggestions to the host (I5c103)
API Level 5: new Alert API to display in context notifications on the NavigationTemplate (I163a7, I5ad70)
API Level 5: new Header and MapController components to facilitate re-use across templates (If5826)
Added androidx.car.app.category.POI as a category for enabling POI apps (and deprecated androidx.car.app.category.PARKING and androidx.car.app.category.CHARGING) (I59da1)

API Changes

API Level 5: new onClick method in the SurfaceCallback interface to allow for tap on map interactivity (Ia9777)
API Level 5: new flags Action.FLAG_IS_PERSISTENT and Action.FLAG_DEFAULT to describe Actions (I96318, I5ad70)
API Level 5: new enabled/disabled state for the Action, Row, and Toggle components (host support coming around the 1.3.0-beta01 release of the library) (Id8a09)
API Level 5: Favor the new Header component via setHeader on the PlaceListNavigationTemplate.Builder and RoutePreviewNavigationTemplate.Builder, deprecating the existing setTitle and setHeaderAction methods (I30e6a)
API Level 5: new setOnContentRefreshListner method on the PlaceListMapTemplate.Builder and PlaceListNavigationTemplate.Builder for use with implementations of the new OnContentRefreshListner interface.
API Level 5: New setTripText and setTripIcon on the TravelEstimate.Builder to customise the travel estimate card (Idcc6d, Ic620d)
Add support for CarIconSpans in the PaneTemplate's title (Ia1ee0)
Add support for CarIconSpans in a Row's title and text (Ic1e3c)
Map ActionStrips can now have up to four actions (If3522)
Update Car App API level to 5 (I26b8e)
Headers/titles are now optional for the PlaceListMapTemplate, PlaceListNavigationTemplate, RoutePreviewNavigationTemplate, GridTemplate, ListTemplate, LongMessageTemplate, MessageTemplate, PaneTemplate, and SignInTemplate (I2078d, Icadde)

Bug Fixes

Updated PaneTemplate image sizing rules to be a square bounding box (Idd72e)
Fixed an exception that happens if the screen stack is modified after State.DESTROYED. (I3c8eb)
Added a null check for retriving the app icon (I3f710)
Update Car Hardware API to use STATUS_UNKNOWN instead of STATUS_UNAVAILABLE by default (Ic9444)
Check if display exists before creating surface (Ice027a)
Fix CarValue.equals() bug involving STATUS_UNIMPLEMENTED (I24451)

Version 1.2

Version 1.2.0-rc01

March 23, 2022

androidx.car.app:app-*:1.2.0-rc01 is released. Version 1.2.0-rc01 contains these commits.

This is a stabilization release, and there are no API changes compared to v1.2.0-beta02. New experimental features (API level 5) have been added that are intended for future Android Auto and Android Automotive releases.

Bug Fixes

Fixed an exception that happens if the screen stack is modified after State.DESTROYED. (I3c8eb)
Updated CarSensors API to indicate that they are not implemented for AAOS (Idd57b)
Updated PlaceListMapTempalte.Builder#setCurrentLocationEnabled to indicate that ACCESS_COARSE_LOCATION would be sufficient for the feature (I510c2)
Made exit number optional for roundabout-with-angle maneuver types (Ife7d1)

Version 1.2.0-beta02

January 26, 2022

androidx.car.app:app-*:1.2.0-beta02 is released. Version 1.2.0-beta02 contains these commits.

Car apps built with this library version targeting the Android Automotive OS platform can now be published to the Play Store open testing channel. Refer to the development guide for more details.

Features annotated with API level 4 and under are compatible with both Android Auto 7.2+ and the new Android Automotive OS platform. See the Known Issues section below for caveats.

API Changes

Added experimental setOnContentRefreshListener API to POI templates (I6bf22)

Bug Fixes

Fixed a memory leak in CarAppService when the car host unbinds. (I5c9ca, b/203594731)
Updated CarAppActivity javadoc to include requirements for singleTask launchmode (Id2f95)
Reduces the visual glitch on resume. (Iff7e0)

Known Issue(s)

The map ActionStrips in the PlaceListNavigationTemplate and RoutePreviewNavigateTemplate will start becoming available in the next Android Auto and Android Automotive OS releases.

Version 1.2.0-alpha02

December 15, 2021

androidx.car.app:app-*:1.2.0-alpha02 is released. Version 1.2.0-alpha02 contains these commits.

Features annotated with API level 4 has been upgraded from experimental to stable, including the map ActionStrips in the PlaceListNavigationTemplate and RoutePreviewNavigateTemplate, the CarIcon image in Panes, the QRCodeSignInMethod and the ability to set rendering hints (e.g. flags) in Actions.

New Features

In Android Auto 7.1+, the item limit for Pane has been increased from 2 to 4.

API Changes

Added an experimental toString() method to CarUnit(I36a3b)

Bug Fixes

Fixed a crash that happened in CarAppPermissionActivity if the callback is dead (If9823)
Changed Pane default list limit to 4 (I0068b)

Version 1.2.0-alpha01

November 3, 2021

androidx.car.app:app-*:1.2.0-alpha01 is released. Version 1.2.0-alpha01 contains these commits.

All new v1.2.0 features (API 4+) are currently experimental targeting future Android Auto and Android Automotive OS releases. Refer to the development guide for more details.

API Changes

Made AutomotiveCarInfo API experimental. (Ia13e5)
Added Car App Library API level 4 (I2a2e7)
API Level 4: Added support for setting a CarIcon in Pane (Ifcc12)
API Level 4: Added QR code sign in method (Ib623e)
API Level 4: Added set/getFlags to Action (Ic03ab)
API Level 4: Added support for panning and zooming in PlaceListNavigationTemplate and RoutePreviewNavigationTemplate (I9d8a3)

Bug Fixes

API Level 4: Add mechanism to allow apps to send location updates to the car host (I3bad3)
Fix an issue where the host validation logic was not finding the TEMPLATE_RENDERER permission properly (I62618)

Version 1.1.0

December 15, 2021

androidx.car.app:app-*:1.1.0 is released. Version 1.1.0 contains these commits.

This is a stabilization release, and there are no changes compared to v1.1.0-rc01. Also see the release notes for v1.2.0-alpha02 for more details on new features for the car app library.

Important changes since 1.0.0

API Level 2: SignInTemplate and LongMessageTemplate that can be used for sign-in flows when the vehicle is parked
API Level 2: map interactivity support within the NavigationTemplate
API Level 2: multiple-length text support to allow apps to provide multiple versions of string for display depending on the car screen sizes.
API Level 3: CarHardwareManagerthat can be used to query vehicle’s hardware data, such as model and make, fuel levels and other sensors.

Version 1.1.0-rc01

November 3, 2021

androidx.car.app:app-*:1.1.0-rc01 is released. Version 1.1.0-rc01 contains these commits.

This is a stabilization release, and there are no API changes compared to v1.1.0-beta01. New experimental features (API level 4) have been added that are intended for future Android Auto releases. See the release notes for v1.2.0-alpha01 for more details on the experimental APIs.

Version 1.1.0-beta01

September 1, 2021

androidx.car.app:app-*:1.1.0-beta01 is released. Version 1.1.0-beta01 contains these commits.

All v1.1.0 features (API 2+) are fully compatible with Android Auto 6.7 and above. Refer to the development guide for more details.

API Changes

Removed Manager as a public interface (Ie381b)
Added ability to set a custom branded background for permission request (I74b76)
Added ScreenManager.getStackSize (I0b16a)
Removed ScreenController constructor that explicit takes TestCarContext (Iefebc)

Bug Fixes

Added API level check when creating CarHardwareManager (I48f9b)
Added checks for invalid CarSpan usage across the API (I65ae6)
Fixed an issue where if a Screen is marked as finished during its creation, it would leave the stack in a broken state (I81b13)
Fix an issue where CarNotificationManager.notify would log an error for AutomotiveOS if there were actions with icons in the CarAppExtender (I3633d)
Added a handshake method for app and host to establish an API version (I7d6f8)

Version 1.1.0-alpha02

July 21, 2021

androidx.car.app:app-*:1.1.0-alpha02 is released. Version 1.1.0-alpha02 contains these commits.

New Features

API Level 3: Added a CarHardwareManagerthat can be used to query vehicle’s hardware data, such as model and make, fuel levels and other sensors. Currently, this feature is only available for Android Auto 6.7+ in the open-testing channel. Testing this in a desktop environment requires a new version of Desktop Head Unit which will be released separately. Stay tuned on Test Android apps for cars page for details on when the new version becomes available.
Follow the development guide and the library reference for additional details and design guidelines on how to use these features in car hosts that are compatible with API level 3.

API Changes

Consolidated SessionController and ScreenController lifecycle methods into a single moveToState method (I1ed00)
Added CarContext#getHostInfo() (I8977e)
Removed deprecated fields. (I67168)
Updated SessionController and ScreenController to expose constructors directly (Iabf22)
Removed PinSignInMethod.Builder and ProviderSignInMethod.Builder (I9f0cb)
Added 'setCarAppResult()' to enable using templated apps 'for result' in AAOS (I37741)
Annotated CarHardware interfaces with @MainThread. (Ib2f85)
Renamed OnCarDataListener to OnCarDataAvailableListener (I518ca)
Updated CarInfo, Speed, Mileage method names and javadoc. (I86672)
Renamed Toll to TollCard. (I3e7c8)
Removed deprecated PinSignInMethod.getPin which is replaced by PinSignInMethod.getPinCode (I996ce)
Removed OnInputCompletedListener (replaced with InputCallback). (Ib5be1)
Changed PinSignInMethod to take CharSequence instead of String (I275d5)

Bug Fixes

Javadoc fixes for car hardware. (I2abbc)

External Contribution

Known Issues

In the SignInTemplate, using the InputSignInMethod may result in a NullPointerException in the car host. This will be addressed in the next release of the library. To workaround the issue, include this line in your app’s Proguard config: -keep class androidx.car.app.model.signin.InputSignInMethod { *; }

Version 1.1.0-alpha01

June 16, 2021

androidx.car.app:app:1.1.0-alpha01, androidx.car.app:app-automotive:1.1.0-alpha01, and androidx.car.app:app-testing:1.1.0-alpha01 are released. Version 1.1.0-alpha01 contains these commits.

New Features

API Level 2: new SignInTemplate and LongMessageTemplate that can be used for sign-in flows when the vehicle is parked.
API Level 2: new map interactivity support within the NavigationTemplate
API Level 2: new multiple-length text support to allow apps to provide multiple versions of string for display depending on the car screen sizes.
Follow the development guide and the library Javadoc for additional details and design guidelines on how to use these features in car hosts that are compatible with API level 2.

API Changes

Made all *Callback interface methods default and renamed OnRequestPermissionsCallback -> OnRequestPermissionsListener (Ib3ec9)
Updated androidx.car.app.hardware classes to remove unnecessary builders and parameter classes. (I67beb)
Added androidx.car.app.hardware classes for access to car specific data such as fuel, battery and speed. (Iff3c9)
Added ActionStrip support on MessageTemplate (Ida657)
Added setLoading to MessageTemplate. (I2a4b5)
Renamed ConnectionToCar to CarConnection (Ife9bd)
Changed NavigationTemplate to return an explicit PanModeDelegate (I13877)
Updated parameter order for CarContext.requestPermissions (Ib890a)
Updated metadata key to define min car api level to androidx.car.api.minCarApiLevel (Ib0d41)
Created an API that allows observing car connection state (Ifc935)
Added support for setting a toggle for an Action, and added the pan mode Action type (Ica6af)
Created CarNotificationManager to support sending notification in the car (I10d7a)
Added ConstraintManager for providing list limits from the host (I8690e)
Added pan mode and map action strip API in NavigationTemplate (I77aa6)
Added pan and zoom API in SurfaceCallback for navigation apps (Id5e9d)
Updated CarAppApiLevel to 2 (Ic1540)
Added ability to request permissions from a CarAppService (I5421e)
Added RequiresCarApi(2) annotation to multi-text API (Iacb62)
Allowed multiple text variants in the half-list template title (Ib8df7)
Added new LongMessageTemplate (requires Car API level 2) (Ic5cee)

Bug Fixes

Updated image size requirements to account for larger car screens (I116dc)
Disallowed adding more than 2 actions in template bodies (I32157)
Ensured all creation of PendingIntents in the car app library set flags. (If84fe, b/186394900)
Updated javadoc to allow Row's text changes as refreshes (If3f9c)
androidx.activity:activity:1.2.0 is now an api dependency (Id1cb9)
Made SignInTemplate and LongMessageTemplate to require parked-only actions in their body and update documentation to indicate they will only be shown when the car is parked (Iddaa9)
Fixed an exception that occurs when popping a Screen during start (Ifcf40, b/184664896)
Allowed custom text color in ForegroundCarColorSpan (I69e59)
Fixed an issue where ON_DESTROY on a Session is observed after a Screen's ON_DESTROY (I52e01, b/183696617)
Updated javadoc on when setting a TravelEstimate's remaining time to an unknown time is allowed. (I99610, b/183632456)
Updated Action to support ForegroundColorSpan in the title and any custom background color (I578e4)
Do not execute NavigationManagerCallback#onStopNavigation if the callback is cleared before the executor executes (I7fc5e, b/181143772)
Fixed an issue that require the app to explicitly take on a dependency on lifecycle-common-java8 (I8b8c8)

Known Issues

In the SignInTemplate, the on-screen keyboard shows a “search” icon instead of an “enter” icon when the user wants to confirm the input. As a workaround, users can access the phone keyboard that activates when the input field is in focus.
In Android Auto version 6.5, the pan and zoom callbacks in SurfaceCallback may be incorrectly invoked for some touch gestures.

Car App Testing Version 1.0.0

Version 1.0.0-alpha01

March 24, 2021

androidx.car.app:app-testing:1.0.0-alpha01 is released. Version 1.0.0-alpha01 contains these commits.

This is the first Jetpack release of the previously closed source testing library. Refer to our samples on how to use this library in your tests.

New Features

The controllers for the model classes have been removed. Model getters are now part of the public API surface which allows for validating values that were set in the builders.
The previous CarAppServiceController has been replaced by the new SessionController for testing logic related to the lifetime of the connection to the hots.

Version 1.0.0

April 21, 2021

androidx.car.app:app:1.0.0 is released. Version 1.0.0 contains these commits.

Major features of 1.0.0

In early April, we announced that apps can start publishing to the production channel using androidx.car.app:app:1.0.0-rc01. Car App Library v1.0.0 is now stable and is fully compatible with Android Auto 6.1 and above.
Follow the development guide for details on how to build navigation, parking, and charging apps for Android Auto using the library.

Bug Fixes

Fixed an exception that occurs when popping a Screen during start (70aae1, b/184664896)
Fixed an issue where ON_DESTROY on a Session is observed after a Screen's ON_DESTROY (0ceecb, b/183696617)

Version 1.0.0-rc01

March 24, 2021

androidx.car.app:app:1.0.0-rc01 is released. Version 1.0.0-rc01 contains these commits.

Bug Fixes

Fixed a race condition bug where NavigationManagerCallback#onStopNavigation was being called after the callback was cleared. This happened if the callback was cleared before the callback executor actually ran (I7fc5e, b/181143772)
Fixed an issue that required the app to explicitly take a dependency on lifecycle-common-java8 (I8b8c8)
Fixed a NullPointerException that was thrown when the app receives a stopNavigation call when it has already removed a callback (Ib8b89, b/181143772)
Improvements to not dispatch calls to app if its lifecycle is not at least in a CREATED state (I86965, b/179800224, b/177921120)
Fixed an issue where an invalid min API specified in the app's manifest would throw, causing an ANR on the host. (Iffedd, b/174231592)

Version 1.0.0-beta01

February 24, 2021

androidx.car.app:app:1.0.0-beta01 is released. Version 1.0.0-beta01 contains these commits.

This is the first Jetpack release of the previously closed source library, and is compatible with Android Auto 6.1 or above. Follow the development guide for details on how to build car apps using the library.

New Features

Introduced a GridTemplate which your app can use to show a list of UI elements in a grid layout.
Introduced a CarAppService.createHostValidator method to validate that a host connection is from a trusted source (for example, Android Auto).
Added a CarAppExtender.Builder.setColor API. (b/174231592)

Bug Fixes

Fixed an issue where the wrong Screen is resumed when popping screens sequentially. (b/177590791)