使用应用内宣传 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 版本为 M(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 方法确定您要建议的快捷指令是否有效以及该快捷指令是否已存在。即使您不打算检查用户快捷指令是否已存在,仍建议您实现 lookupShortcut 来验证您的建议创建的 intent 是否有效。

    1. 创建应用快捷指令 intent。快捷指令 intent 表示您想向用户建议的快捷指令。以下示例展示了一个让用户订购饮料的快捷指令。

      Kotlin

      val menuItem = mapOf(
          "@type" to "MenuItem",
          "@context" to "http://schema.googleapis.com",
          "name" to "Fresh Lemon Honey Jasmine Green Tea",
      )
      
      val appShortcutIntent = AppShortcutIntent.builder()
          .setIntentName("actions.intent.ORDER_MENU_ITEM")
          .setPackageName("my.app.package")
          .setIntentParamName("menuItem")
          .setIntentParamValue(menuItem)
          .build()
       

      Java

        Map menuItem = new HashMap<>();
        menuItem.put("@type", "MenuItem");
        menuItem.put("@context", "http://schema.googleapis.com");
        menuItem.put("name", "Fresh Lemon Honey Jasmine Green Tea");
      
        AppShortcutIntent appShortcutIntent =
            AppShortcutIntent.builder()
                .setIntentName("actions.intent.ORDER_MENU_ITEM")
                .setPackageName("my.app.package")
                .setIntentParamName("menuItem")
                .setIntentParamValue(menuItem)
                .build();
       
    2. 将快捷指令 intent 传递给 lookupShortcut 方法。

      Kotlin

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

      Java

      shortcutsClient.lookupShortcut(appShortcutIntent)
        .addOnSuccessListener(shortcutLookupResult -> {
          if (!shortcutLookupResult.isShortcutPresent()) {
            // app can suggest to create a shortcut
          } else {
            // app can remind that the user has a shortcut for this app action
          }
        })
        .addOnFailureListener(e -> Log.e(TAG, "Shortcut lookup failed", e));
      
  4. 使用快捷指令 intent 创建建议。

    您可以使用以下两种方法来创建建议:

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

      Kotlin

      val orderShortcut = AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand(PHRASE: String)
          .build()
      
      val intent = shortcutsClient.createShortcutSuggestionIntent(orderShortcut).await()
      application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
      

      Java

        AppShortcutSuggestion orderShortcut =
            AppShortcutSuggestion.builder()
                .setAppShortcutIntent(appShortcutIntent)
                .setCommand(PHRASE: String)
                .build();
      
        shortcutsClient.createShortcutSuggestionIntent(orderShortcut)
            .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, order my bubble tea”作为快捷指令,您需要将 PHRASE 替换为 "order my bubble tea"

      Kotlin

      val orderShortcut = AppShortcutSuggestion.builder()
          .setAppShortcutIntent(appShortcutIntent)
          .setCommand("order my bubble tea")
          .build()
      

      Java

      AppShortcutSuggestion orderShortcut =
          AppShortcutSuggestion.builder()
              .setAppShortcutIntent(appShortcutIntent)
              .setCommand("order my bubble tea")
              .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:无法绑定到服务

由于软件包可见性过滤,在 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 可能会在不显示任何内容的情况下关闭。请更新您的预览,然后重试。