ウェブ インベントリ

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

App Actions を使用すると、ユーザーは「OK Google, ExampleApp でスリードット カフェのメニューを見せて」と話しかけるだけで、アプリのコンテンツに直接移動できるようになります。このディープリンクと呼ばれる機能により、ユーザーはアプリでさまざまなことを簡単に行えます。

この種のリクエストに応えるために、Google アシスタントはアプリ内の一致するコンテンツへのディープリンクを生成します。コンテンツや商品情報を含むウェブサイトをアクティブに管理していて、そのような公開ウェブ コンテンツを中心にアプリ内ディープリンクを編成している場合は、ウェブ インベントリを使用して、ウェブサイトからアクションのフルフィルメントの URL を取得するようにアシスタントを構成できます。

ウェブ インベントリは、アプリでサポートされているアイテム URL のウェブサイト上の場所です。ユーザーが App Actions を呼び出すと、アシスタントは「スリードット カフェ」のようなユーザークエリを、Android アプリの shortcuts.xml で指定されているウェブサイトの Google 検索インデックス内の対応する URL と照合します。

メリット

定期的に更新される大規模なアイテムリストをユーザーが閲覧して注文するようなアプリの場合、ウェブ インベントリには次のようなメリットがあります。

  • アプリ内にアイテムリストを格納するインライン インベントリのデータと異なり、ウェブ インベントリのデータはウェブサイト上に存在します。アシスタントにウェブデータへのアクセスを許可することで、インライン インベントリのようにデータが古くなるリスクを回避できます。インライン インベントリのデータは、アプリの新しいバージョンを公開しない限り、更新できません。

  • インライン インベントリのアイテム数は 1,000 に制限されています。これに対して、ウェブ インベントリにはアイテム数の制限がなく、必要に応じて拡張できます。

  • ウェブ インベントリでは、ウェブサイトから取得される予測可能なコンテンツ URL のみをフルフィルメントが処理できるように、アプリのロジックを簡素化できます。一方、インベントリが構成されていない場合は、アシスタントは URL テンプレートでインテント パラメータを変数にマッピングすることにより、フルフィルメントのディープリンクを生成します。フルフィルメントは、この動的に生成される URL を分析して、サポートされているエンティティをアプリでユーザーがリクエストしたかどうかを判断する必要があります。

仕組み

App Action が呼び出されると、アシスタントは shortcuts.xml で定義した組み込みインテント（BII）を使用してアプリ コンテンツにディープリンクします。アシスタントは、自然言語処理を使用してユーザーのリクエスト内の関連アイテムを識別し、それらを BII パラメータに抽出します。次に、shortcuts.xml. 内のフルフィルメント構成に基づき、パラメータを使用してディープリンクを生成します。

フルフィルメントのディープリンクは、次の 3 つの方法で生成できます。

  • パラメータ マッピング: インテント パラメータを、フルフィルメントの URL テンプレート内のプレースホルダにマッピングします。
  • インライン インベントリ: インテント パラメータを、アプリで定義されているサポート対象の entities のリストと照合します。
  • ウェブ インベントリ: インテント パラメータを、ウェブサイトの Google 検索インデックスにあるコンテンツと照合します。

ウェブ インベントリは、デベロッパーが定義するウェブサイトの URL パターンです。たとえば、https://www.exampleapp.com/restaurants/.* は、アプリでサポートされているエンティティのエンティティ セットを表します。

ウェブ インベントリに対応する BII パラメータが構成されている場合、アシスタントはウェブサイトをクエリして、ユーザークエリと一致するエンティティを実行します。次に、構成済みの URL パターン（https://www.exampleapp.com/restaurants/three-dot-cafe など）と一致する URL 結果をフルフィルメントに渡します。

図 1. ウェブ インベントリを使用してレストランのエンティティ アイテムを取得するアシスタント クエリの例。

サポートされている組み込みインテント

