App Actions を使用して Android アプリを Google アシスタントに拡張する（レベル 2）

1. 概要

App Actions を使用すると、ユーザーは Google アシスタントから特定のアプリ機能を直接起動できるため、Android アプリのリーチの拡大につながります。Android デベロッパーの場合は、機能を実装することができるため、ユーザーに提供している機能の種類と、こうしたリクエストの処理方法を Google アシスタントに伝えることができます。

1 つ目の App Actions Codelab では、Health and Fitness BII カテゴリの組み込みインテント（BII）を実装して、Google アシスタントをサンプルのフィットネスアプリに拡張する方法を学習しました。BII は、ユーザーが頻繁にアシスタントに実行させるタスクの種類を表すカテゴリ別に分類されています。

この Codelab では、ほぼすべての Android アプリで処理可能なアプリの一般的なタスクを表す「Common」BII カテゴリの BII を使って、App Actions をアプリに追加する方法を学習します。

この Codelab では、App Actions を使った開発に関する中級レベルのコンセプトについて解説します。Android アプリの開発と Android インテントの実装の経験が必要になります。

作成する内容

この Codelab では、サンプルの To-do リストアプリに 2 つの Common BII を追加して、ユーザーがアシスタントに以下をリクエストできるようにします。

actions.intent.OPEN_APP_FEATURE BII を使ってアプリ内の機能にアクセスする。
actions.intent.GET_THING BII を使ってアプリ内検索でコンテンツを検索する。

アプリ内のアクティブなタスクを表示する Google アシスタントの 3 段階の画面

図 1. アプリ内のアクティブなタスクを表示する Google アシスタントの 3 段階の画面

学習する内容

Common カテゴリの BII を使用して、ほとんどの Android アプリにアシスタントを拡張する方法について学習します。また、Android Studio 用の Google アシスタントプラグインを使用して、Common BII をテストする方法についても学習します。

前提条件

シェルコマンドを実行するためのターミナル（git がインストールされていること）。
Android Studio の最新の安定版。
アクションのテストに使用する Android デバイスまたは Android 仮想デバイス（Google Play ストアにインターネット経由でアクセスできること）。
同じ Google アカウントで Android Studio にログインし、テストデバイスで Google アプリと Google アシスタントアプリの両方にログインしていること。

この Codelab では、Android デバイス（物理デバイスまたは仮想デバイス）を使用してアクションをテストします。物理デバイスを使用する場合は、そのデバイスがローカルの開発マシンに接続されていることを確認してください。また、そのデバイスで Google アプリにログインし、同じ Google アカウントを使用して Android Studio にログインする必要があります。デバイスには Google アシスタントアプリがインストールされている必要もあります。

2. 仕組みを理解する

App Actions は、ユーザーを Google アシスタントから Android アプリに接続します。ここでは、その仕組みについて説明します。

ユーザーがアプリを使用することをアシスタントに伝えると、アシスタントはアプリに登録されている App Actions を shortcuts.xml ファイルから探します。このファイルには、アシスタントの組み込みインテントまたはカスタムインテントを Android インテントまたはディープリンクにリンクするアプリの機能が含まれています。

ユーザーがアシスタントにクエリを伝えると、アシスタントはユーザーの入力を解析し、それを App Actions インテント（この Codelab では BII）と照合します。アシスタントは、Android アプリの shortcuts.xml ファイルから、サポートされている機能を特定します。インテントが一致する場合、その BII を持つ機能には、そのリクエストの処理方法が含まれます。この Codelab では、フルフィルメントとは、アプリでアクティビティを起動する Android インテントを指します。

次の図は、このアシスタントのフローを示しています。

$Google アシスタントによるユーザーの音声クエリの\n処理方法について説明するフロー。$ 図 2. Google アシスタントによるユーザーの音声クエリの処理方法について説明するフロー。

shortcuts.xml プロジェクトファイルには、各 App Actions に関する次の情報が含まれています。

App Actions で使用される組み込みインテントまたはカスタムインテント
ユーザーに提供する Android アクティビティまたはディープリンク
組み込みインテントのパラメータと、ユーザーがアシスタントに提供した情報をマッピングする方法

