建立 shortcuts.xml

找出要實作的應用程式功能和對應的內建意圖 (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 的參照：

  1. 在應用程式的資訊清單檔案 (AndroidManifest.xml) 中，找出意圖篩選器設為 android.intent.action.MAIN 動作和 android.intent.category.LAUNCHER 類別的活動。

  2. 在 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>

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>，含有與應用程式動作相關的某些屬性。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"。

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

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