使用应用内宣传 SDK 建议快捷指令

若要推广应用的功能并使其更易于使用，您可以向用户建议 Google 助理快捷指令。Google 助理快捷指令是用户可以说出的简洁短语，用于触发应用中的功能。

虽然用户可以手动创建 Google 助理快捷指令，但借助应用内宣传 SDK，您可以主动建议和实现 Google 助理快捷指令。通过建议快捷指令，您可在应用中向用户提供清晰、简单的路径来返回其喜欢的 activity，而无需额外设置快捷指令。

例如，如果用户在您的音乐应用中搜索了“heavy metal workout”，您就可以建议用户将来使用 Google 助理快捷指令直接转到这些搜索结果。建议快捷指令时，应用中会出现一条提示，其中会显示建议的快捷指令短语，并询问用户是否可以创建该快捷指令。

在此示例中，您建议短语“start my heavy metal workout”。用户接受建议，然后即可通过说出“Hey Google, start my heavy metal workout”来启动该快捷指令。

如需详细了解扩大应用受众群体的方法，请参阅利用与应用有关的 Action 发展应用。

应用内宣传 SDK 提供了以下方法：

  • lookupShortcut：检查您要建议的快捷指令是否已存在。该方法还会检查是否存在任何阻止创建快捷指令的问题。如果无法创建快捷指令，lookupShortcut 会返回原因。

  • createShortcutSuggestionIntent：返回一个 intent，用于提示用户创建建议的快捷指令。

  • createShortcutSettingsIntent：返回一个 intent，用于将用户转至应用的 Google 助理快捷指令设置。

前提条件和限制

本部分介绍使用建议的前提条件和要求，以及您可能会遇到的限制。

开发前提条件

若要使用建议，您的开发环境必须满足以下前提条件。

  • 扩展您的 Android 应用以使用与应用有关的 Action。

  • 在清单的 <queries> 标记中添加 com.google.android.googlequicksearchbox。例如：

    <manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

  • 使用 Android App Bundle 发布应用。

设备要求

如需在设备上测试建议，您的设备必须安装：

  • 最新版本的 Google 应用

  • Android 6.0（API 级别 23）或更高版本

已知限制

仅支持英文建议。用户必须将自己设备上的 Google 助理语言设为英语，才能看到您的建议。

实现建议

若要实现建议，您需更新 build.gradle 文件，设置建议客户端，然后定义您想要向用户提供的建议。

  1. 为您的 build.gradle 文件添加库依赖项。

    dependencies {
  ...
  implementation "com.google.assistant.appactions:suggestions:1.0.0"
}

  2. 定义 AssistantShortcutSuggestionsClient 的实例。

    Kotlin

    val shortcutsClient =
  AssistantShortcutSuggestionsClient.builder()
    .setContext(CONTEXT: Context)
    .setVerifyIntents(VERIFY_INTENTS: Boolean)
    .setCustomExecutor(CUSTOM_EXECUTOR: Object)
    .build()

    Java

    AssistantShortcutSuggestionsClient shortcutsClient =
  AssistantShortcutSuggestionsClient.builder()
    .setContext(CONTEXT: Context)
    .setVerifyIntents(VERIFY_INTENTS: Boolean)
    .setCustomExecutor(CUSTOM_EXECUTOR: Object)
    .build();

    在此示例中：

    • CONTEXT（必需）是应用上下文。

    • VERIFY_INTENTS（必需）确定在向用户建议快捷指令时是否验证创建的每个 intent。设为 true 时，会验证 AssistantShortcutSuggestionsClient 创建的 intent。如果 intent 无效，则会返回异常。

    • CUSTOM_EXECUTOR（可选）是运行异步任务的自定义执行程序。如果未提供，SDK 会使用单线程执行程序执行任务。

  3. 使用 lookupShortcut 方法确定您要建议的快捷指令是否有效以及（可选）该快捷指令是否已存在。

    1. 创建应用快捷指令 intent。快捷指令 intent 表示您想向用户建议的快捷指令。以下示例为用于开始锻炼的快捷方式创建了一个 intent。

      Kotlin

      val exercise = mapOf(
    "@type" to "Exercise",
    "@context" to "http://schema.googleapis.com",
    "name" to "Running",
)

