您可以向使用者建議 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例項。val shortcutsClient =
AssistantShortcutSuggestionsClient.builder()
.setContext(CONTEXT: Context )
.setVerifyIntents(VERIFY_INTENTS: Boolean )
.setCustomExecutor(CUSTOM_EXECUTOR: Object )
.build()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方法判斷您想建議的快速指令是否有效，並視需要判斷系統內是否已有此快速指令。建立應用程式快速指令意圖。快速指令意圖代表您想向使用者建議的快速指令。以下範例 為開始運動的快速指令建立意圖。
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()
Map
將快速指令意圖傳遞給
lookupShortcut方法。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
}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 意圖，您可以運用該意圖在應用程式範圍內啟動快速指令建議活動。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))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。createShortcutSettingsIntent：傳回 Android 意圖，該意圖可將使用者導向 Google 助理應用程式的快速指令設定介面。val intent = shortcutsClient.createShortcutSettingsIntent().await()
application.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))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 助理快速指令。
快速指令建立活動立即關閉，並未顯示任何內容
如未利用應用程式動作測試工具建立預覽，或是預覽已過期，則快速指令建立活動可能在未顯示任何內容的情況下關閉。請更新預覽，然後再試一次。