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

1 つ目の App Actions Codelab では、Fitness BII カテゴリの組み込みインテント（BII: Built-In Intent）を実装し、サンプルフィットネスアプリを Google アシスタントに拡張する方法を学びました。BII は、ユーザーがアシスタントに実行させるタスクの種類ごとにカテゴリに分けて整理されています。

ここでは、[Common BII カテゴリ] の BII を使用して App Actions をアプリに追加し、ほとんどの Android アプリで実行できる一般的なアプリタスクを実装してみましょう。

この Codelab では、App Actions を使った開発に関する中級レベルのコンセプトについて解説します。Android アプリの開発、ディープリンクの処理、actions.xml リソースの作成、App Actions Test Tool プラグインの使用などの経験と知識が必要になります。Android による開発が初めての場合は、1 つ前の Codelab から始めることをおすすめします。

目標

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

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

Google アシスタントがアプリ内のアクティブタスクを表示する様子を順番に表す 3 つの画面。

演習内容

ほとんどの Android アプリに適用できる一般的なカテゴリの BII を使用してアシスタントを拡張する。
App Actions Test Tool プラグインを使用して Common BII をテストする。

前提条件

シェルコマンドを実行するためのターミナル（git がインストールされていること）。
Android Studio の最新の安定版。
Google Play Console にアクセスできる Google アカウント。
アクションのテストに使用する Android デバイスまたはエミュレータ（Google Play ストアにインターネット経由でアクセスできること）。

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

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

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

次のコマンドを実行し、サンプルアプリの 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 の完成バージョンの ToDo リストアプリを確認するには、--branch master フラグを使用してサンプルアプリのリポジトリのクローンを作成します。

Android アプリケーション ID を変更してテストできるようにする

この Codelab では、App Actions Test Toolを使用して、Android デバイスまたはエミュレータでアクションをテストします。このテストツールを実行するには、Google Play Console のプロジェクトにアプリをアップロードしておく必要があります。Google Play Console にアプリをアップロードする際の「パッケージ名の重複」エラーを回避するため、サンプルアプリの applicationId を一意の ID に変更します。

app/build.gradle で、applicationId の「com.example.myapp」の値を一意の ID（たとえば「com.codelabs.myname」）に変更します。アプリケーション ID の決定方法について詳しくは、Android のリファレンスページをご覧ください。

build.gradle

android {
...
    defaultConfig {
        // This ID uniquely identifies your app on the device and in Google Play Store
        applicationId "com.example.myapp"
    ...
    }
}

applicationId を変更すると、「Gradle files have changed since last project sync…」（Gradle ファイルが前回のプロジェクトの同期から変更されています…）と書かれた黄色の警告ボックスが表示されることがあります。その場合は、Google Play Console にアプリをアップロードしたときに問題が発生しないよう、ボックスの [Sync Now]（今すぐ同期）をクリックしてください。

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

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

Android Studio で、[Run] > [Run app] を選択するか、ツールバーの実行アイコンをクリックします。
[Select Deployment Target] ダイアログで、仮想デバイスを選択して [OK] をクリックします。推奨される OS バージョンは Android 10（API レベル 30）以上ですが、アクションは Android 5（API レベル 21）以上のデバイスでも動作します。

ホームボタンを長押しし、アシスタントが動作していることを確認します。デバイスでアシスタントにログインしていない場合はログインする必要があります。

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

ToDo リストサンプルアプリのアニメーション

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

Google Play Console にアップロードする

Android Studio の App Actions Test Tool を使用するには、アプリを Google Play Console 内のプロジェクトにアップロードしておく必要があります。Android Studio でアプリをビルドし、内部リリースのドラフトとして Google Play Console にアップロードします。

Android Studio でアプリをビルドする手順は次のとおりです。

[Build] > [Generate Signed Bundle / APK] に移動します。
[Android App Bundle] を選択し、[Next] をクリックします。
アプリに署名するための詳細を入力し、[Next] をクリックします。
「prodRelease」ビルドバリアントを選択し、[Finish] をクリックします。

前の手順で作成した App Bundle を、Google Play Console にアップロードします。

[すべてのアプリ] ページで、[アプリを作成] をクリックします。
アプリに名前を付け、[アプリを作成] をクリックします。この Codelab では、アプリの作成後にアプリ情報を入力する必要はありません。
サイドバーのメニューから、[テスト] を選択して [内部テスト] ページに移動します。
[内部テスト] ページで [新しいリリースを作成] をクリックします。
[次へ] をクリックし、Google Play アプリ署名に同意します。
[App Bundle と APK] パネルで、前の手順で生成された AAB ファイルをアップロードします（通常は app/prod/release ディレクトリにあります）。[保存] をクリックします。

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

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

