カスタム インテント

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

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

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

制限事項

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

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

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

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

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

カスタム インテントを使用して App Actions を定義する

BII を使用する他の 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>

カスタム インテントの名前を actions.intent で始めることはできません。この名前空間は BII 用に予約されています。代わりに、カスタム インテントに名前を付けるときは、BII と Android インテント(両者は異なります)の両方と区別するために、プレフィックス custom.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>
...

BII のショートカットと同じ形式を使用して、shortcuts.xml でカスタム インテントのショートカットを定義します。

次のコードは、参照されるクエリパターンを使用して SCHEDULE_APPOINTMENT カスタム インテントをトリガーし、apptType パラメータの定義済みの値 DRIVERS_LICENSEVEHICLE_REGISTRATION を使用する App Action を記述しています。

<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 とは異なります。

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

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

  • 「Hey Google, open Example Game App and start making a cake.」
  • 「Hey Google, open Example Game App and start making an apple pie.」
  • 「Hey Google, start Example Game App and craft 5 cake items.」
  • 「Hey Google, use Example Game App 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」が有効なクエリとなります。