建立 shortcuts.xml

找出要實作的應用程式內功能和對應的內建意圖 (BII) 後，在 shortcuts.xml 資源檔案中定義 capability 元素，宣告功能支援的 BII。藉由宣告 BII 為 capability，即可在您的應用程式內註冊對該語意意圖的支援功能，並可透過 Google 助理使用該意圖的語音查詢執行要求。

Google 助理會使用自然語言處理從使用者查詢內容中擷取參數。內建意圖參考資料列有各種 BII 可以從相關使用者查詢內容中擷取的欄位。舉例來說，如果使用者說出「Ok Google，用範例應用程式向範例咖啡廳點一份披薩」，藉此在應用程式中叫用 actions.intent.ORDER_MENU_ITEM 功能，Google 助理就會從使用者要求中擷取下列 BII 參數：

• menuItem.name =「披薩」
• menuItem.inMenuSection.inMenu.forRestaurant.name =「範例咖啡廳」

Google 助理會將 BII 傳遞給 capability 中定義的執行要求 intent。功能中可以定義一或多個 intent 元素，以便處理多種使用者可能叫用 BII 的方式。例如您可以定義一個需要同時取得上述範例兩種 BII 參數的執行要求 intent。然後，您可以再定義一個需要單一 BII 參數的意圖 menuItem.name，以便在使用者提出較簡單的要求 (例如「Ok Google，用範例應用程式點一份披薩。」) 時顯示附近的餐廳選擇。

總覽

您需要使用放置在應用程式專案 res/xml 目錄中的 shortcuts.xml 檔案來設定應用程式動作，然後在應用程式資訊清單中建立 shortcuts.xml 的參照。按照以下步驟操作，在應用程式資訊清單中加入 shortcuts.xml 參考資料：

1. 在應用程式的資訊清單檔案 (AndroidManifest.xml) 中，找出意圖篩選器設為 android.intent.action.MAIN 動作和 android.intent.category.LAUNCHER 類別的活動。

2. 在 AndroidManifest.xml 同時含有 MAIN 及 LAUNCHER 兩種意圖篩選器的 Activity 中使用 <meta-data> 標記，藉此在 shortcuts.xml 內加入參考資料，如下所示：

   <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
   

上述範例為 APK 中的 xml/shortcuts.xml 檔案宣告 XML 資源。如要進一步瞭解如何設定捷徑，請參閱 Android 開發人員說明文件中的「建立靜態捷徑」。

您的 Android 專案內必須有 Jetpack 程式庫 androidx.core:core:1.6.0 (或以上版本)，以免在 shortcuts.xml 中定義應用程式動作功能時發生編譯錯誤。詳情請參閱「開始使用 Android Jetpack」。

靜態捷徑

定義 capability 時，您可以在 shortcuts.xml 中宣告靜態的 shortcut 元素以擴充功能。上傳版本至 Google Play 管理中心時，Google 助理就會擷取靜態捷徑。由於靜態捷徑只能藉由建立新版本的方式建立並更新，因此最適合用來突顯應用程式的一般活動和內容。

您可以使用靜態捷徑啟用下列應用程式動作功能：

• 功能快速鍵。建立捷徑，以便啟動內含預先定義 intent 參數值的 capability 執行個體。舉例來說，您可以宣告「開始執行」的應用程式捷徑，並用來在健身應用程式中叫用 START_EXERCISE BII 功能。

  這些捷徑內含 intent、shortLabel 和 longLabel 屬性，可透過 Google 助理或在 Android 啟動器中長按應用程式圖示等主動途徑當做方塊建議使用及執行。動作捷徑也可做為實體捷徑，詳情請參閱下文，方法是使用 <capability-binding> 標記將該捷徑與 capability 建立關聯。

• 實體捷徑。實體捷徑可以提供清單，列出 capability 語音查詢執行要求的支援參數值。比方說有一個實體捷徑設有運動類型 (「健行」、「跑步」等) 的清單，並繫結至 START_EXERCISE 功能的 exercise.name BII 參數。如果使用者的表達和某實體相符，shortcutId ID 就會傳遞至意圖，而不是原始的使用者查詢值。

  Entity 捷徑不會定義 intent、shortLabel 或 longLabel 屬性，因此不建議在主動途徑中使用。詳情請見「應用程式動作內嵌清查」。

功能結構定義

