将动态快捷方式推送到 Google 助理

Android 快捷方式为用户提供了在应用中执行操作或访问内容的快捷方法。Google 助理可以在上下文相关的时候主动向用户推荐您的 Android 动态快捷方式，让用户能够轻松发现和再次执行支持语音的功能。

例如，您可以为用户在您记事应用中创建的每条记事分别推送一个快捷方式。您可以在自己的项目中添加 Google Shortcuts Integration Jetpack 库，让动态链接能够显示在 Google 产品界面（例如 Google 助理）上。借助该库，Google 助理便可接收您使用 ShortcutManagerCompat 类（一种 ShortcutManager API 的 Jetpack 封装容器）推送的动态快捷方式。

如果您在应用中使用 Google Shortcuts Integration 库，您推送到 Google 的动态快捷方式就会在 Google 助理应用中以语音快捷方式建议的形式向用户显示。您可以向 Google 助理推送任意数量的动态快捷方式，并可以使用 ShortcutManagerCompat 库的 pushDynamicShortcut() 方法。

配置开发项目

若要向应用添加动态快捷方式功能，就需要使用 Google Shortcuts Integration 库，这是一种 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 库包含用于向 Google 推送动态快捷方式的 ShortcutManagerCompat 类。

   androidx.core:core-google-shortcuts:1.0.1 是 Google 快捷方式集成库，不包含任何面向开发者的 API。只需将其添加为依赖项，Google 助理便可接收您使用 ShortcutManagerCompat 类推送的动态快捷方式。

   注意：如需查找最新版本的 Core 库和 Google Shortcuts Integration 库，请使用 Jetpack 库浏览器。

推送动态快捷方式

如需推送可在 Google 助理上显示的动态快捷方式，您先要使用 ShortcutInfoCompat.Builder() 类创建相应快捷方式，

然后使用 ShortcutManagerCompat.pushDynamicShortcut() 方法推送该快捷方式。推送快捷方式 每当用户在您的应用中完成相关操作时触发。以下示例 每当用户在记事和清单应用中创建清单时，代码都会推送一个快捷方式。

ExampleOrderActivity

Kotlin

// Define the dynamic shortcut for an item
var intent = Intent(context, DisplayOrderActivity::class.java)
intent.action = Intent.ACTION_VIEW
var shortcutInfo = ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Running")
    .setLongLabel("Start running")
    .addCapabilityBinding(
        "actions.intent.CREATE_ITEM_LIST", "itemList.name", Arrays.asList("My First List")
    )
    .setIntent(intent) // Push the shortcut
    .build()

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

Java

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

ShortcutInfoCompat.Builder shortcutInfo = new ShortcutInfoCompat.Builder(context, id)
    .setShortLabel("Running")
    .setLongLabel("Start running")
    .addCapabilityBinding(
      "actions.intent.CREATE_ITEM_LIST", "itemList.name", Arrays.asList("My First List"))
    .setIntent(intent)
    .build();

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

在上述示例代码中，通过 ShortcutInfoCompat.Builder 方法引用的 id 定义了所生成快捷方式对象的 shortcutId。此 id 必须是一个唯一的字符串字面量。如需了解详情，请参阅 Android 快捷方式文档。

此外，在上述示例中，addCapabilityBinding 方法将动态快捷方式绑定到 shortcuts.xml 中定义的同一 android:name 的 capability。利用这种方法，您可以将快捷方式与语义内置 intent (BII) 参数相关联。

即使没有关联任何特定的 BII 参数，动态快捷方式有时也会推送。在被用户调用时，Google 助理就会触发在快捷方式中定义 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("Create a list")
    .setLongLabel("Create a list")
    .addCapabilityBinding("actions.intent.CREATE_ITEM_LIST")
    .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("Create a list")
  .setLongLabel("Create a list")
  .addCapabilityBinding("actions.intent.CREATE_ITEM_LIST")
  .setIntent(intent)
  .build();

ShortcutManagerCompat.pushDynamicShortcut(context, shortcutInfo);

通过 Google 助理测试动态快捷方式

当 Google 助理从应用中成功接收某个动态快捷方式后，该快捷方式便可在 Android 版 Google 助理应用中以语音快捷方式建议的形式显示。Google 助理应用会推荐应用推送的最新快捷方式。

如需通过 Google 助理测试动态快捷方式，请按以下步骤操作：

1. 按照与 Google 助理插件相同的设置要求，创建与应用有关的 Action 的预览，并确保测试设备或模拟器已准备好执行测试操作。
2. 打开您的应用，然后定义要推送的动态快捷方式。接下来，执行相应操作。 例如，如果您想在记事应用中每次创建记事时推送快捷方式，则创建新记事。
3. 在设备上，打开 Google 助理设置应用中的快捷方式。确认动态快捷方式出现在该应用对应的列表中。