ウェブ インベントリは、特定のインテント パラメータに対して、次の BII でサポートされています。

  • [actions.intent.CREATE_REVIEW]
  • [actions.intent.GET_NEWS_ARTICLE]
  • [actions.intent.GET_REVIEW]
  • [actions.intent.GET_THING]
  • [actions.intent.ORDER_MENU_ITEM]
  • [actions.intent.GET_EXERCISE_PLAN]
  • [actions.intent.GET_DIGITAL_DOCUMENT]
  • [actions.intent.GET_ITEM_LIST]
  • [actions.intent.GET_OFFER]
  • [actions.intent.CREATE_OFFER]
  • [actions.intent.GET_PRODUCT]
  • [actions.intent.UPDATE_CART]
  • [actions.intent.CREATE_SOCIAL_MEDIA_CONNECTION]
  • [actions.intent.GET_IMAGE_OBJECT]
  • [actions.intent.GET_SOCIAL_MEDIA_POSTING]
  • [actions.intent.GET_SOCIAL_MEDIA_PROFILE]
  • [actions.intent.CREATE_TAXI_RESERVATION]
  • [actions.intent.CREATE_FLIGHT_RESERVATION]
  • [actions.intent.CREATE_LODGING_RESERVATION]
  • [actions.intent.GET_LOCAL_BUSINESS]
  • [actions.intent.GET_RESERVATION]
  • [actions.intent.UPDATE_RESERVATION]

ウェブ インベントリを追加する

サポートされている BII を特定したら、ウェブサイトの詳細情報で shortcuts.xml を更新し、ウェブ インベントリに対して BII を有効にします。shortcuts.xml ファイルは Android プロジェクトのリソースであり、アプリの機能にマッピングされる BII と、各 BII がアプリのフルフィルメントのディープリンクを生成する方法を定義する場所です。shortcuts.xml について詳しくは、shortcuts.xml を作成するをご覧ください。

サポートされている BII でウェブ インベントリを使用する手順は次のとおりです。

  1. アプリの shortcuts.xml ファイルに、android:name 属性がウェブ インベントリで処理する BII の名前に設定された <capability> タグを追加します（例: actions.intent.ORDER_MENU_ITEM）。

  2. <capability> タグ内に、android:action 属性がこのインテントでアクティブにするビューの名前に設定された <intent> タグを追加します。

  3. 同じ <intent> タグ内で、<parameter> タグを追加し、その android:name 属性をウェブページに記述したエンティティに最も対応する BII パラメータに設定します。たとえば、ORDER_MENU_ITEM のウェブ インベントリを提供する場合は、メニューページを menuItem.name にリンクする必要があります。

  4. 新しい <parameter> タグで、<data> タグを追加して、その android:pathPattern 属性を、ウェブ インベントリに使用する URL パスの URL パターンに設定します。

この手順で shortcuts.xml を構成すると、アシスタントは android:pathPattern 属性で指定した URL パターンの Google 検索インデックスからウェブ コンテンツを取得できます。すると、アシスタントは、定義した URL パスのパターンに一致する結果を使用して、URL 値をフルフィルメントに渡します。そして、アプリは、アシスタントから提供された URL データに基づいて、アプリ内の特定の場所にユーザーを誘導します。

たとえば、ウェブサイトに https://www.examplecafe.com/items/ で始まる URL パスを使用した商品リスティングが含まれているとします。pathPattern 値 https://www.examplecafe.com/items/.* を使用すると、アシスタントはこの URL パターンをウェブ検索で使用して、フルフィルメント URL（https://www.examplecafe.com/items/item123 など）を探します。

一致するウェブ インベントリ URL が見つかった場合は、フルフィルメント インテントの <data> フィールドにその URL がディープリンクであるかのように指定されます。URL を Uri オブジェクトとして取得するには、インテントの getData() メソッドを使用します。インテントを受け取るアプリ アクティビティは、URL を解釈し、適切なアプリのユーザー インターフェースをアクティブにします。

shortcuts.xml の例

次の例では、menuItem.name BII パラメータを含むリクエストの URL 結果を返すウェブ インベントリを提供する ORDER_MENU_ITEM BII を定義しています。

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.ORDER_MENU_ITEM">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.OrderMenuItemActivity">
      <!-- Define URL match pattern in the pathPattern data field -->
      <parameter android:name="menuItem.name">
        <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
      </parameter>
    </intent>
  </capability>
</shortcuts>

上記の例では、pathPattern が menuItem.name に指定され、URL パターン https://www.examplecafe.com/items/.* に一致する URL のみを返すようアシスタントに指示しています。

ウェブ インベントリをサポートする BII のその他の shortcuts.xml の例については、リファレンス ドキュメントをご覧ください。

結果がない場合のフォールバックを処理する