下表描述的是 shortcuts.xml 中 capability 元素的應用程式動作結構定義。加入標記時，除非有標註「非必要」，否則須提供所有屬性。

Shortcuts.xml 標記	包含於	屬性
<capability>	<shortcuts>	android:name app:queryPatterns (僅適用於自訂意圖)
<intent>	<capability>	android:action (非必要) android:targetClass (非必要) android:targetPackage (非必要) android:data (非必要)
<url-template>	<intent>	android:value
<extra>	<intent>	android:key android:value 僅適用於前景應用程式叫用
<parameter>	<intent>	android:name android:key android:mimeType (僅適用於自訂意圖) android:required (非必要) app:shortcutMatchRequired (非必要)
<data>	<parameter>	android:pathPattern (僅適用於網頁廣告空間)
<shortcut-fulfillment>	<capability>	僅適用於內嵌廣告空間
<parameter>	<shortcut-fulfillment>	android:name
<slice>	<capability>	僅適用於 Android Slice

功能結構定義說明

本節將說明 capability 結構定義元素。

<capability>

可以定義應用程式支援的應用程式動作意圖的 capability。shortcuts.xml 檔案中的每個 <capability> 元素都必須提供至少一項 <intent>，以便處理動作的執行要求。

屬性：

• android:name：內建意圖動作 ID (例如 actions.intent.CREATE_TAXI_RESERVATION)。如需支援的內建意圖清單，請參閱內建意圖參考資料。
• app:queryPatterns：預期使用者會為此意圖提出的查詢內容字串陣列資源。此屬性僅適用於自訂意圖，因為 BII 內已包含使用者表示他們嘗試執行工作時使用的常見方式，或是他們需要的資訊。

<intent>

定義使用者查詢內容應如何用應用程式內功能執行的 Android intent 元素。開發人員可以在一項 capability 裡提供多個 <intent> 標記。Google 助理會嘗試使用 capability 中的第一個 <intent> 完成使用者查詢，因為其中提供全部所需的參數。

屬性：

• android:action：意圖的 Action 類型。預設為 ACTION_VIEW。
• android:targetClass：目標活動類別，如："com.example.food.OrderActivity"
• android:targetPackage：含有目標活動類別的套件，如："com.example.food"
• android:data：如果 intent 中有宣告 <url-template>，則該標記會覆寫此欄位。

<url-template>

建構深層連結 URI 以便讓裝置開啟的範本。如果有該範本必要的所有參數，即可使用內建意圖參數擴充此範本。HTTP 網址範本範例請看 Wikipedia 網址範本條目。範本格式需遵守 RFC6570 URI 範本規格的規定。

以下提供部分網址範本值的範例：

Template	值	擴充值
https://example.com/test{?foo,bar}	"foo": "123" "bar": "456"	https://example.com/test?foo=123&bar=456
https://example.com/test?utm_campaign=appactions{&foo,bar}	"foo": "123" "bar": "456"	https://example.com/test?utm_campaign=appactions&foo=123&bar=456
https://example.com/test?utm_campaign=appactions{#foo}	"foo": "123"	https://example.com/test?utm_campaign=appactions#foo=123
myapp://example/{foo}	"foo": "123"	myapp://example/123

如果想進一步瞭解如何設定網址範本，請見執行要求內的網址範本。

<extra>

定義 intent 的其他資料。對應用程式動作來說，這個欄位只是用來為 capability 啟用前景應用程式叫用而已。

<parameter>

將 BII 參數對應至意圖參數值。詳情請參閱參數資料和比對。

屬性：

