Android 12 Developer Preview is here! Try it out, and give us your feedback!

Android for Cars - Jetpack Migration Guide

The Android for Cars App Library is now part of Jetpack! Migrating to Jetpack provides a number of benefits, including giving you more visibility into our feature development, and providing API consistency with other Jetpack libraries.

As part of this move to Jetpack, we have made a number of changes to the API to be consistent with the rest of the Android ecosystem. To help you migrate any apps you have already built with the closed source version of the Car App Library, we have compiled this guide, which describes the changes in detail and provides instructions to migrate your app to the new library.

AndroidManifest Changes

In your app’s AndroidManifest.xml, replace the following closed source library instances with their Jetpack library equivalents, wherever applicable:

App Categories

Closed source Jetpack library equivalent
com.google.android.car.category.NAVIGATION androidx.car.app.category.NAVIGATION
com.google.android.car.category.PARKING androidx.car.app.category.PARKING
com.google.android.car.category.CHARGING androidx.car.app.category.CHARGING

Permissions

Closed source Jetpack library equivalent
com.google.android.libraries.car.app.ACCESS_SURFACE androidx.car.app.ACCESS_SURFACE
com.google.android.libraries.car.app.NAVIGATION_TEMPLATES androidx.car.app.NAVIGATION_TEMPLATES
Not available. New in Jetpack library androidx.car.app.MAP_TEMPLATES

CarAppService

Closed source Jetpack library equivalent
com.google.android.car.action.CAR_APP androidx.car.app.CarAppService

Theming

Closed source Jetpack library equivalent
com.google.android.libraries.car.app.theme androidx.car.app.theme

API Changes

Namespace Change

The namespace of the library has been changed from com.google.android.libraries.car.app to androidx.car.app.

Replace all your library imports from com.google.android.libraries.car.app.* to androidx.car.app.*

CarAppService and Session

We have decoupled the lifecycle of the host connection to your app from CarAppService to a new Session class. The CarContext and Screen creation logic has now been moved to Session.

One of the main entry point to your app, CarAppService#onCreateScreen(Intent) has been replaced with CarAppService.onCreateSession. In essence, a number of methods that were previously in CarAppService are now in the Session class. Refer to the following tables for a summary and to the class-level documentation of Session for more details.

CarAppService
Closed source Jetpack library equivalent
finish() Removed

Invoke CarContext.finishCarApp directly instead.

getCarContext() Moved to Session
getLifecycle() Moved to Session
onCarAppFinished() Removed

Use Session.getLifecycle and listen for the Lifecycle.Event#ON_DESTROY event instead.

onCarConfigurationChanged(Configuration) Moved to Session
onCreateScreen(Intent) Moved to Session
onDestroy() Removed

This method is now irrelevant, and the logic is handled in CarAppService.onUnbind.

onNewIntent(Intent) Moved to Session
Not available. New in Jetpack library getCurrentSession()
Not available. New in Jetpack library onCreateSession()
Not available. New in Jetpack library createHostValidator() See Host validation.
Session
Closed source Jetpack library equivalent
Moved from CarAppService getCarContext()
Moved from CarAppService getLifeCycle()
Moved from CarAppService onCarConfigurationChanged(Configuration)
Moved from CarAppService onCreateScreen(Intent)
Moved from CarAppService onNewIntent(Intent)

In the simplest form, your app can return a Session instance like so if your app does not have any logic that deal with the lifecycle of the connection:

  @Override
  @NonNull
  public Session onCreateSession() {
    return new Session() {
      @Override
      @NonNull
      public Screen onCreateScreen(@Nullable Intent intent) {
        return new HelloWorldScreen(getCarContext());
      }
    };
  }

Builder Constructors

We are moving away from the model where we provide static builders for creating various data objects. Instead we expose the builder constructors as public methods directly. For example:

    Pane.Builder paneBuilder = Pane.builder();

has become:

    Pane.Builder paneBuilder = new Pane.Builder();

Builder Reusability

We are moving away from the model where we explicitly support builders to be reused. Builder methods that allow your app to clear some previously-set data are no longer available. For example, the following (and other clear* methods) have been removed:

    ActionStrip.Builder.clearActions()

New GridItem and GridTemplate

The Jetpack library comes with a new GridTemplate that presents a list of GridItem in a grid format. For details and usage, please refer to the documentation of GridTemplate.

Host validation

We have added mechanisms to allow your app to validate that a host connection is from a trusted source (for example, Android Auto and Android Automotive OS). A sample implementation for the abstract CarAppService.createHostValidator method is as follows:

    @Override
    public HostValidator createHostValidator() {
        if ((getApplicationInfo().flags & ApplicationInfo.FLAG_DEBUGGABLE) != 0) {
            return HostValidator.ALLOW_ALL_HOSTS_VALIDATOR;
        } else {
            return new HostValidator.Builder(getApplicationContext())
                    .addAllowedHosts(androidx.car.app.R.array.hosts_allowlist_sample)
                    .build();
        }
    }