次に、提供された Android インテントまたはディープリンクを Android アクティビティがフィルタして処理し、ユーザーに必要な機能を提供します。これにより、アシスタントはユーザーのクエリに応じてアプリの機能を呼び出すユーザーエクスペリエンスが達成されます。

3. 開発環境を準備する

この Codelab では、Android 用の To-do リストサンプルアプリを使用します。このサンプルアプリを使用すると、To-do リストに項目を追加したり、カテゴリでアイテムを検索したり、完了したタスクに関する情報を表示したりすることができます。

ベースファイルをダウンロードする

次のコマンドを実行して、サンプルアプリの GitHub リポジトリのクローンを作成します。

git clone --branch codelab-start https://github.com/actions-on-google/appactions-common-biis-kotlin.git

リポジトリのクローンを作成したら、次の手順に沿って Android Studio で開きます。

[Welcome to Android Studio] ダイアログで、[Import project] をクリックします。
リポジトリのクローンを作成したフォルダを探して選択します。

この Codelab の完成バージョンのアプリを確認するには、--branch master フラグを使ってサンプルアプリのリポジトリのクローンを作成します。

Android アプリケーション ID を更新する

アプリのアプリケーション ID を更新すると、テストデバイス上のアプリが一意に識別され、Google Play Console にアプリをアップロードする場合に「パッケージ名の重複」エラーが発生するのを回避できます。アプリケーション ID を更新するには、app/build.gradle を開きます。

android {
...
  defaultConfig {
    applicationId "com.MYUNIQUENAME.android.fitactions"
    ...
  }
}

applicationId フィールドの「MYUNIQUENAME」を一意の値に置き換えます。

デバイスでアプリをテストする

アプリに変更を加える前に、サンプルアプリでできる内容を確認しておくことをおすすめします。エミュレータでアプリを実行する手順は次のとおりです。

Android Studio で、[Run] > [Run app] を選択するか、ツールバーの実行アイコンをクリックします。
[Select Deployment Target] ダイアログでデバイスを選択し、[OK] をクリックします。推奨される OS バージョンは Android 10（API レベル 30）以上ですが、アクションは Android 5（API レベル 21）以上のデバイスでも動作します。
ホームボタンを長押しして、アシスタントを設定し、動作していることを確認します。デバイスでアシスタントにログインしていない場合は、ログインする必要があります。

Android Virtual Device について詳しくは、仮想デバイスを作成して管理するをご覧ください。

To-do リストサンプルアプリを示すアニメーション

図 3. To-do リストサンプルアプリを示すアニメーション。

アプリを少し操作して、何ができるかを確認してください。プラスアイコンをタップすると、新しいタスクアイテムを作成できます。右上のメニューアイテムを使用すると、完了ステータスに基づいてタスクアイテムを検索およびフィルタできます。

テストプラグインをインストールする

Google アシスタントプラグインを使用すると、テストデバイス上で App Actions をテストできます。テストツールをまだインストールしていない場合は、次の手順に沿ってインストールします。

[File] > [Settings]（MacOS では [Android Studio] > [Preferences]）に移動します。
[Plugins] セクションで [Marketplace] に移動して「Google Assistant」を検索します。テストツールを手動でダウンロードしてインストールすることもできます。
- Marketplace でプラグインが見つからない場合は、手動でプラグインをダウンロードし、Install the plugin from disk の手順を行います。
ツールをインストールして Android Studio を再起動します。

4. Get Thing BII 機能を追加する

actions.intent.GET_THING BII を使用すると、アプリ内検索機能を Google アシスタントに拡張できます。この手順では、GET_THING BII を実装してテストし、ユーザーがサンプルアプリ内で特定のタスクを検索できるようにします。

Get Thing 機能を定義する

検索関連の App Actions では、アシスタントはユーザークエリから検索語句を thing.name BII パラメータに抽出し、その値を Android アプリに渡します。

GET_THING BII をアプリに追加するには、app/src/main/res/xml サンプルプロジェクトディレクトリにある shortcuts.xml を更新し、最上位の <shortcuts> タグ内に <capability> 要素を追加します。

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

