インライン インベントリ

Android アプリに App Actions を実装すると、1 つのテーマのバリエーションであるリクエストを処理する必要が生じる場合があります。たとえば、フィットネス アプリに START_EXERCISE 組み込みインテント(BII)を実装し、ユーザーがアシスタントに「OK Google, Example App でランニングを開始」などと話しかけてさまざまなワークアウトを開始できるようにするとします。

このインテントを満たすには、「ジョギング」、「スプリント」、「レース」などのバリエーションを含むワークアウトをそれぞれ処理するためのリクエスト マッチング ロジックが必要です。このロジックは、サポートするワークアウトのタイプが増えると、たちまち煩雑になります。

サポートされている BII(START_EXERCISE など)では、インライン インベントリを使用することで、このような複雑な照合ロジックを回避できます。インライン インベントリは、shortcuts.xml で定義された一連の静的 Android ショートカットで、アプリの機能とコンテンツを表します。

各ショートカットには、アイテム ID と、ユーザーがそのアイテムを参照するさまざまなバリエーションを表す類義語のリストが含まれています。呼び出しの際に、BII はユーザーが指定した BII パラメータを類義語リストと比較します。一致するものが見つかると、BII パラメータは、一致するショートカットのアイテム ID に更新されます。

インライン インベントリを使用すると、Google アシスタントは App Action の呼び出し時にアプリケーションに提供される BII パラメータ値を簡素化できます。

インライン インベントリは、BII パラメータのルックアップ テーブルのように機能し、ユーザーが定義したアイテム ID を使用してアプリの機能やコンテンツを参照するさまざまな方法を表します。フルフィルメントが BII パラメータからアイテム ID を予測できるようにすることで、アプリのリクエスト照合ロジックを簡素化します。

インライン インベントリのユーザーフロー図
図 1. アプリでサポートされているエクササイズ タイプのユーザーが指定したワークアウト名を、インライン インベントリを使用して解釈する START_EXERCISE ケーパビリティのフロー図。

制限事項と代替策

インライン インベントリ ショートカットには次の制限があります。

  • ショートカットの上限: アプリごとに最大 1,000 個のインライン インベントリ ショートカットを定義できます。
  • 類義語の上限: 各インライン インベントリ ショートカットには、最大 20 個の類義語値を含めることができます。
  • 静的定義: インライン インベントリ ショートカットは shortcuts.xml で静的に宣言され、ユーザー向けに更新するにはアプリの新しいバージョンを公開する必要があります。

静的構成の要件を考慮すると、インライン インベントリは、メニュー アイテム、バスのルート、飲み物のサイズなど、変更頻度の低いパーソナライズされていないアプリ情報をアシスタントに拡張する場合に最適です。他の種類のコンテンツについては、以下の代替策を検討してください。

  • ウェブ インベントリ: アシスタントは、ユーザークエリをサポートされているアプリ コンテンツ ID と照合する際に、公開されているウェブ コンテンツをクエリできます。ウェブ インベントリ クエリは、呼び出し中にリアルタイムで行われるため、商品カタログやソーシャル メディアの投稿など、頻繁に更新されるコンテンツをアシスタントに拡張できます。

  • 動的ショートカット: パーソナライズされたアプリ コンテンツのインベントリをアシスタントに拡張します。動的ショートカットを使用すると、ユーザーは料理注文アプリでお気に入りの飲み物を再注文する、メモ作成アプリでショッピング リストを表示するなど、一般的なアクションをすばやくリプレイできます。

インライン インベントリを作成する

インライン インベントリを使用すると、ユーザーがアプリのコンテンツと機能をリクエストするさまざまな方法を、アプリケーションが期待する予測可能な識別子にアシスタントで変換する便利な方法が提供されるため、開発が簡単になります。たとえば、アプリが音声を使用して開始できるさまざまなワークアウトを提供しており、ユーザーが同じエクササイズ タイプに対して次のリクエストを行うと想定します。

  • OK Google, Example App でランニングを開始
  • OK Google, Example App でジョギングを開始。

