本頁面由 Cloud Translation API 翻譯而成。

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

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

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

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

在本範例中，您建議使用「start my heavy metal workout」(開始重金屬樂健身) 這個語句。使用者接受建議後，即可藉由說出「Hey Google, start my heavy metal workout」(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 6.0 (API 級別 23) 以上版本

已知限制

系統僅支援英文建議。使用者必須將裝置上的 Google 助理語言設為英文，才能看到您的建議。

實作建議功能

如要實作建議功能，您需要更新 build.gradle 檔案、設定建議用戶端，然後定義要為使用者提供的建議。

在 build.gradle 檔案中加入程式庫依附元件。

dependencies {
  ...
  implementation "com.google.assistant.appactions:suggestions:1.0.0"
}

定義 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 會使用單一執行緒執行程式執行工作。

使用 lookupShortcut 方法判斷您想建議的快速指令是否有效，並視需要判斷系統內是否已有此快速指令。

建立應用程式快速指令意圖。快速指令意圖代表您想向使用者建議的快速指令。以下範例為開始運動的快速指令建立意圖。

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 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();

將快速指令意圖傳遞給 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));

使用快速指令意圖建立建議。您可以使用以下兩種方法建立建議：

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 是您建議使用者設為快速指令的語句。比方說如果你希望使用者改成「Ok Google，開始跑步」做為捷徑，請取代 "start a run" 會員價 PHRASE。

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 意圖，該意圖可將使用者導向 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);
    );

使用上一步傳回的 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 助理快速指令。

快速指令建立活動立即關閉，並未顯示任何內容

如未利用應用程式動作測試工具建立預覽，或是預覽已過期，則快速指令建立活動可能在未顯示任何內容的情況下關閉。請更新預覽，然後再試一次。

使用應用程式內宣傳 SDK 建議捷徑 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

必要條件和限制

開發環境必要條件

裝置需求

已知限制

實作建議功能

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

Kotlin

Java

建議功能疑難排解

「GoogleInstallationUnsupportedException：無法繫結至服務」

「無法驗證 APK 簽章」

「無法取得使用者快速指令」

快速指令建立活動立即關閉，並未顯示任何內容

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