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 を追加して、ユーザーがアシスタントに以下をリクエストできるようにします。

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 でアプリをビルドする手順は次のとおりです。

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

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

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

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

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

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

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

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

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

  1. デバイスのアプリを更新します。
  2. アプリバーのオーバーフロー メニューにある更新ボタンをタップして、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.xmlaction 要素の下に追加します。

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 パラメータ値を entityname 属性と照合し、一致した entityurl をフルフィルメントに渡します。

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

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

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

<?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 をテストする手順は次のとおりです。

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

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

  1. 物理的な Android テストデバイスを接続するか、Android エミュレータを起動します。
  2. [Tools] > [App Actions] > [App Actions Test Tool] に移動します。
  3. [Update Preview] をクリックします。
  4. [Configure] プルダウン リストで、actions.intent.GET_THING インテントを選択します。「name」の値を「running shoes」から「milk」に変更します。
  5. [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 を使用したアプリの拡張について詳しくは、以下を参照してください。

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

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

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

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