App Actions を使用して Android アプリを Google アシスタントに拡張する

App Actions を使用すると、Android アプリの特定の機能を Google アシスタントから直接起動できるようにし、アプリの利用範囲をさらに拡げることができます。App Actions では、アプリのディープリンクを使用して、ユーザーがよく使うアプリ機能に新たな方法でアクセスできるようにします。

開発にあたっては、利用可能な組み込みインテントを実装することで、ユーザーのやりたいことを簡単に実現できます。

この Codelab では、Actions on Google を使用した開発に関する中級レベルのコンセプトについて説明します。この Codelab を実施するには、Android アプリの開発経験とディープリンクの処理に関する知識が必要です。Android による開発が初めての場合は、Android デベロッパー向け基礎知識の Codelab から始めることをおすすめします。

目標

この Codelab では、サンプルの Android アプリ（フィットネスアプリ）に以下の機能を追加します。

ユーザーが Google アシスタントを使用して、アプリのエクササイズタイマーを開始できるようにする。
ユーザーが Google アシスタントを使用して、アプリのエクササイズタイマーを停止できるようにする。

Google アシスタントを使用して、アプリ内のランニングトラッカーを起動する様子を順番に表す 4 つの画面。

演習内容

App Actions が Android アプリに適しているかどうかを確認する。
組み込みインテントと Android アクティビティを接続する。
Android アプリのディープリンクの URL パラメータをアシスタントから取得する。
インラインインベントリを使用して識別子をアプリ機能にマッピングする。
Android Studio で App Actions をテストする。

必要なもの

始める前に、現在の環境で以下のツールが使用できることを確認してください。

シェルコマンドを実行するためのターミナル（git がインストールされていること）。
Android Studio の最新バージョン。
Google Play Console にアクセスできる Google アカウント。
App Actions をテストするための Android デバイス。

この Codelab で使用するコードを理解するうえで、Kotlin と XML に精通していることを推奨しますが、必須ではありません。

この Codelab の App Actions を正常にトリガーするには、Google アシスタントのロケールを en-US、en-GB、en-CA、en-IN、en-BE、en-SG、または en-AU に設定する必要があります。この Codelab の Android アプリで使用する組み込みインテントは、上記以外の言語やロケールには対応していません。

この Codelab では、Android デバイスを使用して App Actions をテストします。物理的な Android デバイスでテストする際は、そのデバイスがローカルの開発マシンに接続されていることを確認してください。そのデバイスで Google アプリにログインし、同じ Google アカウントを使用して Android Studio にログインする必要があります。

App Actions を使用すると、Google アシスタントのユーザーに Android アプリの機能を提供できます。ここではその仕組みについて説明します。

アシスタントは、ユーザーがアプリを使用する意思を示すと、そのアプリに登録されている App Actions が actions.xml ファイルに含まれているかどうかを確認します。このファイルに記述されている App Actions は、組み込みインテント（アプリの機能をセマンティックに記述したもの）とフルフィルメントの方法（たとえばディープリンクテンプレート）を組み合わせたものです。

actions.xml ファイルには、App Actions ごとに以下の情報が格納されています。

App Actions が使用する組み込みインテント。
App Actions を実行する方法（たとえば、ディープリンクを使用する）
ユーザーがアシスタントに提供した情報と、インテントのパラメータをマッピングする方法。

App Actions は、ユーザーが Google アシスタントに提供した情報に基づいて、インテントを実行するためのディープリンクを作成します。Android アクティビティがこのディープリンクをフィルタして処理し、ユーザーに必要な機能を提供します。

以上が、ユーザーのクエリに応じてアシスタントがアプリ機能を呼び出すための仕組みです。

この Codelab では、サンプル Android アプリとしてフィットネスアプリを使用します。このフィットネスアプリでは、エクササイズタイマーを開始または停止したり、エクササイズのルーティン情報を確認したりできます。

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

この Codelab のベースファイルを取得するには、次のコマンドを実行して GitHub リポジトリのクローンを作成します。

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

--branch codelab-start オプションを使用してブランチをチェックアウトすると、この Codelab を開始時点の状態に切り替えることができます。