val appShortcutIntent = AppShortcutIntent.builder()
    .setIntentName("actions.intent.START_EXERCISE")
    .setPackageName("my.app.package")
    .setIntentParamName("exercise")
    .setIntentParamValue(exercise)
    .build()

      Java

        Map exercise = new HashMap<>();
  exercise.put("@type", "Exercise");
  menuItem.put("@context", "http://schema.googleapis.com");
  menuItem.put("name", "Running");

  AppShortcutIntent appShortcutIntent =
      AppShortcutIntent.builder()
          .setIntentName("actions.intent.START_EXERCISE")
          .setPackageName("my.app.package")
          .setIntentParamName("exercise")
          .setIntentParamValue(exercise)
          .build();

    2. 将快捷指令 intent 传递给 lookupShortcut 方法。

      Kotlin

      val result = shortcutsClient.lookupShortcut(appShortcutIntent).await()
if (!result.isShortcutPresent) {
    // App can suggest creating a shortcut
} else {
    // App can remind the user that they have a shortcut for this app action
}

      Java

      shortcutsClient.lookupShortcut(appShortcutIntent)
  .addOnSuccessListener(shortcutLookupResult -> {
    if (!shortcutLookupResult.isShortcutPresent()) {
      // App can suggest creating a shortcut
    } else {
      // App can remind the user that they have a shortcut for this app action
    }
  })
  .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));

  4. 使用快捷指令 intent 创建建议。您可以使用以下两种方法来创建建议：

    • createShortcutSuggestionIntent：返回一个 Android intent，用于在应用的上下文中启动快捷指令建议 activity。

      Kotlin

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand(PHRASE: String)
    .build()

val intent = shortcutsClient.createShortcutSuggestionIntent(exerciseShortcut).await()
application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))

      Java

        AppShortcutSuggestion exerciseShortcut =
      AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand(PHRASE: String)
          .build();

  shortcutsClient.createShortcutSuggestionIntent(exerciseShortcut)
      .addOnSuccessListener(intent ->
          getApplication().startActivity(
              intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
      )
      .addOnFailureListener(e ->
          Log.e(TAG, "Failed to get shortcut suggestion intent", e);
      );

      在此示例中，PHRASE 是要作为快捷指令向用户建议的语音内容。例如，如果您希望用户说出“Hey Google，开始跑步”作为快捷指令，您需要将 PHRASE 替换为 "start a run"。

      Kotlin

      val exerciseShortcut = AppShortcutSuggestion.builder()
    .setAppShortcutIntent(appShortcutIntent)
    .setCommand("start a run")
    .build()

      Java

      AppShortcutSuggestion exerciseShortcut =
    AppShortcutSuggestion.builder()
        .setAppShortcutIntent(appShortcutIntent)
        .setCommand("start a run")
        .build();

    • createShortcutSettingsIntent：返回一个 Android intent，用于将用户转到 Google 助理应用中的快捷指令设置界面。

      Kotlin

      val intent = shortcutsClient.createShortcutSettingsIntent().await()
application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))

      Java

        shortcutsClient.createShortcutSettingsIntent()
    .addOnSuccessListener(intent ->
        getApplication().startActivity(
            intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
    )
    .addOnFailureListener(e ->
        Log.e(TAG, "Failed to get shortcut settings intent", e);
    );

  5. 使用上一步中返回的 Android intent 调用 startActivity。

排查建议问题

本部分列出了在建议快捷指令时可能会遇到的问题和异常。

“GoogleInstallationUnsupportedException: Cannot bind to service”

由于软件包可见性过滤，在 Android 11 及更高版本中可能会发生“GoogleInstallationUnsupportedException: Cannot bind to service”。请确保在清单的 <queries> 标记中添加 com.google.android.googlequicksearchbox：

<manifest ...>
  <queries>
    <package android:name="com.google.android.googlequicksearchbox" />
  </queries>
  ...
</manifest>

“Failed to verify the APK signature”

如果您未将正式版应用作为 app bundle 提交，则可能会发生以下错误：

Failed to verify the APK signature. If this is a development build, please
make sure to update the preview of your app in App Actions Test Tool.

请务必将应用作为 Android App Bundle 提交。

“Failed to get user shortcuts”

如果您最近向设备添加了账号，并且设备上尚未缓存新账号的快捷指令数据，就可能会出现“Failed to get user shortcuts”错误消息。

如需同步设备上的快捷指令数据，请通过 Google 助理应用界面添加或删除 Google 助理快捷指令。

快捷指令创建 activity 立即关闭，而不显示任何内容

如果您未使用与应用有关的 Action 测试工具创建预览，或者预览已过期，快捷指令创建 activity 可能会关闭，而不显示任何内容。请更新您的预览，然后重试。