為 Android 應用程式實作應用程式動作時,您可能會發現自己需要處理主題的變化版本要求。舉例來說,如果您的健身應用程式實作 START_EXERCISE
內建意圖 (BII),讓使用者可以問 Google 助理「Ok Google,在範例應用程式開始跑步」等事項,以開始多種不同的健身活動。
若要執行此意圖,您的要求必須比對邏輯以處理各種類型的運動,包括「慢跑」、「短跑」或「賽跑」等變化版本。隨著支援的健身增加,此邏輯很快就變得繁瑣。
如為支援的 BII (例如 START_EXERCISE
),您可以使用內嵌清查來避免這種複雜的比對邏輯。內嵌清查是 shortcuts.xml
中定義的一組靜態 Android 捷徑,代表應用程式中的功能和內容。
每個捷徑都包含一個項目 ID,以及代表使用者如何參照項目的同義詞清單。在叫用期間,BII 會比較使用者提供的 BII 參數與同義詞清單。找到相符項目時,BII 參數會更新為相符捷徑的項目 ID。
內嵌清查可讓 Google 助理在應用程式動作叫用期間,簡化提供給應用程式的 BII 參數值。
內嵌清查的功能和 BII 參數的對照表類似,並且使用您定義的項目 ID,來表示使用者在應用程式中參照功能或內容的不同方式。這種做法可讓執行要求從 BII 參數預期項目 ID,藉此簡化應用程式的要求比對邏輯。
![內嵌清查使用者流程圖表](https://developer.android.google.cn/static/guide/app-actions/images/appactions-inline-inventory-flow.png?authuser=6&hl=zh-tw)
START_EXERCISE
功能流程圖表,使用內嵌清查將使用者提供的健身名稱解譯為應用程式中支援的運動類型。
相關限制和替代方案
內嵌清查捷徑有下列限制:
- 捷徑限制:每個應用程式最多可以定義 1,000 個內嵌清查捷徑。
- 同義詞限制:每個內嵌清查捷徑最多可包含 20 個同義詞值。
- 靜態定義:內嵌清查捷徑會以靜態方式在
shortcuts.xml
中宣告,而且只能透過發布新版應用程式的方式更新。
由於靜態設定的要求,內嵌清查最適合用來將不常變更的個人化應用程式資訊提供給 Google 助理,例如菜單品項、公車路線或飲料大小。如果是其他類型的內容,請考慮使用以下替代方式:
網站清查:允許 Google 助理在比對使用者查詢與支援的應用程式內容 ID 時,查詢公開網頁內容。網站清查查詢會在叫用期間即時執行,方便您將產品目錄、社交媒體訊息和其他經常更新的內容延伸到 Google 助理。
動態捷徑:將個人化應用程式內容的清查延伸到 Google 助理。動態捷徑可讓使用者快速重播常用動作,例如使用訂餐應用程式重新訂購自己喜愛的飲料,或在筆記應用程式中擷取購物清單。
建立內嵌清查
內嵌清查可讓 Google 助理輕鬆地將不同的應用程式要求和功能轉譯為可預測的 ID,從而簡化應用程式的開發。舉例來說,假設您的應用程式提供使用者能夠使用語音開始的不同健身,且您的應用程式會預期使用者針對相同的運動類型提出下列要求:
- Ok Google,在範例應用程式上開始跑步。
- Ok Google,在範例應用程式上開始慢跑。
在內嵌清查捷徑中,您可以將 shortcutId
設為 "CARDIO_RUN"
,也就是應用程式預期的運動 ID。然後,您可以將「跑步」和「慢跑」指定為與 shortcutId
相關聯的同義詞。接著,當使用者使用先前的查詢觸發您的應用程式動作時,Google 助理在產生執行要求意圖時會使用 BII 參數的 ID "CARDIO_RUN"
。
以下 app/res/shortcuts.xml
範例檔案中的程式碼片段會實作此案例:
<capability android:name="actions.intent.START_EXERCISE">
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.ExerciseActivity">
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</capability>
<shortcut android:shortcutId="CARDIO_RUN">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/run_names" />
</capability-binding>
</shortcut>
在上述範例中,內嵌清查 shortcut
在 <capability-binding>
元素內宣告 <parameter-binding>
標記,並將其繫結至 <capability>
中定義的 exercise.name
BII 參數。
字串陣列資源 @array/run_names
指定 res/values/arrays.xml
中的同義詞清單,且 Google 助理會辨識該同義詞並對應至 "CARDIO_RUN"
項目 ID:
<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
<string-array name="run_names">
<item>Run</item>
<item>Jog</item>
<item>Sprint</item>
</string-array>
</resources>
為功能提供 <url-template>
時,相符值的 shortcutId
會於參數中對應的預留位置插入。以下 app/res/shortcuts.xml
範例檔案中的程式碼會實作此案例:
<capability android:name="actions.intent.START_EXERCISE">
<intent>
<url-template android:value="myapp://workout{?exercise}" />
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</capability>
<shortcut android:shortcutId="CARDIO_RUN">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/run_names" />
</capability-binding>
</shortcut>
在上述範例中,Google 助理會產生執行要求深層連結 myapp://workout?exercise=CARDIO_RUN
。
使用捷徑意圖的執行要求
根據預設,捷徑提供其繫結的 capability
intent
shortcutId
比對內嵌清單值,如捷徑的 <capability-binding>
標記中所宣告。您也可以在 capability
中加入 <shortcut-fulfillment>
標記,藉以指定執行要求使用捷徑中定義的 intent
。
以下 app/res/shortcuts.xml
範例檔案中的程式碼會實作捷徑執行要求:
<capability android:name="actions.intent.START_EXERCISE">
<shortcut-fulfillment>
<parameter android:name="exercise.name"/>
</shortcut-fulfillment>
</capability>
<shortcut android:shortcutId="CARDIO_RUN">
<capability-binding android:key="actions.intent.START_EXERCISE">
<parameter-binding
android:key="exercise.name"
android:value="@array/run_names" />
</capability-binding>
<intent android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.ExerciseActivity">
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</shortcut>
在上述範例中,如果使用者查詢符合 exercise.name
參數的內嵌清查值,<shortcut-fulfillment>
標記會指定繫結捷徑的 intent
用於執行要求。
適用於開放式應用程式功能 BII 的內嵌清查
雖然內嵌清查通常是支援該 BII 的選用功能,但特定 BII (例如 OPEN_APP_FEATURE
) 需要使用內嵌清查。此常用的 BII 可讓使用者透過 Google 助理深層連結至特定的應用程式功能。開啟應用程式功能 BII 需要應用程式功能名稱的內嵌清查,藉此驗證使用者要求的功能是否存在,然後才透過深層連結將使用者導向應用程式。
以下 app/res/shortcuts.xml
範例檔案中的程式碼會實作此 BII,並以一個捷徑代表應用程式的訂單狀態功能:
<capability android:name="actions.intent.OPEN_APP_FEATURE">
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.MyClass">
<parameter
android:name="feature"
android:key="featureParam" />
</intent>
<!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.MyClass">
<parameter
android:name="HOME_SCREEN"
android:key="featureParam" />
</intent>
</capability>
<!-- Inline inventory for OPEN_APP_FEATURE. -->
<shortcut android:shortcutId="ORDER_STATUS">
<capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
<parameter-binding
android:key="feature"
android:value="@array/order_status_names" />
</capability-binding>
</shortcut>
res/values/arrays.xml
中的字串陣列資源 @array/order_status_names
會指定此功能的同義詞清單:
<resources>
<string-array name="order_status_names">
<item>Order status</item>
<item>Orders</item>
<item>Order history</item>
</string-array>
</resources>
有了上述功能,Google 助理就能為相同功能執行多種不同的詞組:
- 「Ok Google,在範例應用程式上顯示我的訂單狀態。」
- 「Ok Google,在範例應用程式上顯示我的訂單。」
- 「Ok Google,在範例應用程式上顯示我的訂單記錄。」
測試內嵌清查
檢查 Google 助理提供給應用程式的 BII 參數值以測試庫存,同時執行相關的應用程式動作功能。內嵌清查的運作方式,是將使用者繫結的 BII 參數值替換成相符內嵌清查捷徑的 shortcutId
。
舉例來說,START_EXERCISE
BII 功能可能會使用內嵌清查,將使用者提供的 BII 參數「跑步」轉譯成對應的運動 ID "CARDIO_RUN"
。
Google 助理外掛程式可讓您在測試裝置上預覽 Google 助理內嵌清查應用程式動作。請按照下列步驟操作,以使用外掛程式測試清查:
- 使用與內嵌清查相關聯的同義詞值,設定 BII 功能的清查繫結參數。
- 使用外掛程式觸發 BII,在測試裝置上叫用該 BII。
- 在應用程式動作執行要求期間,檢查 Google 助理提供給應用程式的結果參數值。