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 パラメータを処理する必要はありません。ただし、組み込みインテントのリファレンスで「推奨」とマークされているデータ フィールドの処理は試してください。

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

たとえば、actions.intent.START_EXERCISE インテントではアプリで BII パラメータ exercise.name を処理することが推奨されていますが、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 では、デベロッパーのテストとアシスタントからのユーザー トリガーで、異なるロケールがサポートされています。