Create an AppCard

To create an AppCard, an app must create a provider in the manifest that extends AppCardContentProvider. The AppCardContentProvider abstracts away underlying details to facilitate the creation of AppCards.

Manifest declaration

To create an AppCard, an app must create a provider in the manifest to extend AppCardContentProvider.

<provider android:name=".SimpleAppCardContentProvider"
            android:authorities="com.example.appcard.sample.media"
            android:permission="@string/host_permission"
            android:exported="true"
            android:enabled="true">
            <intent-filter>
                <action android:name="com.android.car.appcard.APP_CARD_PROVIDER" />
            </intent-filter>
</provider>

Only one provider can be defined per package and with these properties:

  • android:exported="true"
  • android:enabled="true"

  • android:permission="@string/host_permission"

    OR,

    • android:readPermission="@string/host_permission"

      AND,

      android:writePermission="@string/host_permission"

  • @string/host_permission exists in the AppCard library and defines a permission depending on the Android API version of the system.

    Using the string resource works only when building with Gradle. When using Soong, specify the explicit string with the string resource value according to the appropriate resource qualifier.

  • (default) android:grantUriPermissions="false"

  • (default) android:forceUriPermissions="false"

    To avoid unexpected results, it's required that the provider define a single authority only in android:authorities.

  • Declare an action-based intent filter, com.android.car.appcard.APP_CARD_PROVIDER

Extend AppCardContentProvider

This section describes override and protected final methods.

Override methods

val authority: String
Use this method to return the authority defined in the android:authorities manifest property.

fun onCreate(): Boolean
This method must call super.onCreate(). Use this method to set up functionality that could potentially cause a delay if set up when an AppCard is requested.

val appCardIds: List
Use this method to return the list of supported AppCard IDs. We recommend making each ID verbose since this string is used to log errors.

fun onAppCardAdded(String, AppCardContext): AppCard
This method is called when an AppCard is shown for the first time and provides the ID related to the AppCard and the AppCardContext that provide hints as to how the AppCard is displayed.

Use this method to set up any functionality required by the AppCards supported as a provider. Once this function is called, the AppCard that corresponds to the given ID is considered to be active.

fun onAppCardRemoved(String)
This method is called when no remaining instances of the AppCard are shown to the user and handles all clean up. When this function is called, the AppCard that corresponds to the given ID is considered inactive.

fun onAppCardContextChanged(String, AppCardContext)
This method is called when the system wants to update how an AppCard is displayed and sends an updated AppCardContext.

Protected final methods

fun sendAppCardUpdate(AppCard)
Invoke this method to queue an update for an active AppCard.

fun sendAppCardComponentUpdate(String, Component)
Invoke this method to queue an update for a component in an active AppCard. If the given component is tagged with EnforceFastUpdateRate, then the update is sent immediately.

FAQ

Where are the sample implementations?