內嵌清單

為 Android 應用程式實作應用程式動作時，您可能會發現自己需要處理主題的變化版本要求。舉例來說，如果您的健身應用程式實作 START_EXERCISE 內建意圖 (BII)，讓使用者可以問 Google 助理「Ok Google，在範例應用程式開始跑步」等事項，以開始多種不同的健身活動。

若要執行此意圖，您的要求必須比對邏輯以處理各種類型的運動，包括「慢跑」、「短跑」或「賽跑」等變化版本。隨著支援的健身增加，此邏輯很快就變得繁瑣。

如為支援的 BII (例如 START_EXERCISE)，您可以使用內嵌清查來避免這種複雜的比對邏輯。內嵌清查是 shortcuts.xml 中定義的一組靜態 Android 捷徑，代表應用程式中的功能和內容。

每個捷徑都包含一個項目 ID，以及代表使用者如何參照項目的同義詞清單。在叫用期間，BII 會比較使用者提供的 BII 參數與同義詞清單。找到相符項目時，BII 參數會更新為相符捷徑的項目 ID。

內嵌清查可讓 Google 助理在應用程式動作叫用期間，簡化提供給應用程式的 BII 參數值。

內嵌清查的功能和 BII 參數的對照表類似，並且使用您定義的項目 ID，來表示使用者在應用程式中參照功能或內容的不同方式。這種做法可讓執行要求從 BII 參數預期項目 ID，藉此簡化應用程式的要求比對邏輯。

相關限制和替代方案

內嵌清查捷徑有下列限制：

• 捷徑限制：每個應用程式最多可以定義 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 助理內嵌清查應用程式動作。請按照下列步驟操作，以使用外掛程式測試清查：

1. 使用與內嵌清查相關聯的同義詞值，設定 BII 功能的清查繫結參數。
2. 使用外掛程式觸發 BII，在測試裝置上叫用該 BII。
3. 在應用程式動作執行要求期間，檢查 Google 助理提供給應用程式的結果參數值。