See the documentation of CarAppService.createHostValidator for more details.

Miscellaneous Changes

The following tables highlight the rest of the changes we have done across the library (such as renaming existing or adding additional APIs). Note that this list is not exhaustive but provides insights to the categories of changes we have done to the library.

AppManager

Closed source Jetpack library equivalent
setSurfaceListener(SurfaceListener) setSurfaceCallback(SurfaceCallback)

CarContext

Closed source Jetpack library equivalent
Not available. New in Jetpack library getCarAppApiLevel()

OnScreenResultCallback -> OnScreenResultListener

Screen

Closed source Jetpack library equivalent
static final String ROOT Removed

Replaced by ScreenManager.poptoRoot

getTemplate() onGetTemplate()

ScreenManager

Closed source Jetpack library equivalent
Not available. New in Jetpack library popToRoot()

SurfaceListener -> SurfaceCallback

ItemList.Builder

Closed source Jetpack library equivalent
setOnItemsVisibilityChangeListener(OnItemsVisibilityChangedListener) setOnItemsVisibilityChangedListener(OnItemsVisibilityChangedListener)
setSelectable(OnSelectedListener) setOnSelectedListener(OnSelectedListener)

ListTemplate.Builder

Closed source Jetpack library equivalent
setIsLoading(boolean) setLoading(boolean)

Pane.Builder

Closed source Jetpack library equivalent
setIsLoading(boolean) setLoading(boolean)

PlaceListMapTemplate.Builder

Closed source Jetpack library equivalent
setIsLoading(boolean) setLoading(boolean)

Row.Builder

Closed source Jetpack library equivalent
setIsBrowsable(boolean) setBrowsable(boolean)

SearchTemplate.Builder

Closed source Jetpack library equivalent
setIsLoading(boolean) setLoading(boolean)

com.google.android.libraries.car.app.SearchListener -> androidx.car.app.model.SearchTemplate.SearchCallback

Toggle.Builder

Closed source Jetpack library equivalent
setCheckedChangeListener(OnCheckedChangeListener) setOnCheckedChangeListener(OnCheckedChangeListener)

NavigationManagerListener -> NavigationManagerCallback

Closed source Jetpack library equivalent
stopNavigation() onStopNavigation()

NavigationManager

Closed source Jetpack library equivalent
setListener(NavigationManagerListener) setNavigationManagerCallback(NavigationManagerCallback)
Not available. New in Jetpack library setNavigationManagerCallback(Executor, NavigationManagerCallback)
Not available. New in Jetpack library clearNavigationManagerCallback()

Maneuver

Closed source Jetpack library equivalent
Not available. New in Jetpack library static int TYPE_ROUNDABOUT_ENTER_CW
static int TYPE_ROUNDABOUT_EXIT_CW
static int TYPE_ROUNDABOUT_ENTER_CCW
static int TYPE_ROUNDABOUT_EXIT_CCW
static int TYPE_FERRY_BOAT_LEFT
static int TYPE_FERRY_BOAT_RIGHT
static int TYPE_FERRY_TRAIN_LEFT
static int TYPE_FERRY_TRAIN_RIGHT
Removed static int TYPE_ROUNDABOUT_ENTER
static int TYPE_ROUNDABOUT_EXIT

PlaceListNavigationTemplate.Builder

Closed source Jetpack library equivalent
setIsLoading(boolean) setLoading(boolean)

RoutePreviewNavigationTemplate.Builder

Closed source Jetpack library equivalent
setIsLoading(boolean) setLoading(boolean)

RoutingInfo.Builder

Closed source Jetpack library equivalent
setIsLoading(boolean) setLoading(boolean)

TravelEstimate

Closed source Jetpack library equivalent
Not available. New in Jetpack library static long REMAINING_TIME_UNKNOWN
static Builder builder(Distance, Duration, DateTimeWithZone) static Builder builder(Distance, DateTimeWithZone)
static Builder builder(Distance, Duration, ZonedDateTime) static Builder builder(Distance, ZonedDateTime)

TravelEstimate.Builder

Closed source Jetpack library equivalent
Not available. New in Jetpack library setRemainingTimeSeconds(long)
Not available. New in Jetpack library setRemainingTime(Duration)

Trip.Builder

Closed source Jetpack library equivalent
setIsLoading(boolean) setLoading(boolean)

CarAppExtender

Closed source Jetpack library equivalent
getLargeIconBitmap() getLargeIcon()
getSmallIconResId() getSmallIcon()

CarAppExtender.Builder

Closed source Jetpack library equivalent
Not available. New in Jetpack library setColor(CarColor)

Testing Library

The testing library is not yet available in the first beta release. Part of the functionality the testing library offered for accessing fields set in models through their builder classes is now available through the models' getters themselves. The rest of the testing functionality will be available when the testing library is released as part of Jetpack in the near future.