上記の構成は次のとおりです。

アプリが GET_THING BII に応答することを宣言します。
その BII に応じてアプリを起動する Android インテントをビルドする方法を指定します。
- アクティビティは targetPackage と targetClass を使って識別されます。
- BII パラメータ thing.name は、q という名前の Intent エクストラにマッピングされています。

名前を指定したアクティビティは、アプリのマニフェスト内に存在し、エクスポートされている必要があります。

提供された Android アプリにはメタデータが含まれているため、AndroidManifest は shortcuts.xml ファイルを認識します。

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

App Actions をテストする

アシスタントからアプリのアプリ内検索をテストする手順は次のとおりです。

Android デバイスが接続されていることを確認します。
[Tools] > [Google Assistant] > [App Actions Test Tool] に移動します。
[Create Preview] をクリックし、[App name] と [locale] のデフォルト値を承認します。求められた場合は、App Actions のポリシーと利用規約を確認して同意します。
最初の手順で BII を選択および構成することを求められたら、actions.intent.GET_THING を選択します。name の値を running shoes から milk に変更します。
[Run App Action] をクリックします。

このテストでは、GET_THING BII が name 属性を使用して、アプリ内の「milk」を含むタスクを検索します。前の App Actions と同様に、テストツールでアクションをテストするか、テストデバイスで「OK Google, タスクリストでケーキミックスを検索して」などの検索フレーズを言うことができます。

5. Open app feature BII 機能を追加する

この手順では、Open app feature BII を実装し、ユーザーがアシスタントを使用してアクティブなタスクや完了したタスクを表示できるようにします。そのためには、機能をトリガーする方法、パラメータを渡す方法、呼び出す Android インテントに関する情報を含む shortcuts.xml の機能を完成させます。この Codelab では、OPEN_APP_FEATURE BII を使用します。この BII を実装したら、デバイス上でアクションをテストします。

Open app feature 機能を追加する

shortcuts.xml の Get Thing Capabilities 要素の下に、Open app feature 用の 2 つ目の機能を追加します。

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

この機能では、Open app feature BII と Android インテントが一緒にマッピングされるため、Open app feature がトリガーされると、Android インテントがトリガーされます。

Android インテントをトリガーする前に、サポートされているパラメータがユーザーの入力から取得されます。OPEN_APP_FEATURE BII は、ユーザークエリから抽出されたアプリの機能を表す 1 つのパラメータ feature をサポートしています。このアプリケーションでサポートされている機能は、アクティブなタスクと完了したタスクの 2 種類です。これらの機能により、ユーザーはアプリを開いてタスクの一覧をフィルタ表示することができます。これらの機能をサポートするには、インラインインベントリを使用する必要があります。

インラインインベントリを使用してインテントパラメータを処理する

インテントパラメータは、ユーザークエリから抽出された要素を表します。たとえば、ユーザーが「OK Google, ExampleApp からピザを注文して」と言うと、アシスタントは「ピザ」を food.item schema.org インテントパラメータに抽出し、これを処理するアクションにパラメータを渡します。

Open App Feature BII は、ユーザークエリから抽出されたアプリの機能を表す 1 つのパラメータ feature をサポートしています。このパラメータにはインラインインベントリが必要です。アシスタントは、このインラインインベントリを使用して、サポートされているアプリ機能名のセットとパラメータ値を照合します。

feature インテントパラメータを処理するには、shortcuts.xml にショートカットを追加して、Open app feature 機能の上に次のコードを追加します。

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

上のコードでは、機能とパラメータバインディングを含む shortcut 要素として表されるインラインインベントリを定義しました。ショートカットは、BII パラメータのインベントリとして使用できます。Google アシスタントは、ユーザークエリを、ショートカットのパラメータバインディング内の値と照合し、パラメータ値が一致した場合、shortcutId がフルフィルメントインテントに追加されます。ユーザーがリクエストで OPEN_APP_FEATURE BII を有効にすると、アシスタントは feature パラメータ値をショートカットの値属性と照合し、Extra の parameter として値を targetClass に渡します。

