使用应用内推广 SDK 建议快捷方式

为了推广您的应用功能并使其更易于使用，您可以向您的用户建议助手快捷方式。助手快捷方式是用户可以说的简短短语，用于触发应用内的功能。

尽管助手快捷方式可以由您的用户手动创建，但应用内推广 SDK 使您可以主动建议和实现助手快捷方式。通过建议快捷方式，您可以为您的用户提供清晰、简单的路径，让他们无需额外设置快捷方式即可返回到应用中他们最喜欢的活动。

例如，如果用户在您的音乐应用中搜索“重金属锻炼”，您可能会在将来直接建议一条指向这些搜索结果的助手快捷方式。当您建议快捷方式时，您的应用中会出现一个提示，显示快捷方式的建议短语，并询问用户是否可以创建快捷方式。

在此示例中，您建议使用短语“开始我的重金属锻炼”。用户接受建议，然后可以通过说“嘿 Google，开始我的重金属锻炼”来启动快捷方式。

有关扩展应用受众的更多信息，请参阅 使用应用操作扩展您的应用。

应用内推广 SDK 提供以下方法

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

  • createShortcutSuggestionIntent：返回您可以用来提示用户创建建议的快捷方式的意图。

  • createShortcutSettingsIntent：返回您可以用来将用户移动到应用的助手快捷方式设置的意图。

先决条件和限制

本节介绍使用建议的先决条件和要求，以及您可能会遇到的限制。

开发先决条件

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

  • 扩展您的 Android 应用以 使用应用操作。

  • 在清单中的 <queries> 标记内包含 com.google.android.googlequicksearchbox。例如

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

  • 使用 Android 应用包 发布您的应用。

设备要求

要在设备上测试您的建议，您的设备必须安装以下内容。

  • 最新版本的 Google 应用

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

已知限制

建议仅支持英语。要让用户看到您的建议，他们必须将设备上的助手语言设置为英语。

实施建议

要实施建议，您需要更新 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（必需）确定是否在向用户建议快捷方式时验证每个创建的意图。当为 true 时，将验证 AssistantShortcutSuggestionsClient 创建的意图。如果意图无效，则会返回异常。

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

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

    1. 创建一个应用快捷方式意图。快捷方式意图代表您要建议给用户的快捷方式。以下示例创建了用于启动锻炼的快捷方式的意图。

      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<String, Object> 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. 将快捷方式意图传递给 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. 使用快捷方式意图创建建议。您可以使用两种方法创建建议

    • createShortcutSuggestionIntent：返回一个 Android 意图，您可以使用它在应用上下文中启动快捷方式建议活动。

      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 是您要建议给用户作为快捷方式的语音表达。例如，如果您希望用户说“嘿 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，该 Intent 可将用户引导至 Assistant 应用中的快捷方式设置界面。

      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: 无法绑定到服务"

由于包可见性过滤，“GoogleInstallationUnsupportedException: 无法绑定到服务”可能会在 Android 11 及更高版本上发生。请确保com.google.android.googlequicksearchbox包含在清单文件中的<queries>标签内。

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

"APK 签名验证失败"

如果您未将生产应用提交为应用包，则可能会发生以下错误。

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 应用包。

"无法获取用户快捷方式"

"无法获取用户快捷方式"错误消息可能会在您最近向设备添加帐户且新帐户的快捷方式数据尚未缓存在设备上时发生。

要同步设备上的快捷方式数据，请使用 Assistant 应用的界面添加或删除 Assistant 快捷方式。

快捷方式创建活动立即关闭，没有任何内容显示

如果您没有使用应用操作测试工具创建预览，或者预览已过期，则快捷方式创建活动可能会在不显示任何内容的情况下关闭。更新您的预览，然后重试。