App Actions を作成する

App Actions を使用すると、ユーザーは Google アシスタントに話しかけるか、アシスタントから提案される Android ショートカットを使用して、Android アプリの機能を起動できます。App Actions を使用して Android アプリを拡張する基本的な手順は次のとおりです。

  1. トリガーするアプリ内機能と、それに対応する組み込みインテント(BII)を特定します。
  2. BII のフルフィルメントの詳細を指定します。
  3. App Action のショートカットをアシスタントにプッシュします。
  4. テストデバイスで App Actions をプレビューします。
  5. アプリのテストリリースを作成します。
  6. App Actions の審査とデプロイをリクエストします。

必要に応じて、アシスタントに提供する動的ショートカットを定義して、ユーザーに提案できます。App Actions の Codelab に沿って、サンプルアプリを使用して App Actions を作成します。

要件

App Actions の開発を始める前に、ご自身とアプリが次の要件を満たしていることを確認してください。

  • Google Play Console にアクセスできる Google アカウントが必要です。
  • App Actions は Google Play ストアで公開されているアプリでのみ使用できるため、アプリを Google Play ストアに公開する必要があります。また、App Actions は managed Google Play でサポートされていないため、アプリが仕事用プロファイルでの使用を想定していないことを確認してください。
  • App Actions をテストするには、物理デバイスまたは仮想デバイスが必要です。
  • 最新バージョンの Android Studio が必要です。
  • Android Studio、テストデバイスの Google アプリ、Google Play Console にログインするには、同じ Google アカウントを使用する必要があります。
  • テストデバイスでアシスタントをセットアップし、ホームボタンを長押ししてテストする必要があります。

アプリの機能と一致する組み込みインテントを見つける

音声リクエストによってユーザーがジャンプできる Android アプリの機能を特定し、組み込みインテントのリファレンスを確認して、ユースケースに適した BII を見つけます。BII は、実行するタスクのユーザークエリをモデル化しているため、アプリの主要な機能とユーザーフローに一致する BII を探します。

actions.intent.GET_THING BII を使用してアプリ内検索をアシスタントに拡張したり、actions.intent.OPEN_APP_FEATURE BII を実装してユーザーが音声で特定のアプリ機能を起動できるようにしたりするなど、ほぼすべての Android アプリで使用できる一般的な BII があります。

カテゴリやカテゴリ固有のユースケースを可能にする BII もあります。たとえば、料理注文アプリでは actions.intent.ORDER_MENU_ITEM BII を使用できます。

優れたユーザー エクスペリエンスを提供し、承認の遅延を避けるために、実装する各 BII がアプリ内機能に関連していることを確認してください。

App Actions は、アシスタント アプリから Android インテントを起動して、アプリ内の特定のコンテンツにユーザーを直接誘導します。targetClass フィールドと targetPackage フィールドを指定することで、アクティビティを明示的に起動するインテントを定義できます。Android ディープリンク URL をすでにアプリに実装している場合は、フルフィルメントにディープリンクを使用するようにインテントを構成できます。詳しくは、アクティビティのディープリンクをテストするをご覧ください。

組み込みインテントのフルフィルメントの詳細を指定する

App Actions の作成の大部分は、Android アプリの shortcuts.xml リソース ファイル内で、選択した BII とそれに対応するフルフィルメントを指定するケーパビリティの宣言です。BII は、タスクのユーザークエリをモデル化したものです。フルフィルメント インテントは、タスクの実行方法に関する情報をアシスタントに提供します。

shortcuts.xml ファイルでは、BII は <capability> 要素で表され、各フルフィルメントは <intent> 要素で表されます。

<shortcuts>
    <capability android:name="actions.intent.ORDER_MENU_ITEM">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.app"
            android:targetClass="com.example.app.browse">
            <parameter
                android:name="menuItem.name"
                android:key="query">
            </parameter>
        </intent>
    </capability>

ほとんどの BII では、schema.org エンティティに基づいてユーザークエリからインテント パラメータを抽出します。アプリは、これらの BII パラメータを使用して、選択したケーパビリティにユーザーを誘導します。たとえば、上記のコードでは、menuItem.name BII パラメータが query Android intent パラメータにマッピングされています。

ディープリンクを使用してアクションを遂行する場合は、urlTemplate フィールドを使用して、アシスタントが生成するディープリンク URL を定義します。

