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, parking, and charging apps for Android Auto.

Latest Update	Current Stable Release	Next Release Candidate	Beta Release	Alpha Release
December 15, 2021	1.1.0	-	-	1.2.0-alpha02

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 testing
    implementation "androidx.car.app:app-testing:1.2.0-alpha02"
}

Kotlin

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

    // For testing
    implementation("androidx.car.app:app-testing:1.2.0-alpha02")
}

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

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)