自訂意圖

每個應用程式都有不同之處，因此並非所有應用程式功能都有相符的應用程式動作內建意圖 (BII) 可用。如果您的應用程式功能沒有 BII，您可以改用自訂意圖，利用應用程式動作擴充應用程式。

自訂意圖和 BII 相同，也會遵守 shortcuts.xml 結構定義，扮演 Google 助理和定義執行要求之間的連接點。自訂意圖裡也有意圖參數，這些參數可以對應到相應執行要求裡的參數。

和 BII 不同的是，自訂意圖必須使用查詢模式，說明使用者可能會提出的查詢範例。這個方法和內建意圖不同，後者會對使用者表達該意圖的常用方式來建立模型。

限制

自訂意圖具有以下幾種限制：

  • 自訂意圖的名稱不得以 actions.intent 開頭。
  • 應用程式的自訂意圖名稱皆不得重複。
  • Google 助理只能擷取特定資料類型的參數 (請參閱「支援的類型」)。
  • 自訂意圖必須包含可用的查詢模式範例 (請參閱「查詢模式」)。
  • 每項查詢最多支援兩個文字參數。其他資料類型無此限制。
  • 自訂意圖僅支援 en-US 語言代碼。此外，裝置和 Google 助理的語言設定必須一致。

支援的類型

擷取參數時，自訂意圖支援以下 schema.org 類型：

  • https://schema.org/Text
  • https://schema.org/Date
  • https://schema.org/Time
  • https://schema.org/Number

使用自訂意圖定義應用程式動作

和其他使用 BII 的應用程式動作相同，您需要在 shortcuts.xml 的 <capability> 元素中定義自訂意圖。

至於功能，則在 <shortcuts> 根元素內定義。定義 <shortcuts> 元素時，請為您要存取的屬性加入命名空間，如以下範例所示：

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

在 android:name 屬性內提供自訂意圖名稱，並在 queryPatterns 屬性內參照查詢模式資源檔案。

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

自訂意圖名稱不得以 actions.intent 開頭，因為系統會預留這個命名空間給 BII 使用。所以，您為自訂意圖命名時，請改用前置字串 custom.actions.intent 來區別自訂意圖與 BII 和 Android 意圖；BII 和 Android 意圖的運作方式不同。

請針對每個參數，提供最能準確描述參數含意的支援 schema.org 類型。舉例來說，您可以用 https://schema.org/Date 說明您預期收到的日期：

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

使用與 BII 相同的格式，在 shortcuts.xml 中定義自訂意圖的捷徑。

以下程式碼描述的應用程式動作會針對 apptType 參數，使用參照的查詢模式觸發 SCHEDULE_APPOINTMENT 自訂意圖，並使用一組定義過的值，也就是 DRIVERS_LICENSE 和 VEHICLE_REGISTRATION。

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

您可以使用內嵌目錄設定自訂意圖參數，將擷取的實體引導到 shortcuts.xml 指定的一組支援實體中。

查詢模式

您使用的每個自訂意圖，都需要具備您預期使用者會對該意圖執行的一組查詢。這和 BII 使用的方式不同；在 BII 中，查詢已根據使用者執行任務或尋找資訊時常見的表達方式來建立模型。

請在 Android 資源檔案 (通常是 /res/values/strings.xml) 中，將查詢模式指定為字串陣列中的項目。當系統叫用應用程式動作時，Google 助理會在比對使用者的執行要求意圖時，按照您的查詢模式檢查使用者的查詢內容。您提供的每項查詢模式，都代表您認為適用於對應自訂意圖的詞組。

為自訂意圖提供查詢模式時，應要求每項模式都遵守明確的叫用方式，例如「開啟範例應用程式，然後」或「啟動範例應用程式，然後」。舉例來說，請考慮使用以下使用者查詢內容：

  • 「Ok Google，開啟範例遊戲應用程式，然後開始做蛋糕。」
  • 「Ok Google，開啟範例遊戲應用程式，然後開始做蘋果派。」
  • 「Ok Google，啟動範例遊戲應用程式，然後製作 5 個蛋糕項目。」
  • 「Ok Google，使用範例遊戲應用程式產生蛋糕 5 次。」

如需比對使用者的查詢內容，請確認您提供的查詢模式含有叫用詞組後方的查詢部分。如果是想從查詢中擷取的資訊 (如使用者提供的文字或數字)，則需要將值指派給查詢模式中含有預留位置的對應意圖參數。

如要在查詢模式內參照參數，請在模式內的參數名稱中加入 $。舉例來說，如果想為參數建立預留位置值，如 <parameter name="date1" ... (在 actions.xml 中) 或 <parameter android:name="date1" ... (在 shortcuts.xml 中)，您需要使用 $date1。

以下程式碼描述的查詢模式會比對上述的使用者查詢，並擷取項目名稱值，及需要製作的項目數量：

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

查詢模式支援條件式，例如：set (an)? appointment $date $time。在此情況下，「set appointment today at noon」和「set an appointment today at noon」都是有效的查詢內容。