<shortcuts>
    <capability android:name="actions.intent.ORDER_MENU_ITEM">
        <intent android:action="android.intent.action.VIEW">
            <url-template android:value="myfoodapp://browse{?query}" />
            <parameter android:name="menuItem.name"
                android:key="query"
                android:mimeType="text/*">
            </parameter>
        </intent>
    </capability>
</shortcuts>

App Actions を shortcuts.xml ファイルに追加する方法に関する重要事項については、shortcuts.xml を作成するをご覧ください。このページでは、アプリが想定するパラメータ値を指定する方法についても説明します。

GET_THING 組み込みインテントを実装する

アプリに検索機能がある場合は、その関数に actions.intent.GET_THING BII を実装する必要があります。アシスタントは、ユーザーが「OK Google, Example App で Example Thing を検索して」などのクエリをすると、アプリ内の検索結果の検索機能にユーザーを転送できます。

shortcuts.xml ファイルで、他の BII を実装する場合と同様に、actions.intent.GET_THING BII に <capability> を実装します。ユーザークエリをアプリの検索機能に渡すフルフィルメントを少なくとも 1 つ提供する限り、GET_THING に複数のフルフィルメントを使用できます。

shortcuts.xmlactions.intent.GET_THING BII を追加する例を次に示します。

  <capability android:name="actions.intent.GET_THING">
    <intent
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.MySearchActivity">
      <parameter android:name="thing.name" android:key="query" />
    </intent>
  </capability>

検索 Activity で、intent の追加データから検索クエリを抽出し、アプリの検索機能に渡します。上記のコードでは、query キーとして渡された検索クエリは "thing.name" BII パラメータにマッピングされています。次に、クエリを使用して検索を実行し、その結果をユーザー インターフェースに表示します。

省略可: App Action のショートカットをアシスタントにプッシュする

アクションにケーパビリティを定義すると、ユーザーは「OK Google, Example App でピザを注文して」などと話しかけてアクションを起動できます。アシスタントは、適切なタイミングでユーザーにアクションの Android ショートカットを提案し、ユーザーがアクションを見つけてリプレイできるようにします。アシスタントは、動的ショートカットと静的ショートカットの両方を提案できます。

動的ショートカットをアシスタントにプッシュするには、Google Shortcuts Integration Library を使用します。この Jetpack ライブラリを使用すると、アシスタントはショートカットを取得し、適切なタイミングでユーザーに提案できます。

詳しくは、アシスタントに動的ショートカットをプッシュするをご覧ください。

App Actions をプレビューする

開発時とテスト時は、Android Studio 用の Google アシスタント プラグインを使用して、App Actions がアプリで機能するかテストします。このプラグインは、Google アカウントのアシスタントに App Actions のプレビューを作成します。このテストツールを使用すると、ユーザーから受け取ることを想定している入力パラメータを BII に提供して、物理テストデバイスまたはエミュレータでフルフィルメントをテストできます。

App Actions のプレビュー中に、デバイスから音声によるクエリをトリガーできます。この機能は、App Actions の BII リファレンスに記載されているクエリでのみ利用できます。音声トリガーはデモ目的でのみ使用し、通常のテストでは使用しないでください。

審査のためにアプリを送信する前に、Google Play Console のデベロッパー ツールを使用して、アプリをドラフトモードでテストします。Google Play Console を使用してアプリのドラフトをデプロイする方法については、リリースを準備して公開するをご覧ください。

テストリリースを作成する

追加のテスターを使用して App Actions をテストする準備ができたら、アプリの内部またはクローズド テスト版リリースを作成します。デフォルトでは、内部リリースとクローズド リリースのテスターは、審査と承認が完了している App Actions にアクセスできます。

未承認のアクションを含むすべての App Actions へのテストアクセス権を付与するには、App Actions Development Program Google グループに参加するようテスターに指示します。このグループのメンバーは、アプリ アクション テストツールを使用してプレビューを作成しなくても、クローズド テストリリースと内部テストリリースのすべての App Actions にアクセスできます。グループに参加してからアクセスできるようになるまで、最大 3 時間かかることがあります。

App Actions の審査とデプロイをリクエストする

App Actions は、公開済みのアプリやオープンテスト版リリースが審査されて承認されるまで、使用できません。App Actions の審査は、Android アプリの審査と Google Play でのデプロイ ステータスには影響しません。送信したアプリが承認され、Play ストアに公開されている場合でも、shortcuts.xml は Google による審査中の可能性があります。審査も承認されるまで、App Actions はエンドユーザーに対して機能しません。

