将动态快捷方式推送到助手

Android 快捷方式为用户提供在应用中执行操作或访问内容的快捷方法。助手可以在相关时机主动向用户推荐你的 Android 动态快捷方式，让用户能够轻松发现和重复使用你的语音功能。

例如，你可以为用户在记事应用中创建的每条记事推送一个快捷方式。通过将 Google Shortcuts Integration Jetpack 库添加到你的项目，你可以使动态链接有资格显示在 Google 的界面上，例如助手。这个库允许助手接收你使用 ShortcutManagerCompat 类推送的动态快捷方式，它是 ShortcutManager API 的 Jetpack 封装器。

在你的应用中使用 Google Shortcuts Integration 库后，你推送到 Google 的动态快捷方式将作为语音快捷方式建议显示在 Assistant 应用中供用户查看。你可以使用 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 库包含 ShortcutManagerCompat 类，你使用该类将动态快捷方式推送到 Google。

    androidx.core:core-google-shortcuts:1.0.1 是 Google Shortcuts Integration 库。此库不包含面向开发者的 API。通过将其添加为依赖项，你可以让助手接收你使用 ShortcutManagerCompat 类推送的动态快捷方式。

推送动态快捷方式

要推送有资格在助手中显示的动态快捷方式，首先使用 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 参数关联的情况下推送。当用户调用时，助手会触发快捷方式中定义的 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 Assistant 成功接收你的应用的动态快捷方式时，该快捷方式有资格作为语音快捷方式建议显示在 Assistant Android 应用中。助手应用会建议你的应用推送的最新快捷方式。

要使用助手测试你的动态快捷方式，请按照以下步骤操作

  1. 通过遵循与 Google Assistant 插件相同的设置要求，创建你的 App Actions 预览版并准备你的测试设备或模拟器以进行操作测试。
  2. 打开你的应用并定义一个要推送的动态快捷方式。然后完成一个操作。例如，如果你的记事应用在每次创建记事时都会推送一个快捷方式，那么创建一个新记事。
  3. 在你设备的 Assistant 设置应用中打开快捷方式。你的动态快捷方式将显示在你的应用的列表中。