ウェブ インベントリ結果がフルフィルメントに返されない状況では、フォールバック ロジックを実装して、可能な限り最適なユーザー エクスペリエンスでアクションを遂行する必要があります。結果がない状況の例を次に示します。

  • インテント パラメータがない: ユーザーがクエリで要求されるパラメータを指定しなかったか、アシスタントがユーザー リクエストのパラメータを理解していなかった。
  • URL 結果がない: アシスタントが、ユーザークエリと一致するエンティティをウェブサイトで検出できなかった。

パラメータ値の欠落に対応するには、1 つのケーパビリティに複数の <intent> 要素を定義します。アシスタントが最初のインテントを満たすことができない場合は、次のインテントにフォールバックします（以降も同様）。

フォールバック インテントにパラメータは不要です。代わりに、より一般的なディープリンク（ユーザークエリの検索結果の表示など）でケーパビリティを満たす必要があります。

次の shortcuts.xml の例では、ORDER_MENU_ITEM BII で 2 つのフルフィルメントが定義されています。1 つ目のフルフィルメントは menuItem.name パラメータで URL を要求します。2 つ目のパラメータはパラメータを要求しません。したがって、すべてのメニュー アイテムを表示するページにユーザーを誘導します。

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
    </parameter>
  </intent>
  <!-- Fallback intent with no required parameters -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ViewMenuActivity">
    <url-template android:value="myapp://app.examplecafe.com/menu/all-items" />
  </intent>
</capability>

ウェブ インベントリ URL が返されない状況でも、検索結果を表示する場合など、フォールバック インベントリでユーザークエリの内容が使用される場合があります。

次の shortcuts.xml の例では、2 つのインテント要素が定義されています。

  1. 1 つ目は、menuItem.name パラメータのウェブ インベントリのディープリンクを必要としています。
  2. ディープリンクが返されない場合、2 つ目のインテントが、menuItem.name のユーザークエリを使用して検索結果を表示します（存在する場合）。
<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- Fallback intent displaying search results, using "menuItem.name" -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.SearchMenuActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

ウェブ インベントリにアプリ内検索を追加する

ウェブ インベントリと actions.intent.GET\_THING BII の実装を組み合わせると、ユーザーがアプリでウェブ コンテンツを検索できるようになります。

この BII は、アプリのデフォルトのアプリ内検索機能を使用してコンテンツやエンティティを検索し、「OK Google, SampleApp で滝のハイキングを見せて」のようなクエリを有効にします。GET_THING BII によって渡される thing.name ケーパビリティ パラメータのウェブ インベントリを構成することで、自分のウェブサイトの一致するエンティティの結果がフルフィルメントに渡されます。

ウェブ インベントリ shortcuts.xml の例については、GET\_THING BII のリファレンスをご覧ください。

ウェブ インベントリをテストする

BII フルフィルメントのウェブ インベントリを定義すると、アシスタントは、指定された BII パラメータに定義した urlTemplate パターンに一致するウェブ結果を使用してディープリンクを生成します。ウェブ インベントリの結果が見つからない場合は、フォールバック インテントの urlTemplate パターンに一致する URL が生成されます。ウェブ インベントリの実装をテストするには、アシスタントが提供するリンクがウェブ インベントリの urlTemplate パターンに一致する URL であることを確認します。

次の ORDER_MENU_ITEM BII の例では、アシスタントは menuItem.name パラメータで指定された urlFilter パターンに一致するウェブ インベントリのフルフィルメント リンクを生成します（例: https://www.examplecafe.com/items/nuggets）。2 つ目のインテントは menuItem.name の値を受け取り、最初のインテントが URL パターンと一致しない場合に検索を実行します。

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <!-- web inventory fulfillment -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- search intent -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MenuSearchActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

App Actions Test Tool を使用して、実機または仮想デバイスでウェブ インベントリをテストします。

このテストツールを使用する手順は次のとおりです。

  1. アプリを実行中のテストデバイスを接続します。
  2. Android Studio で、[Tools] > [App Actions] > [App Actions Test Tool] に移動します。
  3. [Create preview] をクリックします。
  4. Android Studio から、テストデバイスでアプリを実行します。
  5. テストデバイスのアシスタント アプリを使用して、App Action をテストします。たとえば、「OK Google, ExampleCafe でナゲットを注文して」のように話しかけます。
  6. アプリの動作を観察します。または、Android Studio デバッガを使用して、アクションの結果が想定どおりになることを確認します。