[File] > [Settings]（MacOS の場合は [Android Studio] > [Preferences]）に移動します。
[Plugins] セクションで、Marketplace に移動して「App Actions Test Tool」を検索します。手動でテストツールをダウンロードしてインストールすることもできます。
ツールをインストールして Android Studio を再起動します。

ここでは Open app feature BII を実装し、ユーザーがアシスタントを使用して、アクティブなタスクや完了したタスクを表示できるようにします。そのためには、まず actions.xml で BII を定義し、タスクフィルタ機能用の既存のディープリンクをアシスタントに拡張します。このセクションの最後に、デバイスを使ってアクションをテストします。

ディープリンクをテストする

BII を実装する前に、アプリ内の既存のディープリンクが所定の App Actions の動作に対応していることを確認します。

Android Debug Bridge（ADB）コマンドラインツールでディープリンクをテストする手順は次のとおりです。

デバイスのアプリを更新します。
アプリバーのオーバーフローメニューにある更新ボタンをタップして、ToDo リストにサンプルデータを入力します。

ToDo リストアプリのオーバーフローメニュー

Google で開くためのオプションを提示する場合は [Always] を選択し、ToDo リスト アプリがサポートされているリンクを開けるようにします。この設定は後でアプリの設定から変更できます。

ターミナルで以下の adb コマンドを入力して、アプリのタスクフィルタのディープリンクをテストします。

アクティブなタスクを表示する

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/active-tasks"

完了したタスクを表示する

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/completed-tasks"

すべてのタスクを表示する

adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/all-tasks"

これらのコマンドを実行するとアプリのリスト表示ビューが開き、各ディープリンクの後続パスに指定した完了ステータスでフィルタされたタスクが表示されます。

BII を追加する

これらのリンクを開くように設定された Open app feature BII を actions.xml で定義し、タスクフィルタ機能を Google アシスタントに拡張します。

app/src/main/res/xml サンプルプロジェクトディレクトリにある actions.xml を開き、次のコードを使用して BII を定義します。

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        //TODO: Handle intent parameters

        //TODO: Handle action fulfillment

    </action>
</actions>

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

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

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

feature インテントパラメータを処理するには、actions.xml を次のコードのように変更します。

actions.xml

<?xml version="1.0" encoding="utf-8"?>

<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        <parameter name="feature">
            <entity-set-reference entitySetId="FeatureEntitySet" />
        </parameter>

        //TODO: Handle action fulfillment

    </action>
</actions>

上のコードでは、渡された feature パラメータ値を、パラメータタグ内で entity-set-reference として定義したインラインインベントリ FeatureEntitySet と照合するようアシスタントに指示しています。

BII のインラインインベントリを定義するには、次のコードの entity-set を、actions.xml の action 要素の下に追加します。

actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action>
       ...
    </action>

    <entity-set entitySetId="FeatureEntitySet">
        <entity  url="https://todo.androidappactions.com/completed-tasks"
            name="completed tasks" alternateName="@array/completed_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/active-tasks"
            name="active tasks" alternateName="@array/active_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/all-tasks"
            name="all tasks" alternateName="@array/all_tasks_synonyms"/>
        <entity url="https://todo.androidappactions.com/statistics"
            name="statistics" alternateName="@array/statistics_synonyms"/>
    </entity-set>
</actions>

上のコードでは、インラインインベントリを 4 つの entity 要素からなる entity-set 要素として定義しました。ユーザーがリクエストでこの BII を有効にすると、アシスタントは feature パラメータ値を entity の name 属性と照合し、一致した entity の url をフルフィルメントに渡します。

たとえば、ユーザーが「OK Google, 完了したタスクを ExampleApp に表示して」と言うと、アシスタントは feature インテントパラメータ値「完了したタスク」を、対応するインベントリ entity と照合します。この照合の結果、関連付けられた URL https://todo.androidappactions.com/completed-tasks がフルフィルメントに渡されます。

アクションフルフィルメントを定義する

このアクションを実行するには、actions.xml で fulfillment 要素を定義し、アシスタントから渡された URL を処理します。次のコードを使用して、fulfillment を action に追加してください。

<?xml version="1.0" encoding="utf-8"?>
<actions>
    <action intentName="actions.intent.OPEN_APP_FEATURE">

        ... //Parameter definition

        <fulfillment urlTemplate="{@url}"/>
        <fulfillment urlTemplate="https://todo.androidappactions.com/all-tasks"/>

    </action>
   ...
</actions>

