找出要實作的應用程式功能和對應的內建意圖 (BII) 後,請在 shortcuts.xml
資源檔案中定義 capability
元素,宣告功能支援的 BII。宣告 BII 為 capability
,即可在您的應用程式內註冊對該語意意圖的支援功能,並可透過 Google 助理,使用該意圖的語音查詢執行要求。
Google 助理會使用自然語言,處理從使用者查詢內容中擷取參數。內建意圖參考資料列出了許多欄位,BII 可以從相關使用者查詢內容中擷取各欄位。例如,如果使用者
藉由以下方式,在應用程式中叫用 [actions.intent.GET_FOOD_OBSERVATION
][] 功能:
說出:「Ok Google,詢問範例應用程式我上週午餐吃了哪些食物」、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,詢問範例應用程式我吃了午餐吃什麼」。
capability
都必須具備無需參數即可執行使用者要求的「備用」intent
。這類備用意圖可以增進使用者體驗,即使收到不明確的使用者查詢 (例如「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,用 ExampleApp 叫一杯拿鐵」的使用者查詢,應用程式會收到叫用以下元件的 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 而言,參數類型為已知狀態,因此不需要此欄位。如果是自訂意圖參數,則必須宣告支援的語意類型。
詳情請參閱「自訂意圖」。