リポジトリのクローンを作成したら Android Studio で開きます。

[Welcome to Android Studio] ダイアログで、[Open an existing Android Studio project] をクリックします（プロジェクトを開いている場合は閉じておいてください）。
フィットネスアプリでの作業を開始するには、リポジトリのクローンを作成したフォルダを探して選択します。

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

フィットネスアプリに App Actions を実装したら、Android Studio プラグインを使用して入力テストを行います。プラグインは後ほどインストールしますが、このテストツールはアプリを Google Play Console のプロジェクトにアップロードするまでは使用できません。

サンプルのフィットネスアプリを Console 内で一意に識別できるよう、app/build.gradle ファイルで Android のデフォルト構成に設定されているアプリケーション ID を変更する必要があります。

build.gradle

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

applicationId の「MYUNIQUENAME」を一意の名前で置き換えます。これによりパッケージ名が変更され、後ほど Google Play Console にアップロードする際に「パッケージ名の重複」の問題が発生するのを回避できます。

アプリの動作を確認する

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

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

エミュレータは、物理的なデバイスと同じように起動する必要があるため、パソコンの処理速度によっては時間がかかることがあります。アプリのビルドが完了してエミュレータの準備が整うと、Android Studio によってアプリがエミュレータにアップロードされて実行されます。

Fit Actions アプリを開いてエクササイズの統計情報を表示した状態のスマートフォン。

アプリを少し操作して、何ができるかを確認してみましょう。実行アイコンをタップするとエクササイズのタイマーが始動し、X アイコンをタップするとタイマーが停止します。App Actions で有効にするタスクは 2 つです。

上記の手順をテストデバイスでも行い、アプリがどちらのサーフェスでも同じように機能することを確認します。次に進む前に、物理デバイスのホームボタンを長押しし、アシスタントが動作していることも確認してください。テストデバイスでアシスタントにログインしていない場合はログインする必要があります。

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

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

Android Studio で次の手順を行います。

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

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

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

これでアプリが Google Play Console にアップロードされたので、Android Studio に戻ります。

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

アプリに登録されている App Actions が認識されるようにするには、その情報をなんらかの方法で Google アシスタントに伝える必要があります。開発中は、Android Studio プラグインの「App Actions Test Tool」を使用して情報を伝えます。

プラグインをまだインストールしていない場合は、次の手順でインストールします。

[File] > [Settings]（MacOS では [Android Studio] > [Preferences]）に移動します。
[Plugins] セクションで、Marketplace に移動して「App Actions Test Tool」を検索します。
ツールをインストールして Android Studio を再起動します。

App Actions を設定するには、Android アプリで実行する機能にマッピングする組み込みインテントを指定する必要があります。Google アシスタントで利用可能な組み込みインテントは、組み込みインテントのリファレンスページにまとめられています。各組み込みインテントは、ユーザーが実行しようとしているタスクを実現する一般的な方法をモデル化したものです。

このリファレンスでは、App Actions で実行できる組み込みインテントが、カテゴリと機能別ごとに整理されています。

この Codelab では、ユーザーに機能を提供するため、以下の 2 つの組み込みインテントを実装します。

エクササイズの記録を開始する（actions.intent.START_EXERCISE）
エクササイズの記録を停止する（actions.intent.STOP_EXERCISE）

実装の手順としては、まずディープリンクを設定し、次にアプリの XML リソース内で App Actions を定義し、最後にこれら 2 つを接続します。

ディープリンクを実装する

ディープリンクは、インテントからの情報をプロセス内のアプリに渡し、ユーザーがアプリ内のコンテンツに直接アクセスできるようにするために使用します。アシスタントは、デフォルトではディープリンクを使用してインテントを実行し、パラメータをアプリに渡します。この Codelab の入力ディープリンクでは、"fit-actions.firebaseapp.com" ホストと "https" スキームを使用します。

Android マニフェストファイルで、メインアクティビティのインテントフィルタを追加し、サポートされているディープリンクを定義します。

AndroidManifest.xml

