辨別要實作的應用程式功能和對應的內建意圖 (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
參考資料:
在應用程式的資訊清單檔案 (
AndroidManifest.xml
) 中,找出意圖篩選器設為android.intent.action.MAIN
動作和android.intent.category.LAUNCHER
類別的活動。在
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> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
僅適用於前景應用程式叫用。 |
<parameter> |
<intent> |
|
<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 範本規格的規定。
以下提供部分網址範本值的範例:
範本 | 值 | 擴充值 |
---|---|---|
https://example.com/test{?foo,bar} |
"foo": "123"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
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>
屬性:
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> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
僅適用於列舉參數比對。 |
捷徑結構定義說明
本節將說明 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>
標記。此範本會使用應用程式連結網址、自訂 Scheme 或意圖式網址,對應至其中一個 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,用範例應用程式點一份拿鐵。」的使用者查詢內容,應用程式會收到叫用以下元件的 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 助理會為這些參數將使用者查詢內容 (「早餐」) 和有符合列舉結構定義網址 (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 不一定需要提供此欄位。若是自訂意圖參數,則必須宣告支援語意類型。
詳情請參閱「自訂意圖」。