找出要實作的應用程式功能和對應的內建意圖 (BII) 後,請在 shortcuts.xml
資源檔案中定義 capability
元素,宣告功能支援的 BII。宣告 BII 為 capability
,即可在您的應用程式內註冊對該語意意圖的支援功能,並可透過 Google 助理,使用該意圖的語音查詢執行要求。
Google 助理會使用自然語言,處理從使用者查詢內容中擷取參數。內建意圖參考資料列出了許多欄位,BII 可以從相關使用者查詢內容中擷取各欄位。舉例來說,如果使用者說出「Ok Google,請問 ExampleApp 上週五我吃了什麼午餐」,藉此在應用程式中叫用 [actions.intent.GET_FOOD_OBSERVATION
][] 功能,Google 助理會從使用者要求中擷取以下 BII 參數:
foodObservation.forMeal
= "https://schema.googleapis.com/MealTypeLunch"foodObservation.startTime
= "2024-09-06T00:00:00"foodObservation.endTime
= "2024-09-06T23:59:59"
Google 助理會將 BII 參數傳遞給 capability
中定義的執行要求 intent
。功能物件中可定義一或多個 intent
元素,因應使用者叫用 BII 的各種方式。例如,您可以定義一個需要用到上述示例中兩種 BII 參數的執行要求 intent
。接著,您可以定義第二個意圖,需要取得單一 BII 參數 foodObservation.forMeal
,以便回報特定日期的所有餐點,例如「Ok Google,請問 ExampleApp 我午餐吃了什麼?」
總覽
設定應用程式動作的方法,是在應用程式專案的 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> |
|
<shortcut-fulfillment> |
<capability> |
僅適用於內嵌目錄 |
<parameter> |
<shortcut-fulfillment> |
android:name |
<slice> |
<capability> |
僅適用於 Android Slice |
能力結構定義說明
本節將說明 capability
結構定義元素。
<capability>
capability
可定義您應用程式支援的應用程式動作意圖。shortcuts.xml
檔案中的每個 <capability>
元素都必須提供至少一項 <intent>
,用於處理動作的執行要求。
屬性:
android:name
:內建意圖動作 ID (例如 [actions.intent.GET_FOOD_OBSERVATION
][])。如需支援的內建意圖清單,請參閱內建意圖參考資料。app:queryPatterns
:您預期使用者會對該意圖執行的查詢的字串陣列資源。此屬性僅適用於自訂意圖,因為 BII 內已包含數個常見方式模型,使用者表示會根據這些方式嘗試執行任務或尋找資訊。
<intent>
Android intent
元素,定義應如何使用應用程式內功能執行使用者查詢。開發人員可以在 capability
中提供多個 <intent>
標記。Google 助理會嘗試使用 capability
中的第一個 <intent>
(已為其提供所有必要參數) 執行使用者查詢。
屬性:
android:action
:意圖的Action
類型。預設為ACTION_VIEW
。android:targetClass
:目標活動類別,如:"com.example.exercise.ExerciseActivity"
android:targetPackage
:含有目標活動類別的套件,如:"com.example.exercise
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
的 extra 資料。對應用程式動作來說,這個欄位只是用來為 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
,執行使用者查詢。
<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"
代表「Call David」的值。android:shortcutLongLabel
:代表長快速指令語句的字串資源。舉例來說,"@string/callDavidLong"
代表「Make an audio call to David」的值。
<intent>
和此快速指令相關聯的 Android 意圖。當使用者以語音或觸控方式啟動這個快速指令時,系統會排除此 intent
。
shortcut
意圖屬性和 capability
intent
屬性相同。
<capability-binding>
將 shortcut
與應用程式動作 capability
建立關聯。將此元素加入 shortcut
後,即可使用 Assistant
,透過語音執行要求。
屬性:
android:key
:這個shortcut
繫結的capability
的android:name
屬性。例如:actions.intent.START_EXERCISE
。
<parameter-binding>
非必要屬性,可將 shortcut
與應用程式動作 capability
的單一參數建立關聯。如果為 shortcut
定義了 parameter-binding
,則可使用此快速指令,為 BII 參數提供內嵌目錄實體。詳情請參閱「應用程式動作內嵌目錄」。
屬性:
android:key
:和此快速指令相關聯的capability
BII 參數名稱。例如:exercise.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.START_EXERCISE">
<intent
android:targetPackage="com.example.myapp"
android:targetClass="com.example.myapp.ExerciseActivity">
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</capability>
以上述範例為例,如果是「Ok Google,開始跑步」的使用者查詢,應用程式會收到叫用以下元件的 intent
:targetPackage
、targetClass
。元件會接收 Extra、key = "exercise"
和 value = "Running"
。
為 Android 深層連結使用網址範本
如果應用程式已能處理應用程式連結網址,您可以利用動態參數,在 intent
中定義 <url-template>
,為執行要求產生 Android 深層連結。以下範例會定義 <url-template>
:
<capability android:name="actions.intent.START_EXERCISE">
<intent>
<url-template android:value="myapp://start{?exercise}" />
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</capability>
以上述範例為例,如果使用者查詢為「Ok Google,開始跑步」,應用程式會收到系統產生的網址:「myapp://start?exercise=Running」。
如果想將 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
能力物件會觸發符合「breakfast」餐點類型的內容,則以下 Extra 會和執行要求 intent
一起送出。
key = "for_meal"
value = "meal_breakfast"
功能
shortcuts.xml
中提供了下列應用程式動作功能。
應用程式動作的內嵌目錄
就部分 BII 參數而言,您可以使用快速指令,將實體擷取內容引導至 shortcuts.xml
中指定的一組支援實體,稱為內嵌目錄。詳情請參閱「內嵌目錄」。
自訂意圖
您可以在 shortcuts.xml
中宣告自訂意圖,使用語音指令在應用程式中啟用與可用 BII 不相符的功能。雖然與 BII 定義的功能十分相似,但自訂意圖必須在 shortcuts.xml
內新增兩項額外屬性:
app:queryPatterns
:為自訂意圖宣告不同查詢模式的陣列資源。android:mimeType
:此為自訂意圖的參數類型。就 BII 而言,參數類型為已知狀態,因此不需要此欄位。如果是自訂意圖參數,則必須宣告支援的語意類型。
詳情請參閱「自訂意圖」。