上のコードでは、2 つの fulfillment 要素を定義しています。1 つ目は urlTemplate 属性が {@url} プレースホルダになっており、アシスタントが feature パラメータから生成したディープリンクをトリガーします。2 つ目の fulfillment は、feature パラメータがない場合や一致するインラインインベントリ element が見つからなかった場合に、タスクビューを開いてフィルタされていないタスクリストを表示するフォールバックです。

App Actions をテストする

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

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

物理的な Android テストデバイスを接続するか、Android エミュレータを起動します。
[Tools] > [App Actions] > [App Actions Test Tool] に移動します。Android Studio へのログインを求められる場合があります。前の手順で Google Play Console に使用したのと同じアカウントを使用してください。
[Invocation Name] フィールドに「Task List」と入力します。
アシスタントの言語が [English (en)] でない場合は、アシスタントの言語と一致するロケールを [Locale] に入力します。
[Create Preview] をクリックします。
[Configure] プルダウンリストで、actions.intent.OPEN_APP_FEATURE インテントを選択します。
[feature] ボックスで、デフォルトの [History] の値を [Completed tasks] に変更します。
[Run] をクリックします。

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

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

ディープリンクをテストする

サンプルアプリには、すでにアプリ内検索機能のディープリンクが含まれています。BII を実装する前に、adb を使用して、アプリ内の既存のディープリンクが所定の App Actions の動作に対応していることを確認します。

検索ディープリンクテストするには、次の adb コマンドを使用します。

# GET_THING deep link: in-app search
adb shell am start -a android.intent.action.VIEW -d "https://todo.androidappactions.com/search?q=milk"

上のコマンドによってディープリンクがトリガーされ、検索クエリ「home」を含むアイテムのみをフィルタしたアイテムリストアクティビティが読み込まれます。

BII を追加する

検索関連の App Actions では、アシスタントがユーザークエリ内の検索キーワードを thing.name インテントパラメータに抽出します。このパラメータを fulfillment 要素で定義した URL テンプレートにマッピングすることで、フルフィルメントの URL が生成されます。

アプリ内で Get thing BII を定義するには、この新しいアクションで actions.xml を更新します。

Actions.xml

<?xml version="1.0" encoding="utf-8"?>
<actions>
   <action intentName="actions.intent.OPEN_APP_FEATURE">...</action>

   <action intentName="actions.intent.GET_THING">

        <parameter-mapping
                intentParameter="thing.name"
                urlParameter="q"/>

        <fulfillment urlTemplate="https://todo.androidappactions.com/search?q={q}">
        </fulfillment>

   </action>

   ...
</actions>

上のコードでは、parameter-mapping 要素で thing.name インテントパラメータが fulfillment 要素の urlParameter 属性の値「q」に割り当てられています。アシスタントは、urlParameter の値を fulfillment urlTemplate の {q} プレースホルダにマッピングしてディープリンクを生成します。

App Actions をテストする

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

物理的な Android テストデバイスを接続するか、Android エミュレータを起動します。
[Tools] > [App Actions] > [App Actions Test Tool] に移動します。
[Update Preview] をクリックします。
[Configure] プルダウンリストで、actions.intent.GET_THING インテントを選択します。「name」の値を「running shoes」から「milk」に変更します。
[Run] をクリックします。

このテストでは、Get thing BII が name 属性を使用して、アプリ内の「home」を含むタスクを検索します。前の App Actions と同じように、テストデバイスでアクションをテストするか、テストデバイスで「OK Google, Task List でケーキミックスを検索して」のように言います。その他の検索フレーズも試してみてください。

これで完了です

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

学習した内容

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

ユーザーがアシスタントを使用してアプリの特定の機能にアクセスできるようにする方法。
ユーザーがアシスタントを使用してアプリ内を検索する方法。
App Actions Test Tool を使用して、一般的な BII をテストする方法。

次のステップ

Task List アプリをさらに拡張してみましょう。拡張後のプロジェクトを参照するには、GitHub の –master branch リポジトリを参照してください。

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

App Actions のパフォーマンスをトラッキングする方法については、Firebase 向け Google アナリティクスを使用した ToDo リストのサンプルをご覧ください。
スライスを使用すると、ユーザーが Google アシスタントで操作できるビジュアルカードに埋め込まれたリストアイテムを表示できます。
アプリをアシスタントに拡張する方法について詳しくは、App Actions の組み込みインテントのリファレンスをご覧ください。

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

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

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

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

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

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

目標

演習内容

前提条件

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

Android アプリケーション ID を変更してテストできるようにする

build.gradle

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

Google Play Console にアップロードする

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

ディープリンクをテストする

BII を追加する

actions.xml

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

actions.xml

actions.xml

アクション フルフィルメントを定義する

App Actions をテストする

ディープリンクをテストする

BII を追加する

Actions.xml

App Actions をテストする

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

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

アクションフルフィルメントを定義する