たとえば、ユーザーが「OK Google, 完了したタスクを ExampleApp に表示して」と言うと、アシスタントは feature インテントパラメータ値の「完了したタスク」を、対応するインベントリショートカットと照合します。これにより、その値が OPEN_APP_FEATURE 機能に渡されます。それから、アシスタントが Android インテントをトリガーします。

App Actions をテストする

開発時とテスト時は、Google アシスタントプラグインを使用して、テストデバイス上でアシスタントによる App Actions をプレビューできます。また、このツールを使用すると、App Actions のインテントパラメータを調整したり、さまざまなユーザークエリでアシスタントにリクエストし、アクションがどう処理されるかをテストしたりすることもできます。

テストツールを使って App Actions をテストする手順は次のとおりです。

物理的な Android テストデバイスを接続するか、Android Emulator を起動します。
テストツールが表示されない場合は、[Tools] > [Google Assistant] > [App Actions Test Tool] に移動して開きます。
[Update] ボタンをクリックしてプレビューを更新します。
最初の手順で BII を選択および構成することを求められたら、actions.intent.OPEN_APP_FEATURE を選択します。
[feature] ボックスで、デフォルトの History 値を Completed tasks で更新します。
[Run App Action] をクリックします。

別の方法として、デバイスのアシスタントアプリで呼び出し名を直接使用して、App Actions を試すこともできます。たとえば、「OK Google, Task List で完了したタスクを表示して」と言うことも可能です。

6. 次のステップ

これで完了です

一般的な BII を使用して、ほぼすべての Android アプリを Google アシスタントに対応させることができるようになりました。

学習した内容

この Codelab では、以下のことを学びました。

ユーザーがアシスタントを使用してアプリの特定の機能を詳しく確認できるようにする方法。
ユーザーがアシスタントからアプリ内検索にアクセスする方法。
Google アシスタントプラグインを使用して一般的な BII をテストする方法。

次のステップ

To-do リストアプリにさらに調整を加えてみましょう。完了プロジェクトを参照するには、GitHub の –master branch リポジトリをご覧ください。

App Actions を使用したこのアプリの拡張について詳しくは、以下を参照してください。

App Actions のパフォーマンスをトラッキングする方法を確認するには、Firebase 向け Google アナリティクスを使用した To-do リストのサンプルをご覧ください。
アプリをアシスタントに拡張する方法について詳しくは、App Actions の組み込みインテントのリファレンスをご覧ください。

Actions on Google についてさらに詳しく知りたい場合は、以下のリソースをご覧ください。

developers.google.com/assistant: Actions on Google の公式ドキュメントサイト。
App Actions のサンプルインデックス: App Actions の機能を検討するためのサンプルアプリとサンプルコード。
Actions on Google GitHub リポジトリ: サンプルコードとライブラリ。
r/GoogleAssistantDev: Google アシスタントに取り組むデベロッパーを対象とした Reddit 公式コミュニティ。

Twitter で @ActionsOnGoogle をフォローして最新情報をチェックしてください。また、作成したアクションについて、ハッシュタグ #AoGDevs でツイートしてください。

フィードバックアンケート

最後に、こちらのアンケートにご回答いただき、この Codelab に関するフィードバックをお送りください。

App Actions を使用して Android アプリを Google アシスタントに拡張する（レベル 2）

1. 概要

作成する内容

学習する内容

前提条件

2. 仕組みを理解する

3. 開発環境を準備する

ベースファイルをダウンロードする

Android アプリケーション ID を更新する

デバイスでアプリをテストする

テスト プラグインをインストールする

4. Get Thing BII 機能を追加する

Get Thing 機能を定義する

shortcuts.xml

App Actions をテストする

5. Open app feature BII 機能を追加する

Open app feature 機能を追加する

shortcuts.xml

インライン インベントリを使用してインテント パラメータを処理する

shortcuts.xml

App Actions をテストする

6. 次のステップ

テストプラグインをインストールする

インラインインベントリを使用してインテントパラメータを処理する