カスタム インテント

すべてのアプリはそれぞれ異なるため、すべてのアプリの機能が利用可能な App Actions 組み込みインテントと一致するわけではありません。アプリの機能に対応する組み込みインテント(BII)がない場合は、代わりにカスタム インテントを使用することにより、App Actions でアプリを拡張できます。

BII と同様に、カスタム インテントは shortcuts.xml のスキーマに従い、アシスタントと定義済みのフルフィルメントとの間の接続ポイントとして機能します。カスタム インテントには、対応するフルフィルメントのパラメータにマッピングできるインテント パラメータがあります。

BII とは異なり、カスタム インテントには、ユーザーが発話する可能性のあるクエリの例を記述するクエリパターンが必要です。このアプローチは、各ユーザーがインテントを表現する一般的な方法をモデル化する組み込みインテントとは異なります。

制限事項

カスタム インテントには次の制限があります。

  • カスタム インテントの名前を actions.intent で始めることはできません。
  • カスタム インテントの名前は、アプリのカスタム インテント名の中で一意にする必要があります。
  • Google アシスタントによるパラメータ抽出に使用できるのは、特定のデータタイプのみです。サポートされているタイプのリストについては、サポートされているタイプをご覧ください。
  • 1 つのクエリでは最大 2 つのテキスト パラメータを使用できます。この上限は他のデータタイプには適用されません。
  • カスタム インテントでは en-US ロケールのみがサポートされています(デバイスとアシスタントの両方の言語設定が一致している必要があります)。

サポートされているタイプ

カスタム インテントは、パラメータ抽出に次の schema.org タイプをサポートしています。

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

カスタム インテントを使用した App Actions の定義

組み込みインテントを使用する他の App Actions と同様に、shortcuts.xml<capability> 要素にカスタム インテントを定義します。

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>

カスタム インテントに名前を付けるときは、組み込みインテントと Android インテント(両者は異なります)の両方と区別するために、プレフィックス custom.actions.intent を使用することをおすすめします。カスタム インテントの名前を actions.intent で始めることはできません。この名前空間は組み込みインテント用に予約されています。

パラメータごとに、パラメータの意味を最もよく表す、サポートされている 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>
...

shortcuts.xml のショートカットの定義では、組み込みインテントの場合と同じ形式をカスタム インテントに使用します。次のコードは、参照されるクエリパターンを使用して SCHEDULE_APPOINTMENT カスタム インテントをトリガーする App Action と、apptType パラメータの定義済みの値 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>
    ...

shortcuts.xml のショートカットの定義では、組み込みインテントの場合と同じ形式をカスタム インテントに使用します。次のコードは、参照されるクエリパターンを使用して SCHEDULE_APPOINTMENT カスタム インテントをトリガーする App Action と、apptType パラメータの定義済みの値 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 で指定された一連のサポートされているエンティティへのエンティティ抽出をガイドできます。

クエリパターン

使用する各カスタム インテントには、そのインテントで想定されるユーザーからの一連のクエリが必要です。このアプローチは、ユーザーが実行しようとしているタスクや探している情報を表現する一般的な方法でクエリがすでにモデル化されている組み込みインテントとは異なります。

Android リソース ファイル(通常は /res/values/strings.xml)で、クエリパターンを文字列配列のアイテムとして指定します。App Action が呼び出されると、Google アシスタントは、ユーザーの意図をフルフィルメントと照合する一環として、ユーザークエリをクエリパターンと照合します。指定した各クエリパターンは、対応するカスタム インテントに対して有効と見なされるフレーズを表します。

カスタム インテントのクエリパターンを指定する際は、各パターンでは「open ExampleApp and」や「start ExampleApp and」などの明示的呼び出しを想定してください。たとえば、次のユーザークエリを検討してください。

  • 「Hey Google, open ExampleGameApp and start making a cake.」
  • 「Hey Google, open ExampleGameApp and start making an apple pie.」
  • 「Hey Google, start ExampleGameApp and craft 5 cake items.」
  • 「Hey Google, use ExampleGameApp to produce cake 5 times.」

ユーザークエリと一致させるには、呼び出しフレーズの後のクエリ部分を含むクエリパターンを指定します。クエリから抽出する情報(ユーザーが指定したテキストや数値など)については、クエリパターン内のプレースホルダで対応しているインテント パラメータに値を割り当てます。

クエリパターンでパラメータを参照するには、パターンのパラメータの名前に $ を追加します。たとえば、<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」が有効なクエリとなります。