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

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

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

当您在应用中使用 Google 快捷方式集成库时，您推送到 Google 的动态快捷方式将作为助理应用中的语音快捷方式建议显示给用户。您可以使用 pushDynamicShortcut() 方法向助理推送无限数量的动态快捷方式。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。通过将其添加为依赖项，您可以使助理能够接收您使用 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。此方法允许您将快捷方式与语义 内置意图 (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 助理成功接收来自您应用的动态快捷方式后，该快捷方式就有资格作为语音快捷方式建议显示在助理 Android 应用中。助理应用会建议您的应用最近推送的快捷方式。

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

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