Configure an AppCard host

Use AppCardHost to communicate with apps that show AppCards.

Permissions

Any app that uses an AppCardHost must have the following permissions:

  • android.permission.INTERACT_ACROSS_USERS_FULL
  • android.permission.QUERY_ALL_PACKAGES
  • (In API level 34 and higher only) android.car.permission.BIND_APP_CARD_PROVIDER

Initialize

To initialize the host, provide:

  • Context
  • updateRate AppCard update rate in milliseconds.
  • fastUpdateRate Update rate in milliseconds for components tagged with EnforceFastUpdateRate
  • responseExecutor A thread on which you want to receive responses from AppCard apps.

Design

An AppCardHost can be interacted with in one of two ways:

OR,

AppCardListener

The AppCardListener component registers itself with an AppCardHost to receive communication updates from the AppCardHost and AppCard apps. The interface functions of an AppCardListener are detailed here.

fun onAppCardReceived(AppCardContainer)

This function is triggered when an AppCard has been received from an app. It's sent as an AppCardContainer which provides an AppCard and an appIdentifier to identify the app that sent the AppCard

fun onComponentReceived(AppCardComponentContainer)

This function is triggered when an AppCard component is received from an app. It's sent as an AppCardComponentContainer, which provides an AppCards component, Identifier to identify the app that sent the AppCard, and a string ID to point to the AppCard to which the component is related.

fun onProviderRemoved(String, String?)

This function is triggered when an AppCard provider has been removed or disabled. Use this method to clean up any active AppCard related to the given package name and provider authority.

If authority is {@code null}, then an entire package was removed.

fun onProviderAdded(String, String?)

This function is triggered when an AppCard provider has been added or enabled.

Sample usage. Use this function as a trigger to refresh all available AppCards in an AppCard picker. If authority is {@code null}, then an entire package was added.

fun onPackageCommunicationError(appIdentifier, Throwable)

This function is triggered when the AppCardHost encounters an error when communicating with an AppCard provider.

Sample usage. Use this method to show to the user that an AppCard they have selected has encountered an error.

APIs

fun refreshCompatibleapp()

This method should be called whenever the activity that is using the host is resumed so that the host can refresh its list of apps that support AppCards.

fun destroy()

Call this method when an activity that is using a host is destroyed so that the host can clean up all connections and internal members.

fun registerListener(AppCardListener)

Used to register an AppCardListener.

fun unregisterListener(AppCardListener)

Used to unregister an AppCardListener.

fun getAllAppCards(AppCardContext)

Call this method to supply a registered AppCardListener with all the AppCards provided in the system with a given AppCardContext that provides hints to the providers on how to structure their AppCard.

fun requestAppCard(AppCardContext, appIdentifier, String)

Call this method to supply a registered AppCardListener with a specific AppCard, given an AppCardContext that gives hints to the providers on how to structure their AppCard.

fun notifyAppCardRemoved(appIdentifier, String)

Notify an AppCard provider that its AppCard is no longer active.

fun notifyAppCardInteraction(appIdentifier, String, String, String)

Notify an AppCard provider that its AppCard has been interacted with. The only supported interaction is a button click, which is signified by a AppCardMessageConstants.InteractionMessageConstants.MSG_INTERACTION_ON_CLICK.

We recommend creating a button for an AppCard with an onClick listener that calls this function with appIdentifier, AppCard ID, component ID, and interaction ID.

fun sendAppCardContextUpdate(AppCardContext, appIdentifier, String)

Send an AppCardContext update for a specific AppCard. For example, when shifting from Park mode to Drive mode, use this method to send an AppCardContext update in which isInteractable is set to false for each active AppCard.

FAQ

  1. Where can I find sample implementations?

    • Sample host. Shows all available AppCards in the system, along with testing capabilities.

    • DriverUI and Pano manager. Pano manager acts as the picker while DriverUI acts as the presenter.

  2. How many AppCards can each AppCardContentProvider support?

    An AppCardContentProvider can support an infinite number of AppCards. However, be sure to balance the number of AppCards with degraded performance versus a positive user experience.