<activity android:name="com.devrel.android.fitactions.FitMainActivity" ...>
    ... // Other intent filters

    <!-- Define your supported deeplinks -->
    <intent-filter
        android:autoVerify="true"
        tools:targetApi="m">

        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:host="fit-actions.firebaseapp.com"
            android:scheme="https" />
    </intent-filter>
</activity>

次に、メインアクティビティに関数を追加して、入力ディープリンクの動作を定義します。

FitMainActivity.kt

private fun handleDeepLink(data: Uri?) {
    when (data?.path) {
        DeepLink.START -> {
            // Get the parameter defined as "exerciseType" and add it to the fragment arguments
            val exerciseType = data.getQueryParameter(DeepLink.Params.ACTIVITY_TYPE).orEmpty()
            val type = FitActivity.Type.find(exerciseType)
            val arguments = Bundle().apply {
                putSerializable(FitTrackingFragment.PARAM_TYPE, type)
            }

            updateView(FitTrackingFragment::class.java, arguments)
        }
        DeepLink.STOP -> {
            // Stop the tracking service if any and return to home screen.
            stopService(Intent(this, FitTrackingService::class.java))
            updateView(FitStatsFragment::class.java)
        }
        else -> {
            // Path is not supported or invalid, start normal flow.
            showDefaultView()
        }
    }
}

サンプルアプリでは、DeepLink.START と DeepLink.STOP は定数として定義され、入力ディープリンクの対応するパスにマッピングされています。DeepLink.START のハンドラは、ディープリンクの URL パラメータを介して渡された引数も取ります。

次に、同じファイルの handleIntent 関数に変更を加え、ディープリンクハンドラを使用できるようにします。

FitMainActivity.kt

private fun Intent.handleIntent() {
    when (action) {
        // When the action is triggered by a deep-link, Intent.ACTION_VIEW will be used
        Intent.ACTION_VIEW -> handleDeepLink(data)
        // Otherwise start the app as you would normally do.
        else -> showDefaultView()
    }
}

これで、アプリが "https://fit-actions.firebaseapp.com/start" 形式のインテントをフィルタすると、エクササイズタイマーが始動するようになりました。

Android Debug Bridge（ADB）に精通している場合は、実行中のデバイス上でディープリンクハンドラをテストすることもできます。その場合は、デバイス上のアプリを更新し、次のシェルコマンドを使用します。

adb shell am start -a android.intent.action.VIEW -d "https://fit-actions.firebaseapp.com/start"

App Actions が機能するためには、アプリにどの App Actions が登録されているかを Google アシスタントが認識できる必要があります。この情報をアシスタントに伝えるには、Android パッケージの一部として Google Play Console に actions.xml ファイルをアップロードします。

新しいリソースを作成して参照する手順は次のとおりです。

actions.xml を作成し、接続する組み込みインテントと必要なパラメータを設定します。
組み込みインテントのパラメータを、アクティビティ内のディープリンクパラメータにマッピングします。
AndroidManifest.xml の actions.xml ファイルへの参照を追加します。

actions.xml を作成する

アプリでサポートされる App Actions を記述するには、actions.xml という新しい XML ファイルを app/src/main/res/xml に作成します。

Android Studio で次の手順を行います。

[File] > [New] > [XML] > [App Actions XML File] に移動します。
[Actions File Name] に「actions」と入力します。
[Finish] をクリックすると、新しい actions.xml ファイルが作成され、AndroidManifest.xml にそのファイルへの参照が追加されます。

新しいファイルが作成されたら、actions.xml の内容を次のコードで置き換えます。

actions.xml

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

<actions>
    <action intentName="actions.intent.START_EXERCISE">
        <fulfillment urlTemplate="https://fit-actions.firebaseapp.com/start{?exerciseType}">
            <parameter-mapping
                intentParameter="exercise.name"
                urlParameter="exerciseType" />
        </fulfillment>
    </action>

    <action intentName="actions.intent.STOP_EXERCISE">
        <fulfillment urlTemplate="https://fit-actions.firebaseapp.com/stop" />
    </action>
</actions>

上のコードでは、要素を使用して、アプリ内のエクササイズタイマーの開始と停止を行う App Actions を定義しています。intentName 属性は、App Actions を使用して実行する 2 つの組み込みインテントに対応します。要素は、アプリを使用してアクションを処理する方法をアシスタントに伝えます。

