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

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

雖然使用者可以手動建立 Google 助理快速指令，但是應用程式內宣傳 SDK 可以讓您主動建議並實作 Google 助理快速指令。您可以透過建議捷徑確定使用者可以確實回到他們喜愛的應用程式活動，而不用另外想辦法設定捷徑。

舉例來說，當有使用者在您的音樂應用程式中搜尋「健身用重金屬」時，您可以建議 Google 助理快速指令，讓使用者日後可以直接存取這些搜尋結果。建議捷徑時，應用程式會出現說明，提議該捷徑的句子，並詢問使用者是否要建立該捷徑。在本範例中，您建議使用句子「開始健身用重金屬」。使用者接受建議後，即可藉由說出「Ok Google，開始健身用重金屬」啟動捷徑。

有關如何擴充應用程式觀眾的資訊，請見「使用應用程式動作擴充應用程式」。

應用程式內宣傳 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 應用程式。

  • 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 (必要) 會決定向使用者建議捷徑時，是否需要驗證每一項建立的意圖。如果是 true，則會驗證由 AssistantShortcutSuggestionsClient 建立的意圖。如果意圖無效，便會回傳例外狀況。

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

  3. 使用 lookupShortcut 方法判斷您想建議的捷徑是否有效，以及系統內是否已有此捷徑。就算您不打算檢查現有的使用者捷徑，依然建議您實作 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 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. 使用捷徑意圖建立建議。

    建議的建立方法有兩種：

    • 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 是您希望建議使用者設為捷徑的語音內容。舉例來說，如果您希望使用者說出「Ok Google，幫我點珍珠奶茶」做為捷徑，您需要將 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: Cannot bind to service。請確認在資訊清單內，<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 助理快速指令。

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

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