配置 AppCard 主机

使用 AppCardHost 与显示 AppCard 的应用进行通信。

权限

任何使用 AppCardHost 的应用都必须具有以下权限:

  • android.permission.INTERACT_ACROSS_USERS_FULL
  • android.permission.QUERY_ALL_PACKAGES
  • 在 API 级别 34 及更高级别中) android.car.permission.BIND_APP_CARD_PROVIDER

初始化

如需初始化主机,请提供以下信息:

  • 背景信息
  • updateRate AppCard 更新速率(以毫秒为单位)。
  • fastUpdateRate 标记为 EnforceFastUpdateRate 的组件的更新速率(以毫秒为单位)
  • responseExecutor 您希望从 AppCard 应用接收响应的线程。

设计

您可以通过以下两种方式之一与 AppCardHost 进行交互:

AppCardListener

AppCardListener 组件会向 AppCardHost 注册自己,以接收来自 AppCardHost 和 AppCard 应用的通信更新。此处详细介绍了 AppCardListener 的接口函数。

fun onAppCardReceived(AppCardContainer)

当从应用收到 AppCard 时,系统会触发此函数。该函数会作为 AppCardContainer 发送,其中包含 AppCard 和 appIdentifier,用于标识发送 AppCard 的应用

fun onComponentReceived(AppCardComponentContainer)

当从应用收到 AppCard 组件时,系统会触发此函数。该函数会作为 AppCardComponentContainer 发送,其中包含一个 AppCard 组件 Identifier,用于识别发送 AppCard 的应用,以及一个字符串 ID,用于指向与该组件相关联的 AppCard。

fun onProviderRemoved(String, String?)

当 AppCard 提供程序被移除或停用时,系统会触发此函数。使用此方法可清理与给定软件包名称和提供方授权相关的所有有效 AppCard。

如果 authority 为 {@code null},则表示移除了整个软件包。

fun onProviderAdded(String, String?)

添加或启用 AppCard 提供程序时,系统会触发此函数。

用法示例。您可以将此函数用作触发器,以刷新 AppCard 选择器中的所有可用 AppCard。如果 authority 为 {@code null},则表示添加了整个软件包。

fun onPackageCommunicationError(appIdentifier, Throwable)

AppCardHost 在与 AppCard 提供程序通信时遇到错误时,系统会触发此函数。

用法示例。使用此方法可向用户显示其所选的 AppCard 遇到了错误。

API

fun refreshCompatibleapp()

每当使用托管应用的 activity 被恢复时,都应调用此方法,以便托管应用可以刷新其支持 AppCard 的应用列表。

fun destroy()

在使用宿主的 activity 被销毁时调用此方法,以便宿主可以清理所有连接和内部成员。

fun registerListener(AppCardListener)

用于注册 AppCardListener

fun unregisterListener(AppCardListener)

用于取消注册 AppCardListener

fun getAllAppCards(AppCardContext)

调用此方法可向已注册的 AppCardListener 提供系统中提供的所有 AppCard,并提供给定 AppCardContext,以向提供方提供有关如何构建其 AppCard 的提示。

fun requestAppCard(AppCardContext, appIdentifier, String)

调用此方法可向已注册的 AppCardListener 提供特定的 AppCard,前提是提供一个 AppCardContext,以向提供方提供有关如何构建其 AppCard 的提示。

fun notifyAppCardRemoved(appIdentifier, String)

通知 AppCard 提供商其 AppCard 已失效。

fun notifyAppCardInteraction(appIdentifier, String, String, String)

通知 AppCard 提供商其 AppCard 已被互动。 唯一支持的互动是按钮点击,以 AppCardMessageConstants.InteractionMessageConstants.MSG_INTERACTION_ON_CLICK 表示。

我们建议为 AppCard 创建一个带有 onClick 监听器的按钮,该监听器使用 appIdentifier、AppCard ID、组件 ID 和互动 ID 调用此函数。

fun sendAppCardContextUpdate(AppCardContext, appIdentifier, String)

为特定 AppCard 发送 AppCardContext 更新。例如,从停车模式切换到驾驶模式时,请使用此方法发送 AppCardContext 更新,其中每个有效的 AppCard 的 isInteractable 都设置为 false

常见问题解答

  1. 在哪里可以找到示例实现?

    • 主机示例。显示系统中所有可用的 AppCard 以及测试功能。

    • DriverUI 和 Pano Manager。Pano 管理器充当选择器,而 DriverUI 充当呈现程序。

  2. 每个 AppCardContentProvider 可以支持多少个 AppCard?

    AppCardContentProvider 可以支持无限数量的 AppCard。不过,请务必在 AppCard 数量、性能下降和良好用户体验之间取得平衡。