• android:name：慾和此 intent 參數建立關聯的 BII 參數名稱。此名稱應是 BII 參數的分葉層級欄位 (例如 foodObservation.aboutFood.name)。
• android:key：由開發人員定義的 BII 參數值金鑰。例如，您可以為 message.recipient.name BII 參數定義 contact_name。
• android:mimeType：參數的 mimeType，如 text/*。僅有自訂意圖的參數才必須提供此欄位。
• android:required：宣告使用者查詢內容在使用此意圖當做執行要求時，需不需要納入此參數。如果沒有參數可用，Google 助理會嘗試使用下一個為 capability 定義的 intent 執行使用者查詢內容。

<data>

建立網頁廣告空間和 parameter 的關聯。

屬性：

• android:pathPattern：使用網頁廣告空間傳回的 entity 網址模式。本屬性支援兩種萬用字元：

  • *：一個星號，符合緊接前方且 0 個以上的字元序列。

  • .*：半形句號後面加上星號，符合 0 個以上字元的任何序列。

  • 常值 * 和 \ 只需要逸出字元，然後可個別以 \\* 和 \\\\ 逸出。

<shortcut-fulfillment>

指定內嵌清查捷徑內已定義的 intent，以便讓執行要求使用特定參數。詳情請參閱「使用捷徑意圖的執行要求」。

<parameter> (<shortcut-fulfillment> 用)

非必要屬性，可用來將單一 BII 參數對應到內嵌清查捷徑執行要求。詳情請參閱「使用捷徑意圖的執行要求」。

屬性：

• android:name：和內嵌清查捷徑執行要求建立關聯的 BII 參數。此名稱應是 BII 參數的分葉層級欄位 (例如 menuItem.name)。

<slice>

使 Google 助理可內嵌符合此 capability 的查詢結果為 Android Slice。詳情請參閱「整合應用程式動作至 Android Slice」。

捷徑結構定義

以下表格說明含有 shortcut 元素，並用來啟用應用程式動作功能的屬性。加入標記時，除非有標註「非必要」，否則須提供所有屬性。

Shortcuts.xml 標記	包含於	屬性
<shortcut>	<shortcuts>	android:shortcutId android:shortcutShortLabel android:shortcutLongLabel (非必要) android:icon (非必要)
<intent>	<shortcut>	android:action android:targetClass (非必要) android:targetPackage (非必要) android:data (非必要)
<capability-binding>	<shortcut>	android:key
<parameter-binding>	<capability-binding>	android:key (非必要) android:value
<extra>	<shortcut>	android:name (非必要) android:value 僅適用於列舉參數比對。

捷徑結構定義說明

本節將說明 shortcut 結構定義元素。

<shortcut>

shortcuts.xml 內定義的 Android <shortcut>，有和應用程式動作相關的屬性。shortcutShortLabel 和 shortcutLongLabel 欄位的字串值會透過 APK 的字串資源參照。

屬性：

• android:shortcutId：此捷徑的 ID。
• android:shortcutShortLabel：代表簡短快速指令語句的字串資源。舉例來說，"@string/callDavidShort" 代表「撥號給 David」的值。
• android:shortcutLongLabel：代表長快速指令語句的字串資源。舉例來說，"@string/callDavidLong" 代表「撥語音通話給 David」的值。

<intent>

和此捷徑有關聯的 Android 意圖。使用者透過語音或觸控啟動此捷徑時，系統會排除此 intent。

shortcut 意圖屬性和 capability intent 屬性相同。

<capability-binding>

將 shortcut 和應用程式動作 capability 建立關聯。將此元素加入 shortcut後，即可讓語音執行要求使用 Assistant。

屬性：

• android:key：這個 shortcut 繫結的 capability 的 android:name 屬性。例如：actions.intent.CREATE_TAXI_RESERVATION。

<parameter-binding>

非必要屬性，可將 shortcut 和應用程式動作 capability 的單一參數建立關聯。如果為 shortcut 定義 parameter-binding，則可使用此捷徑為 BII 參數提供內嵌清查實體。詳情請見「應用程式動作內嵌清查」。

屬性：

• android:key：和此捷徑建立關聯的 capability BII 參數名稱。例如：foodObservation.aboutFood.name。
• android:value：entity 的值。可為單一 entity 或資源清單。

<extra>

捷徑的 extra 軟體包資料。只有 sameAs 是與應用程式動作 shortcut 元素相關的資料。sameAs 網址會參照明確識別實體的參照網頁。只有在意圖參數類型是 schema.org/Enumeration 子類型時，才能用來識別列舉值。類型為 schema.org/Enumeration 子類型的參數欄位 (如 MealTypeBreakfast) 必須提供此項目。

屬性：

• android:key：應用程式動作支援值為：sameAs
• android:value：sameAs 網址值

詳情請見「比對列舉參數值」。

意圖執行要求選項

在 <capability> 中定義 intent 元素，以宣告 Google 助理如何回應或執行符合該功能的使用者語音指令。根據您的應用程式導覽架構而定，設定 intent 在應用程式內啟動執行要求目的地的方法不只一種。

您可以使用下列的執行要求選項：

• 明確意圖：針對 intent 定義 targetClass 和 targetPackage 屬性，以啟動特定的應用程式元件。這是應用程式動作執行要求方法的建議做法。

• 深層連結：在 intent 元素內定義 <url-template> 標記，以使用 Android 深層連結啟動應用程式目的地。如果您的應用程式導覽已必須使用深層連結，此方法便非常實用。

• 意圖資料：您可以在 intent android:data 屬性中提供執行要求 URI。如果 intent 內也有定義的標記，則此欄位會由 <url-template> 資料覆寫。

參數資料和比對

根據預設，Google 助理會將使用者查詢內容中擷取的 BII 參數，以 capability 內定義的 Android intent extra 資料方式傳送至應用程式。

此外，您也可以在包含動態參數預留位置的 capability 中宣告 <url-template> 標記。此範本會使用應用程式連結網址、自訂配置或意圖網址對應到您的其中一個 Android 活動。

使用意圖 Extra

以下範例將展示為 capability 執行要求定義的明確意圖：

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

以上述範例為例，如果是「Ok Google，用範例應用程式點一份拿鐵。」的使用者查詢內容，應用程式會收到叫用以下元件的 intent：targetPackage、targetClass。元件會收到額外功能，以及 key = ”menu”、value = ”latte”。

為 Android 深層連結使用網址範本

如果應用程式已可處理應用程式連結網址，您就可以利用動態參數，在 intent 中定義 <url-template>，以針對執行要求產生 Android 深層連結。以下範例將定義 <url-template>：

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent>
    <url-template android:value="myapp://order{?menu}" />
    <parameter android:name="menuItem.name" android:key="menu" />
  </intent>
</capability>

以上述範例為例，如果是「Ok Google，用範例應用程式點一份拿鐵。」的使用者查詢內容，應用程式會收到以下產生的網址：「myapp://order?menu=latte」。

如果想將 BII 參數對應到網址內的位置，請用 <parameter> 標記的 android:name 屬性。此屬性對應您想取代為使用者提供資訊的網址範本內的 android:key 值。<url-template> 內必須有 android:key 值，左右須用大括號 ({}) 包住。

比對列舉參數值

部分 BII 參數可以為執行要求意圖提供列舉值，例如 RECORD_FOOD_OBSERVATION BII 的支援文字值。針對這些參數，Google 助理會比對使用者查詢內容 (「Breakfast」) 和 sameAs 值與列舉結構定義網址 (https://schema.googleapis.com/MealTypeBreakfast) 相符的實體。如要為支援的 entity 建立列舉值關聯，請在 shortcut 中宣告 sameAs 關聯。以下範例會展示內嵌實體捷徑的 sameAs 關聯：

<shortcut android:shortcutId="meal_breakfast" >
    <capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
        <parameter-binding android:key="foodObservation.forMeal" />
    </capability-binding>
    <extra
        android:key="sameAs"
        android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>

<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
  <intent targetPackage="com.example.app" targetClass="com.example.app.Class">
    <parameter android:name="foodObservation.forMeal" android:key="for_meal" />
  </intent>
</capability>

在上述範例中，如果 RECORD_FOOD_OBSERVATION 功能會觸發符合「早餐」餐點類型的內容，則以下額外功能會和執行要求 intent 一起傳送：

• key = "for_meal"
• value = "meal_breakfast"

功能

shortcuts.xml 提供下列應用程式動作功能。

應用程式動作內嵌目錄

對於部分 BII 參數而言，您可以使用捷徑引導實體擷取內容至 shortcuts.xml 中指定的支援實體組合，稱為內嵌清查。詳情請參閱「內嵌清查」。

應用程式動作網站目錄

對於部分 BII，您可使用網站清查方法產生執行要求網址。網頁廣告空間會使用您的網站偵測應用程式動作執行要求網址。如果您的網站非常知名，而應用程式內的深層連結是可公開存取的網站內容，就非常適合使用這個功能。

詳情請見「網站清查」。

自訂意圖

您可在 shortcuts.xml 內宣告自訂意圖，以使用語音在應用程式中啟用不符合可用 BII 的功能。自訂意圖和 BII 定義的功能雖然十分相似，但是必須在 shortcuts.xml 內額外提供兩項屬性：

• app:queryPatterns：為自訂意圖宣告其他查詢模式的陣列資源。

• android:mimeType：自訂意圖參數類型。如果是已知的參數類型，則 BII 不一定需要提供此欄位。若是自訂意圖參數，則必須宣告支援語意類型。

詳情請參閱「自訂意圖」。