建立 shortcuts.xml

找出要實作的應用程式功能和對應的內建意圖 (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,詢問範例應用程式我吃了午餐吃什麼」。

總覽

設定應用程式動作的方法,是在應用程式專案的 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 (非必要)

<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"

"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 的 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>

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" 代表「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 繫結的 capabilityandroid:name 屬性。例如:actions.intent.START_EXERCISE

<parameter-binding>

非必要屬性,可將 shortcut 與應用程式動作 capability 的單一參數建立關聯。如果為 shortcut 定義了 parameter-binding,則可使用此快速指令,為 BII 參數提供內嵌目錄實體。詳情請參閱「應用程式動作內嵌目錄」。

屬性:

  • android:key:和此快速指令相關聯的 capability BII 參數名稱。例如:exercise.name
  • android:valueentity 的值。可以是單一 entity 或資源清單。

<extra>

快速指令的 extra 套件資料。只有 sameAs 是與應用程式動作 shortcut 元素相關的唯一資料。sameAs 網址會參照明確識別該實體的參照網頁。只有在意圖參數類型是 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 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 叫一杯拿鐵」的使用者查詢,應用程式會收到叫用以下元件的 intenttargetPackagetargetClass。元件會接收 Extra、key = "exercise"value = "Running"

如果應用程式已能處理應用程式連結網址,您可以利用動態參數,在 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 而言,參數類型為已知狀態,因此不需要此欄位。如果是自訂意圖參數,則必須宣告支援的語意類型

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