ここでは、urlTemplate 属性を使用してディープリンクを作成することで、両方のアクションを実行できるようにしています。この URL テンプレートでは、AndroidManifest.xml ファイルでディープリンク用に定義したホストとスキームが使用されます。各 URL テンプレートのパスは、前の手順でメインアクティビティに追加した handleDeepLink 関数に対応しています。

タイマーを開始するときには、組み込みインテントの exercise.name パラメータを exerciseType URL パラメータにもマッピングする点に注意してください。これにより、ディープリンクハンドラが、アシスタントからビジネスロジックの引数を取得できます。

Android マニフェストが actions.xml を参照していることを確認する

前の手順では、Android Studio で actions.xml ファイルへの参照を AndroidManifest.xml ファイルに追加しました。これを確認するには、Android マニフェストで次の要素をチェックします。

AndroidManifest.xml

<application>
    ...

    <meta-data
        android:name="com.google.android.actions"
        android:resource="@xml/actions" />
</application>

マニフェストファイルに上記の要素が表示されている場合は、App Actions のテストに進みます。

マニフェストファイルに上記の要素が表示されていない場合は追加します。

App Actions をテストする

では、テストデバイスで App Actions の動作を確認しましょう。

テストデバイスを接続し、テストツールで App Actions をテストする手順は次のとおりです。

[Tools] > [App Actions] > [App Actions Test Tool] に移動します。Android Studio へのログインを求められる場合があります。前の手順で Google Play Console に使用したのと同じアカウントを使用してください。
[Invocation Name] フィールドに「Fit Actions」と入力します。
アシスタントの言語が [English (US)] でない場合は、アシスタントの言語と一致するロケールを [Locale] に入力します。
[Create Preview] をクリックします。
[Configure] プルダウンリストから、テストする組み込みインテントを選択します。
[Run] をクリックします。Google で開くためのオプションを提示する場合は [Always] を選択し、アシスタントがサポートされているリンクを開けるようにします（この設定は後でアプリの設定から変更できます）。

App Actions Test Tool では、App Actions のプレビューを Google アカウントごとに作成または更新するため、定義した App Actions は一時的に登録されることになります。このプレビューにより、アプリの製品版を Google Play Console にデプロイしていなくても、アシスタントが App Actions を認識できるようになります。

テストツールがアプリの組み込みインテントをフェッチしたら、そのインテントとパラメータ値を直接提供し、Android Studio から App Actions をトリガーできます。

別の方法として、デバイスのアシスタントアプリで呼び出し名を指定して App Actions を実行することもできます。たとえば、「OK Google, Fit Actions でランニングを開始して」と言うことで、エクササイズタイマーを開始する App Actions を実行できます。

これで、Google アシスタントを使ってフィットネスアプリのエクササイズタイマーを開始したり停止したりできるようになりました。ただし、認識されるエクササイズの種類はまだ限られています。「Fit Actions で水泳を開始」や「Fit でハイキングを開始」のようなリクエストに対しては、タイマーの最初に「不明なアクティビティを開始…」というテキストが返されます。

これは、サンプルアプリが現時点でサポートしているエクササイズの種類が、「ランニング」、「サイクリング」、「ウォーキング」のみであるためです。他のエクササイズのトラッキングにも対応できるようにしましょう。

このアプリで対応できるエクササイズの種類を増やす方法はいくつかあります。

水泳やクライミングなど、アプリが対応できるエクササイズの種類を追加する（actions.intent.START_EXERCISE 組み込みインテントのサポート対象のテキストフィールド値で制限する）
アプリでサポートする別のエクササイズ（「ハイキング」など）を、すでにサポートされている「ウォーキング」などにマッピングする。

対応できるエクササイズの種類を追加することで、ユーザーが指定したエクササイズに応じてさまざまな機能を提供することも可能になります。エクササイズごとに異なるタスクを実行できれば、ユーザーにとってさらに魅力的なアプリになります。

