建立 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 同時含有 MAINLAUNCHER 兩種意圖篩選器的 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 功能。

    這些捷徑內含 intentshortLabellongLabel 等屬性,可透過 Google 助理或在 Android 啟動器中長按應用程式圖示等主動途徑當做方塊建議使用及執行。動作捷徑也可以當做實體捷徑使用,詳情如下所示,您可以使用 <capability-binding> 標記將其和 capability 建立關聯。

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

    Entity 捷徑無法定義 intentshortLabellongLabel 屬性,因此不會在主動途徑中推薦使用。詳情請見「應用程式動作內嵌清查」。

功能結構定義

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

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>

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

屬性:

<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 範本規格

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

範本 擴充值
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>,並有和應用程式動作相關的屬性。shortcutShortLabelshortcutLongLabel 欄位的字串值會透過 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 繫結的 capabilityandroid:name 屬性。例如:actions.intent.CREATE_TAXI_RESERVATION

<parameter-binding>

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

屬性:

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

<extra>

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

屬性:

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

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

意圖執行要求選項

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

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

  • 明確意圖:為 intent 定義 targetClasstargetPackage 屬性,藉此啟動特定的應用程式元件。這是應用程式動作執行要求方法的建議做法。

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

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

參數資料和比對

Google 助理預設會從使用者查詢內容中擷取 BII 參數,並以 capability 內定義的 Android intentextra 資料方式傳送給您的應用程式。

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

使用意圖額外功能

以下範例將展示為 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,用範例應用程式點一份拿鐵。」的使用者查詢內容,應用程式會收到叫用以下元件的 intenttargetPackagetargetClass。元件會收到額外功能,以及 key = ”menu”value = ”latte”

如果應用程式已可以透過動態參數處理應用程式連結網址,則您可以在 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 助理會為這些參數將使用者查詢內容 (「早餐」) 和有符合列舉結構定義網址 (https://schema.googleapis.com/MealTypeBreakfast) 的 sameAs 值的實體進行比對。為了和支援 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 不一定需要提供此欄位。若是自訂意圖參數,則必須宣告支援語意類型

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