App Actions の組み込みインテント

組み込みインテント（BII）を使用すると、アプリでフルフィルメント機能を Google に伝えることができます。 shortcuts.xml ファイルで機能を宣言し、インテント パラメータをフルフィルメントにマッピングすることで、クエリに応じて Google アシスタントがアプリを特定の画面で起動し、ユーザーがタスクを完了できるようになります。

組み込みインテントは、アプリのカテゴリに応じてグループ化されています。各カテゴリは、ユーザーがアプリで頻繁に実行する一般的なタスクのセットを表しています。利用可能な BII とそのパラメータ、テストに使用できるクエリの例の一覧については、組み込みインテントのリファレンスをご覧ください。

多くの BII には、固有のデプロイ要件と推奨事項があります。これらの要件と推奨事項は、アプリがユーザー エクスペリエンスを最大限に高めるのに役立ちます。

図 1. アシスタントへの音声クエリで START_EXERCISE BII を呼び出します。
図 2. アプリを特定の画面で起動して START_EXERCISE タスクを開始します。
図 3. クエリに応じてウィジェットを表示します。

​

BII を実装してインテント パラメータを処理する

App Actions では、 shortcuts.xml ファイルで機能を宣言し、BII パラメータを処理します。BII を実装してパラメータを処理する手順は次のとおりです。

  1. 選択した BII で capability を宣言します。
  2. 追加する BII フィールドごとに、ネストされた parameter 要素を追加します。
    1. targetClass または targetPackage を使用する場合は、選択した名前を使用して Android インテント extras にマッピングします。
    2. ディープリンク URL を使用する場合は、URL テンプレートのクエリ文字列で名前付きパラメータを使用します。

BII パラメータを処理するには、BII パラメータを capability 内の明示的 Android インテントの対応するパラメータにマッピングします。その後、その値をアプリで使用できます。アプリで BII パラメータを処理する必要はありません。ただし、組み込みインテントのリファレンスで「Recommended」とマークされているデータ フィールドは処理するようにしてください。

複数のインテント フルフィルメントを定義し、それぞれに独自の推奨パラメータ セットを指定できます。Google は、ユーザーのクエリから特定したケーパビリティ パラメータとインテントで宣言されたパラメータに基づいて、適切なフルフィルメントを選択します。

たとえば、actions.intent.START_EXERCISE インテントでは、アプリで exercise.name BII パラメータを処理することが推奨されますが、パラメータなしでアプリに BII を実装することもできます。これは、特定のエクササイズ名なしでユーザークエリを処理する場合に行います（「Example App にエクササイズのトラッキングを開始するよう依頼してください」）。

次のスニペットには、ユーザーのクエリにパラメータが含まれていない場合、必須パラメータのないフルフィルメントへのフォールバックがあります。

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">

    <capability android:name="actions.intent.START_EXERCISE">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetClass="com.example.myapplication.Activity1"
            android:targetPackage="com.example.myapplication">
            <parameter
                android:name="exercise.name"
                android:key="exerciseType"
                android:required="true"
                />
        </intent>
        <intent
            android:action="android.intent.action.VIEW"
            android:targetClass="com.example.myapplication.Activity2">
        </intent>
    </capability>
</shortcuts>

Google アシスタントは、パラメータ値をアプリに返すときに、最も関連性の高い情報をユーザーに提供するように最善を尽くします。たとえば、Example Restaurant のモバイルアプリでピザを注文するユーザークエリには、必ずしも場所が含まれているとは限りません。ユーザーの利便性を高めるため、アシスタントは最寄りの Example Restaurant の緯度と経度の値をそのアプリに提供することがあります。

追加の要件として、ユーザーの実際の状態を変更するアクション（送金、注文、メッセージの送信など）を、事前にユーザーに確認することなく直接実行しないようにする必要があります。

曖昧性除去

<url-parameter> やインテント エクストラを介してアプリに渡される引数では、ユーザーに表示するアイテムを一意に識別できない可能性があります。この場合、引数値を検索引数として使用し、ユーザーをアプリの検索ページに導きます。これにより、曖昧さを取り除いて適切なアイテムを選択できます。

たとえば、ユーザーのクエリが BII ORDER_MENU_ITEM の「Order from Example Restaurant」である場合、名前が「"Example Restaurant"」という用語に一致するレストランのリストをユーザーに提示できます。

言語とロケールのサポート

各 App Action BII で開発とテストをサポートしているロケールは、組み込みインテントのリファレンスに記載されています。一部の BII は、デベロッパーのテストやアシスタントからのユーザーによるトリガーに関して、さまざまなロケールをサポートしています。