使用應用程式內宣傳 SDK 建議捷徑

您可以向使用者建議 Google 助理快速指令,藉此宣傳應用程式的功能,讓應用程式更好用。Google 助理快速指令是簡短的句子,使用者可以說出這些句子,觸發應用程式內的功能。

雖然使用者可以手動建立 Google 助理快速指令,但是應用程式內宣傳 SDK 可以讓您主動建議並實作 Google 助理快速指令。建議捷徑後,您可以為使用者提供清楚簡單的路徑,讓他們輕鬆返回應用程式中最愛的活動,而不需要另外設定捷徑。

舉例來說,當有使用者在您的音樂應用程式中搜尋「健身重金屬樂」時,您可以建議對方採用 Google 助理快速指令,方便日後直接存取這些搜尋結果。您建議捷徑後,應用程式會出現含有建議捷徑短語的提示,並詢問使用者是否要建立捷徑。

在本範例中,您建議使用「start my heavy metal workout」這個短語。使用者接受建議後,即可藉由說出「Hey Google, start my heavy metal workout」啟動捷徑。

如要進一步瞭解如何拓展應用程式目標對象,請參閱「利用應用程式動作擴充應用程式」。

應用程式內宣傳 SDK 提供了以下方法:

  • lookupShortcut檢查系統內是否已有您想建議的捷徑。這個方法也會檢查是否有問題導致無法建立捷徑。如果無法建立捷徑,lookupShortcut 會回傳原因。

  • createShortcutSuggestionIntent傳回意圖,您可以運用這個意圖,指引使用者按照建議內容建立捷徑。

  • createShortcutSettingsIntent傳回意圖,您可以運用這個意圖,將使用者導向應用程式的 Google 助理快速指令設定。

必要條件和限制

本節將說明使用建議的必要條件和規範,以及您可能會碰到的限制。

開發環境必要條件

如要使用建議,開發環境必須符合以下必要條件。

  • 擴充 Android 應用程式,採用應用程式動作

  • 在資訊清單的 <queries> 標記內加入 com.google.android.googlequicksearchbox。例如:

    <manifest ...>
      <queries>
        <package android:name="com.google.android.googlequicksearchbox" />
      </queries>
      ...
    </manifest>
    
  • 使用 Android App Bundle 發布應用程式。

裝置需求

如要在裝置上測試建議,裝置必須安裝以下項目。

已知限制

系統僅支援英文建議。使用者必須將裝置上的 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 (必要) 會決定向使用者建議捷徑時,是否需要驗證每一項建立的意圖。如果是 true,則會驗證由 AssistantShortcutSuggestionsClient 建立的意圖。如果意圖無效,便會回傳例外狀況。

    • CUSTOM_EXECUTOR (非必要) 是執行非同步任務用的自訂執行程式。如未提供,SDK 會使用單一執行緒執行程式進行任務。

  3. 使用 lookupShortcut 方法判斷您想建議的捷徑是否有效,以及系統內是否已有此捷徑 (如適用)。

    1. 建立應用程式捷徑意圖。捷徑意圖代表您想建議使用者使用的捷徑。在下方範例中,我們針對訂飲料的捷徑來建立意圖。

      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. 將捷徑意圖傳遞給 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 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 意圖,可將使用者導向 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 意圖呼叫 startActivity

排解建議問題

本節說明建議捷徑時可能會發生的問題及例外狀況。

「GoogleInstallationUnsupportedException:無法繫結至服務」

由於受到套件瀏覽權限篩選機制影響,Android 11 以上版本可能會發生「GoogleInstallationUnsupportedException:無法繫結至服務」錯誤。請確認資訊清單的 <queries> 標記中含有 com.google.android.googlequicksearchbox

<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 App Bundle

「無法取得使用者捷徑」

如果您近期曾在裝置中新增帳戶,而裝置尚未對新帳戶的捷徑資料製作快取,便可能會顯示「無法取得使用者捷徑」錯誤訊息。

如果想同步處理裝置的捷徑資料,請利用 Google 助理應用程式介面新增或刪除 Google 助理快速指令。

捷徑建立活動立即關閉,並未顯示任何內容

如果您並未利用「應用程式動作測試工具」建立預覽,或是預覽已經過期,則捷徑建立活動便可能在未顯示任何內容的情況下關閉。請更新預覽,然後再試一次。