アプリをデプロイするとき、App Actions は有効なままになります。ただし、再デプロイしたバージョンは Google による審査の対象となります。新しいバージョンが正常に機能しない場合、またはポリシー違反が含まれている場合、Google は、アプリの App Actions を無効にする権限を有します。

審査のために App Actions を提出する手順は次のとおりです。

  1. Google Play Console で App Actions の利用規約に同意します([詳細設定] > [App Actions])。

    App Actions 利用規約(Google Play Console 内)

  2. 通常どおり、Google Play Console に shortcuts.xml を含むアプリをアップロードします。

  3. Google Play Console にアプリをアップロードすると、Google Play Console アカウントのメールで、App Actions の詳しい審査状況に関する連絡が Google から届きます。App Actions の審査ステータスについてご不明な点がある場合は、アシスタント デベロッパー サポートにお問い合わせください。お問い合わせフォームにアプリのパッケージ ID を入力し、[What can we help you?] 選択ボックスで [App Action review] を選択します。

ディープリンクを使用して App Action で Activity を起動するには、Activity にディープリンク URL を設定し、対応するインテント フィルタを Android アプリ マニフェストに追加する必要があります。

アクティビティがアクセス可能かどうか、ディープリンクを使用して App Actions を使用してトリガーできるかどうかをテストするには、次の adb コマンドを実行します。

$ adb shell am start -a android.intent.action.VIEW -d "AppLinksURL"

次に例を示します。

$ adb shell am start -a android.intent.action.VIEW -d "https://www.example.com/deeplink"

adb コマンドでアクティビティが正常に起動されない場合は、次の点を確認してください。

  • アプリ マニフェスト ファイルでは、アクティビティに android:exported=true が含まれているため、Google アシスタントからインテントを使用してアクティビティを起動できます。
  • アプリリンク URL を使用している場合、Android アプリリンクの処理に記載されている手順をすべて実施している。

App Actions のポリシー

App Actions は、トリガーしたユーザーが意図したとおりのエクスペリエンスを提供できるよう、特定のポリシーに準拠する必要があります。最適なユーザー エクスペリエンスを提供し、Google Play ストアでの審査の遅延や否承認を避けるため、アプリを送信する前に以下のポリシーを確認してください。

  • ユーザーを目的のコンテンツに誘導する

    App Action の組み込みインテント(BII)やパラメータは、関連するユーザーが意図したアクションにのみユーザーを誘導する必要があります。これには、アプリ内コンテンツ、ウェブサイトのコンテンツ、スライスやウィジェットに表示される情報(エクスペリエンスがユーザーの意図したものである場合に限る)が含まれます。

    たとえば、BII「ORDER_MENU_ITEM」を実装すると、ユーザーは指定されたメニュー項目や料理の種類の注文を開始できます。このポリシーの唯一の例外は、BII OPEN_APP_FEATURE によってユーザーをアプリのホーム画面に誘導する場合です。

  • 関連するウェブ コンテンツにユーザーを誘導する

    ユーザーがウェブページのコンテンツにリダイレクトされる場合、ウェブサイトはユーザーが意図するアクションに関連し、ブランドが所有するものである必要があります。

    たとえば、BII「GET_RESERVATION」をトリガーするユーザーを、アプリのブランド exampledomain.com に属さない google.com/travel にリダイレクトすることは違反です。違反のもう 1 つの例は、BII「GET_CALL_HISTORY」をトリガーしたユーザーを exampledomain.com/payment にリダイレクトし、購入を要求するケースです。

  • 関連する App Actions BII を実装する

    実装する BII は、アプリのコンテンツと機能に直接関連している必要があります。

    たとえば、アプリが通信 Play ストアのカテゴリ内にある場合、ORDER_MENU_ITEM BII は実装しないでください。この BII は、フード、ドリンク カテゴリのアプリに推奨されます。

  • 関連するカスタム インテントを実装する

    カスタム インテントに対して定義されたクエリは、アプリのコンテンツと機能に関連します。このポリシーへの違反の例として、Play ストア アプリの交通系アプリに対して、関連するクエリパターン「ブリトー レシピを見せて」のインテント custom.action.intent.GET_RECIPE が作成されます。