将动态快捷方式推送到 Assistant

Android 快捷方式 为用户提供快速执行操作或访问应用中内容的方法。Assistant 可以主动在相关时间向用户建议您的 Android 动态快捷方式，使用户可以轻松发现和重复使用您的语音功能。

例如，您可以为用户在您的笔记应用中创建的每个笔记推送到一个快捷方式。通过将 Google 快捷方式集成 Jetpack 库 添加到您的项目中，您可以使动态链接有资格在 Google 表面（如 Assistant）上显示。此库允许 Assistant 接收您使用 ShortcutManagerCompat 类推送的动态快捷方式，该类是 ShortcutManager API 的 Jetpack 包装器。

当您在应用中使用 Google 快捷方式集成库时，您推送到 Google 的动态快捷方式将作为 Assistant 应用中的语音快捷方式建议显示给用户。您可以使用 pushDynamicShortcut() 方法向 Assistant 推送无限数量的动态快捷方式，该方法属于 ShortcutManagerCompat 库。

配置您的开发项目

将动态快捷方式功能添加到您的应用需要 Google 快捷方式集成库，该库是 Android Jetpack 库。本节介绍如何配置您的应用开发项目以包含此库。

要添加此 Jetpack 库并配置您的项目，请执行以下步骤

  1. 更新您的 gradle.properties 文件以处理 Jetpack 库

    gradle.properties

    android.useAndroidX=true
# Automatically convert third-party libraries to use AndroidX
android.enableJetifier=true

  2. 将 Jetpack 库依赖项添加到您的 build.gradle 中

    app/build.gradle

    dependencies {
 implementation "androidx.core:core:1.6.0"
 implementation "androidx.core:core-google-shortcuts:1.0.1"
 ...
}

    在前面的示例代码中，您将两个 Jetpack 库列为依赖项。 androidx.core:core:1.6.0 库包含 ShortcutManagerCompat 类，您可以使用该类将动态快捷方式推送到 Google。

    androidx.core:core-google-shortcuts:1.0.1 是 Google 快捷方式集成库。此库不包含面向开发者的 API。通过将其添加为依赖项，您允许 Assistant 接收您使用 ShortcutManagerCompat 类推送的动态快捷方式。

推送动态快捷方式

要推送有资格在 Assistant 上显示的动态快捷方式，您首先需要使用 ShortcutInfoCompat.Builder() 类创建快捷方式。

然后，您使用 ShortcutManagerCompat.pushDynamicShortcut() 方法推送快捷方式。每当用户在您的应用中完成相关操作时，都会推送快捷方式。以下示例代码显示了每当用户在食品配送应用中下订单时推送一个快捷方式

ExampleOrderActivity

Kotlin

// Define the dynamic shortcut for a menu item
var intent = Intent(context, DisplayOrderActivity::class.java)
intent.action = Intent.ACTION_VIEW
var shortcutInfo = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Cappuccino")
    .setLongLabel("Order another cappuccino")
    .addCapabilityBinding(
        "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino")
    )
    .setIntent(intent) // Push the shortcut
    .build()

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo)

Java

// Define the dynamic shortcut for a menu item
Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat.Builder shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Cappuccino")
    .setLongLabel("Order another cappuccino")
    .addCapabilityBinding(
      "actions.intent.ORDER_MENU_ITEM", "menuItem.name", Arrays.asList("cappuccino"))
    .setIntent(intent)
    .build();

// Push the shortcut
ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

在前面的示例代码中，ShortcutInfoCompat.Builder 方法中引用的 id 定义了生成的快捷方式对象的 shortcutId。此 id 必须是唯一的字符串文字。有关详细信息，请参阅 Android 快捷方式文档。

在前面的示例中，addCapabilityBinding 方法将动态快捷方式绑定到 shortcuts.xml 中定义的相同 android:name 的 capability。此方法允许您将快捷方式与语义 内置意图 (BII) 参数相关联。

动态快捷方式有时会没有特定的 BII 参数关联而被推送。当用户调用时，Assistant 会触发快捷方式中定义的 intent 来完成操作。以下示例显示了一个没有参数关联的动态快捷方式

Kotlin

var intent: Intent = Intent(context, DisplayOrderActivity::class.java)
intent.setPackage(this, "com.sample.app")
intent.setAction(Intent.ACTION_VIEW)

var shortcutInfo: ShortcutInfoCompat = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Order coffee")
    .setLongLabel("Order a cup of coffee")
    .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM")
    .setIntent(intent)
    .build()

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

Java

Intent intent = new Intent(context, DisplayOrderActivity.class);
intent.setPackage(this, "com.sample.app");
intent.setAction(Intent.ACTION_VIEW);

ShortcutInfoCompat shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
  .setShortLabel("Order coffee")
  .setLongLabel("Order a cup of coffee")
  .addCapabilityBinding("actions.intent.ORDER_MENU_ITEM")
  .setIntent(intent)
  .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

使用 Assistant 测试动态快捷方式

当 Google Assistant 成功从您的应用中接收动态快捷方式时，该快捷方式有资格作为 Assistant Android 应用中的语音快捷方式建议显示。Assistant 应用会建议您的应用推送的最新的快捷方式。

要使用 Assistant 测试您的动态快捷方式，请执行以下步骤

  1. 创建您的应用操作的预览，并按照与 Google Assistant 插件 相同的设置要求，为测试操作准备您的测试设备或模拟器。
  2. 打开您的应用并定义一个动态快捷方式进行推送。然后完成一项操作。例如，如果您在创建笔记时推送快捷方式，那么就创建一个新笔记。
  3. 在设备上的助理设置应用中打开快捷方式。您的动态快捷方式会显示在应用列表中。