このフィットネスアプリでは、2 番目の簡単な方法で Google アシスタントが対応できるようにします。これによりユーザーは、別のサポート対象テキストフィールド値を含むクエリでも、タイマーを開始できるようになります。この Codelab では、インラインインベントリを使用して、「Start hiking」をアプリの「Start walking」機能にマッピングします。

インラインインベントリ

インラインインベントリを使用すると、ユーザーがアシスタントを通じて App Actions をトリガーするときに、クエリに含める可能性のあるエンティティを定義できます。actions.xml ファイルにインラインインベントリを追加することで、サポートされるオプションのリストを直接作成できます。インラインインベントリのアイテムは、要素でグループ化されます。アクション定義では、それらのエンティティセットを参照してマッピングパラメータとして使用できます。

前述のように、このサンプルアプリには「ランニング」、「サイクリング」、「ウォーキング」をサポートする機能が含まれています。エンティティセットを作成して actions.intent.START_EXERCISE で参照することで、ディープリンクではエンティティ識別子を使用するだけで済みます。

actions.xml

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

        <!-- Map a parameter to an entity set reference -->
        <parameter name="exercise.name">
            <entity-set-reference entitySetId="ExerciseEntitySet" />
        </parameter>
    </action>
    ...

    <!-- Define an inline inventory -->
    <!-- This sample maps supported entities with the class FitActivity.Type -->
    <entity-set entitySetId="ExerciseEntitySet">
        <entity
            name="@string/activity_running"
            identifier="RUNNING" />
        <entity
            name="@string/activity_walking"
            identifier="WALKING" />
        <entity
            name="@string/activity_hiking"
            identifier="WALKING" />
        <entity
            name="@string/activity_cycling"
            identifier="CYCLING" />
    </entity-set>
</actions>

インラインインベントリの各要素は、ユーザーのクエリと一意に一致します。アシスタントは、これらのエンティティに基づいて、サポートされている入力（ランニング、ウォーキング、サイクリングなど）を識別します。エンティティは、アプリ固有の情報（メニュー項目やサービスなど）をアシスタントが認識できるようにしたい場合には特に便利です。

「hiking」という文字列のエンティティを追加すると、ウォーキング用に作成した機能をハイキングにも活用できるようになります。

インベントリをテストする

テストツールでプレビューを作成または更新すると、アプリに登録された組み込みインテントが取得されます。このインテントにパラメータ値を直接渡すことで、Android Studio から App Actions をトリガーできます。

App Actions Test Tool でインベントリをテストしてみましょう。

[Update Preview] をクリックします。
[Configure] プルダウンリストから「actions.intent.START_EXERCISE」を選択します。
exercise.name フィールドに「hiking」と入力します。
[Select Target Device] プルダウンリストからデバイスを選択します。
[Run] をクリックします。

App Actions Test Tool に「hiking」と入力し、テストデバイス上でウォーキングタイマーを開始するアニメーション。

これで完了です

この Codelab では、Android アプリに App Actions を追加するために必要なスキルを習得しました。

学習した内容

どの Android アクティビティがどの組み込みインテントに対応し、ユーザーが App Actions でトリガーできるかどうかを特定する方法。
組み込みインテントからのパラメータを Android アプリに渡す方法。
インラインインベントリを使用して、サポートされる値をアプリの機能識別子にマッピングする方法。
Android Studio で App Actions をテストする方法。

次のステップ

この Codelab で作成したフィットネスアプリをさらに拡張できます。GitHub の master リポジトリのブランチに、アプリの拡張バージョンを提供していますので参考にしてください。拡張バージョンでは Android の Slice を使用して、アシスタントを介してエクササイズの追加情報を提供できるようにしています。また、製品版 Android アプリの 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 アシスタントに拡張する

目標

演習内容

必要なもの

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

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

build.gradle

アプリの動作を確認する

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

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

ディープリンクを実装する

AndroidManifest.xml

FitMainActivity.kt

FitMainActivity.kt

actions.xml を作成する

actions.xml

Android マニフェストが actions.xml を参照していることを確認する

AndroidManifest.xml

App Actions をテストする

インライン インベントリ

actions.xml

インベントリをテストする

学習した内容

次のステップ

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

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

インラインインベントリ

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