インライン インベントリ ショートカットでは、shortcutId"CARDIO_RUN"(アプリが想定するエクササイズ ID)に設定します。次に、shortcutId に関連付けられた類義語として「ランニング」と「ジョギング」を指定します。次に、ユーザーが上記のクエリを使用して App Action をトリガーすると、フルフィルメント インテントの生成時に、アシスタントは BII パラメータの ID "CARDIO_RUN" を使用します。

サンプル app/res/shortcuts.xml ファイルの次のスニペットは、このケースを実装します。

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

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

上記のサンプルで、インライン インベントリ shortcut<capability-binding> 要素内で <parameter-binding> タグを宣言し、<capability> で定義されている exercise.name BII パラメータにバインドしています。

文字列配列リソース @array/run_names は、アシスタントが認識して "CARDIO_RUN" アイテム ID にマッピングする res/values/arrays.xml の類義語のリストを指定します。

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

ケーパビリティに <url-template> が指定されている場合、一致する値の shortcutId が、生成された URL のパラメータに対応するプレースホルダに挿入されます。サンプル app/res/shortcuts.xml ファイルの次のコードは、このケースを実装しています。

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://workout{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

上記のサンプルでは、アシスタントはフルフィルメント ディープリンク myapp://workout?exercise=CARDIO_RUN を生成します。

ショートカット インテントを使用したフルフィルメント

デフォルトでは、ショートカットは、ショートカットの <capability-binding> タグの宣言に従って、ショートカットがバインドされている capabilityintent に対して一致するインライン インベントリ値の shortcutId を提供します。または、<shortcut-fulfillment> タグを capability に追加することで、ショートカット自体で定義された intent をフルフィルメントに使用するように指定できます。

サンプル app/res/shortcuts.xml ファイルの次のコードは、ショートカット フルフィルメントを実装します。

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

上記のサンプルでは、ユーザークエリが exercise.name パラメータのインライン インベントリ値と一致する場合、<shortcut-fulfillment> タグは、バインドされたショートカットの intent がフルフィルメントに使用されることを指定します。

Open App Feature BII のインライン インベントリ

インライン インベントリは、一般的にはインライン インベントリをサポートする BII のオプションのケーパビリティですが、OPEN_APP_FEATURE のような特定の BII では必須です。一般的に使用されるこの BII を使用すると、ユーザーはアシスタントを使用して特定のアプリ機能にディープリンクできます。オープンアプリ機能 BII では、ユーザーをアプリにディープリンクする前に、ユーザーがリクエストした機能が存在することを確認するために、アプリ機能名のインライン インベントリが必要です。

サンプル app/res/shortcuts.xml ファイルの次のコードは、アプリの注文ステータス機能を表す単一のショートカットでこの BII を実装しています。

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

res/values/arrays.xml の文字列配列リソース @array/order_status_names では、この機能の類義語のリストを指定します。

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

前述のケーパビリティを設定して、アシスタントは同じ機能を表すさまざまなフレーズを遂行できます。

  • 「OK Google, Example App で注文ステータスを見せて」
  • 「OK Google, Example App で注文を見せて」
  • 「OK Google, Example App で注文履歴を表示して」

インライン インベントリをテストする

インベントリをテストするには、アシスタントが関連する App Action ケーパビリティを遂行する際にアプリに渡す BII パラメータ値を検査します。インライン インベントリは、ユーザーがインベントリにバインドされた BII パラメータの値を、一致するインライン インベントリ ショートカットの shortcutId に置き換えることで機能します。

たとえば、START_EXERCISE BII ケーパビリティは、インライン インベントリを使用して、ユーザー指定の BII パラメータ「run」を、対応するエクササイズ ID "CARDIO_RUN" に変換します。

Google アシスタント プラグインを使用すると、テストデバイス上のアシスタントでインライン インベントリの App Actions をプレビューできます。プラグインを使用してインベントリをテストする手順は次のとおりです。

  1. インライン インベントリに関連付けられた類義語の値を使用して、BII ケーパビリティのインベントリにバインドされたパラメータを構成します。
  2. プラグインから BII をトリガーし、テストデバイスで BII を呼び出します。
  3. App Action のフルフィルメント中にアシスタントがアプリケーションに提供するパラメータ値を検査します。