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

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

虽然用户可以手动创建 Assistant 快捷方式，但应用内推广 SDK 使您能够主动建议和实现 Assistant 快捷方式。通过建议快捷方式，您可以为用户提供清晰、简单的路径，让他们轻松返回应用中最喜欢的活动，而无需额外努力设置快捷方式。

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

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

如需详细了解如何增加应用的用户群，请参阅使用 App Actions 发展您的应用。

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

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

• createShortcutSuggestionIntent：返回一个 intent，您可以使用该 intent 提示用户创建建议的快捷方式。

• createShortcutSettingsIntent：返回一个 intent，您可以使用该 intent 将用户引导至您应用的 Assistant 快捷方式设置。

前提条件和限制

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

开发前提条件

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

• 扩展您的 Android 应用以使用 App Actions。

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

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

• 使用Android App Bundles 发布您的应用。

设备要求

若要在设备上测试您的建议，您的设备必须已安装以下软件。

• 最新版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（必需）确定是否验证在向用户建议快捷方式时创建的每个 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<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. 将快捷方式 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，您可以使用它在您的应用上下文中启动快捷方式建议活动。

     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 是您想向用户建议作为快捷方式的 utterance。例如，如果您想让用户说出 "Hey Google, start a run" 作为快捷方式，请将 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，可将用户引导至 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: 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"（验证 APK 签名失败）

如果您未以应用 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”错误消息。

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

快捷方式创建活动立即关闭且未显示任何内容

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