借助与应用有关的 Action 将 Android 应用扩展到 Google 助理

与应用有关的 Action 可让用户通过 Google 助理直接启动特定的应用功能,从而帮助您扩展 Android 应用的覆盖面。与应用有关的 Action 是在应用深层链接的基础上构建的,让用户可通过更多方式来访问要使用的功能。

作为 Android 开发者,您可以实现其中一个可用的内置 intent,以便帮助用户更快速、更顺畅地处理各种事务。

本 Codelab 介绍了 Actions on Google 相关开发的中级概念。您最好拥有开发 Android 应用和处理深层链接的经验,以便顺利完成本 Codelab 的学习。之前没接触过 Android 的开发者最好先从关于 Android 开发者基础知识的 Codelab 开始学习。

构建内容

在本 Codelab 中,您将在一个 Android 健身应用示例中添加以下功能:

  • 用户可以使用 Google 助理让该应用中的运动计时器开始计时。
  • 用户可以使用 Google 助理让该应用中的运动计时器停止计时。

4 个进程屏幕,其中显示的是 Google 助理在应用中启动跑步跟踪程序的过程。

学习内容

  • 如何确定与应用有关的 Action 是否适合您的 Android 应用。
  • 如何将内置 intent 与 Android activity 相关联。
  • 如何通过 Google 助理获取 Android 应用的深层链接网址参数。
  • 如何使用内嵌目录将标识符映射到应用功能
  • 如何在 Android Studio 中测试与应用有关的 Action。

所需条件

继续学习之前,请确保您的环境中已安装下列工具:

  • 已安装 git 的终端,用于运行 shell 命令。
  • 最新版本的 Android Studio
  • 有权访问 Google Play 管理中心的 Google 帐号。
  • 一台 Android 实体设备,用于测试与应用有关的 Action。

建议(但不强制要求)您熟悉 Kotlin 和 XML,以便理解本 Codelab 中使用的代码。

在本 Codelab 中,只有使用以下语言区域的 Google 助理语言才能成功触发与应用有关的 Action:en-US、en-GB、en-CA、en-IN、en-BE、en-SG 和 en-AU。本 Codelab 中的 Android 应用使用的内置 intent 不支持其他语言和语言区域。

在本 Codelab 中,您将使用 Android 设备来测试与应用有关的 Action。在 Android 实体设备上测试之前,请确保该设备已连接到您的本地开发机器。您必须在该设备上登录 Google 应用,并使用同一 Google 帐号登录 Android Studio

与应用有关的 Action 会将用户从 Google 助理关联到您的 Android 应用,但它们的工作原理是怎样的?

在用户向 Google 助理表明他们想要使用您的应用后,Google 助理会从 actions.xml 文件中查找已向您的应用注册的与应用有关的 Action。该文件中结合使用内置 intent(对应用功能进行语义化描述)和执行方式指令(例如,深层链接模板)来描述与应用有关的 Action。

actions.xml 文件包含每个与应用有关的 Action 的以下信息:

  • 与应用有关的 Action 使用的内置 intent。
  • 与应用有关的 Action 采用的执行方式(例如,通过深层链接)。
  • 该 intent 的参数如何映射到用户提供给 Google 助理的信息。

与应用有关的 Action 会根据用户提供给 Google 助理的信息来创建深层链接,以便执行相应 intent。然后,您的 Android activity 会过滤并处理所提供的深层链接,以便为用户提供所需的功能。

总而言之,这将产生如下的用户体验:Google 助理调用您的应用功能,以便响应用户的查询。

在本 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 中将其打开:

  1. Welcome to Android Studio 对话框中,点击 Open an existing Android Studio project(如果您已打开某个项目,请先将其关闭)。
  2. 请找到并选择您克隆代码库的文件夹,以便开始对该健身应用执行相应操作。

更改 Android 应用 ID

在您为该健身应用实现与应用有关的 Action 时,系统会要求您完成使用 Android Studio 插件测试输入的任务。稍后您会在本 Codelab 中安装该插件,但您只有在将应用上传到 Google Play 管理中心的某个项目后才能使用相应的测试工具。

如需在本 Codelab 中构建独有的示例健身应用版本,请更改 app/build.gradle 文件的默认 Android 配置中列出的应用 ID:

build.gradle

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

applicationId 中的“MYUNIQUENAME”替换为您独有的名称。这样做可以更改软件包名称,并防止以后在向 Play 管理中心上传时出现“Duplicate package name”(软件包名称重复)问题。

试用应用

在对该应用进行任何其他更改之前,最好了解一下该示例应用的功能。请尝试在模拟器上运行该应用:

  1. 在 Android Studio 中,依次选择 Run > Run app,或点击工具栏中的 Run 图标 acabcb8f8634af20.png
  2. Select Deployment Target 对话框中,选择虚拟设备,然后点击 OK。虽然 Action 在搭载 Android 5(API 级别 21)的设备上也能运行,但我们推荐使用的操作系统版本是 Android 8(API 级别 26)或更高版本。

模拟器的启动过程和实体设备一样,因此这个过程可能需要一些时间,具体取决于计算机的运行速度。在应用 build 和模拟器准备就绪后,Android Studio 会将该应用上传到模拟器并运行。

打开 Fit Actions 应用的手机,屏幕上显示的是运动统计信息。

快速浏览该应用以了解其功能。点按“Run”图标可让运动计时器开始计时,点按“X”图标可让计时器停止计时。您将通过与应用有关的 Action 完成这两项任务。

在测试设备上重复执行上述步骤,以便确认应用通过这两种途径的运行效果是相同的。在继续操作之前,请长按主屏幕按钮,以便设置 Google 助理并验证它能否在您的实体设备上正常运行。您需要在测试设备上登录 Google 助理(如果您尚未登录的话)。

上传到 Play 管理中心

在 Android Studio 中构建您的应用,并将其作为内部版本上传到 Play 管理中心。您必须上传该应用,然后才能在 Android Studio 中使用与应用有关的 Action 测试工具。

在 Android Studio 中,请按以下步骤操作:

  1. 依次转到 Build > Generate Signed Bundle / APK
  2. 选择“Android App Bundle”,然后点击 Next
  3. 输入详细信息以对应用进行数字签名,然后点击 Next
  4. 选择“release”build 变体,然后点击 Finish

Google Play 管理中心中,将您刚刚创建的 app bundle 作为新应用进行上传:

  1. 所有应用页面上,点击创建应用
  2. 随意为该应用命名,然后点击创建应用。在本 Codelab 中,您无需在应用创建完成后填写任何应用信息。
  3. 在边栏菜单中,转到版本并找到 内部测试页面。
  4. 点击内部测试页面上的创建新版本
  5. app bundle 和 APK 面板中,上传您之前生成的 AAB 文件(该文件可能位于 app/release 目录中)。
  6. 点击保存

现在,您已成功将您的应用上传到 Play 管理中心,接下来,请返回 Android Studio。

安装测试插件

Google 助理需要知道向您的应用注册的与应用有关的 Action,因此您需要以某种方式传达相关信息。在开发过程中,您可以使用“与应用有关的 Action 测试工具”Android Studio 插件来实现这一点。

如果您还没有该插件,请进行安装:

  1. 依次转到 File > Settings(在 MacOS 中,依次转到 Android Studio > Preferences)。
  2. 在“Plugins”部分中,转到 Marketplace 并搜索“App Actions test tool”。
  3. 安装该工具,然后重启 Android Studio。

如需设置与应用有关的 Action,您需要查找映射到您的 Android 应用所执行的函数的内置 intent。“内置 intent 参考”页面列出了适用于 Google 助理的内置 intent,其中每个 intent 都模拟了一种用户表达他们想要执行的任务的常用方式。

在该参考页面中,可由与应用有关的 Action 执行的内置 intent 会按类别和功能分组。

在本 Codelab 中,您将实现两个内置 intent 来帮助用户:

该过程涉及以下步骤:设置深层链接,在应用的 XML 资源中定义与应用有关的 Action,以及将深层链接和与应用有关的 Action 关联起来。

深层链接会将用户直接定向到内容,并在该过程中将来自 intent 的信息传递到应用。默认情况下,Google 助理会使用深层链接来执行 intent 并将相关参数传递到应用。在本 Codelab 中,传入深层链接会使用 "fit-actions.firebaseapp.com" 主机和 "https" 架构。

在 Android 清单文件中,为主 activity 添加 intent 过滤器,以便定义支持的深层链接:

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>

现在,在主 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.STARTDeepLink.STOP 在示例应用中被定义为常量,它们对应的是传入深层链接的相应路径。对于 DeepLink.START,处理程序还会获取通过深层链接网址参数传入的参数。

现在,更新同一文件的 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" 格式的 intent 时,它会让运动计时器开始计时。

如果您熟悉 Android 调试桥 (adb),则可以在正在运行的设备上测试深层链接处理程序。为此,请在您的设备上更新该应用并使用以下 shell 命令:

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

为了让与应用有关的 Action 能够正常运行,Google 助理需要知道有哪些已向您的应用注册的与应用有关的 Action。您可以将 actions.xml 文件作为 Android 软件包的一部分上传到 Play 管理中心,以便传达相应信息。

您只需执行几个步骤即可创建新资源并完成引用:

  1. 创建 actions.xml,以便确定要关联的内置 intent 以及所需的参数。
  2. 将内置 intent 参数映射到 activity 中的深层链接参数。
  3. AndroidManifest.xml 中添加对 actions.xml 文件的引用。

创建 actions.xml

如需描述该应用支持的与应用有关的 Action,请在 app/src/main/res/xml 中创建一个名为 actions.xml 的新 XML 文件。

在 Android Studio 中,请按以下步骤操作:

  1. 依次转到 File > New > XML > App Actions XML File
  2. Actions File Name 字段中输入“actions”。
  3. 点击 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>

在以上代码中,您可以使用 元素来定义与应用有关的 Action,以便在应用中让运动计时器开始和停止计时。intentName 属性与您使用与应用有关的 Action 执行的两个内置 intent 相对应,并且 元素可以向 Google 助理说明如何使用您的应用来实现相应 Action。

在该代码中,两个 Action 都是通过使用 urlTemplate 属性构建深层链接来执行的。网址模板使用您为 AndroidManifest.xml 文件中的深层链接定义的主机和架构。每个网址模板中的路径都与 handleDeepLink 函数(之前已添加到主 activity)的预期值相对应。

请注意,若要让计时器开始计时,您还要将内置 intent 中的 exercise.name 参数映射到 exerciseType 网址参数。这样一来,您的深层链接处理程序便可从 Google 助理获取其业务逻辑的参数。

确认您的 Android 清单是否引用 actions.xml

在上一步骤中,Android Studio 在 AndroidManifest.xml 中添加了对 actions.xml 文件的引用。您可以通过在 Android 清单中检查以下 元素来进行验证:

AndroidManifest.xml

<application>
    ...

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

如果您在清单文件中看到上述 元素,请继续测试您的与应用有关的 Action。

如果您在清单文件中没有看到上述 元素,请添加该元素。

测试与应用有关的 Action

现在可以在测试设备上试用您的与应用有关的 Action 了!

连接您的测试设备,然后使用测试工具来测试与应用有关的 Action:

  1. 依次转到 Tools > App Actions > App Actions Test Tool。系统可能会要求您登录 Android Studio。请使用之前用于登录 Google Play 管理中心的帐号。
  2. Invocation Name 字段中,输入“Fit Actions”。
  3. 如果 Google 助理的语言不是“English (US)”,请在 Locale 字段中输入与 Google 助理语言匹配的语言区域。
  4. 点击 Create Preview
  5. 使用 Configure 下拉列表,选择要测试的内置 intent。
  6. 点击 Run。如果系统显示使用 Google 打开的选项,请选择“Always”,以便让 Google 助理能够打开支持的链接(您以后可在应用设置中更改这项设置)。

与应用有关的 Action 测试工具创建或更新与应用有关的 Action 的预览时,它会针对单个 Google 帐号执行该操作,从而暂时注册您定义的与应用有关的 Action。借助该预览,Google 助理可在您将应用的正式版部署到 Google Play 管理中心之前识别您的与应用有关的 Action。

在该测试工具提取您应用的内置 intent 后,您可以直接为 intent 提供参数值,并通过 Android Studio 触发与应用有关的 Action!

除此之外,您还可以在设备上的 Google 助理应用中直接使用调用名称,以便试用您的与应用有关的 Action。例如,您可以通过说出“Ok Google, start running in Fit Actions”(Ok Google,在 Fit Actions 中开始跟踪跑步数据)来启动用于让运动计时器开始计时的与应用有关的 Action。

您现在可以通过 Google 助理让健身应用中的运动计时器开始和停止计时,不过您可能会发现,该应用只能识别某些运动项目。如果您说出“Start my swim in Fit Actions”(在 Fit Actions 中开始跟踪游泳数据)或“Start hiking in Fit Actions”(在 Fit Actions 中开始跟踪徒步旅行数据)之类的请求,计时器便会启动并显示文字“Start unknown in…”(…后开始跟踪未知运动项目数据)。

这是因为示例应用目前仅支持跟踪“跑步”、“骑车”和“步行”这几种运动类型。如何更好地满足想要使用该应用跟踪其他运动项目的用户的需求呢?

对于该应用,您可以通过以下几种方式增加支持的运动项目数量:

  • 添加对更多运动类型(例如游泳和攀岩)的应用支持(受 actions.intent.START_EXERCISE 内置 intent 支持的文本字段值的限制)。
  • 将其他支持的运动类型(例如“徒步旅行”)映射到应用中支持的运动类型(例如“步行”)。

如果您添加对更多运动类型的支持,您可以根据用户想要进行的运动项目在您的应用中关联更多路径。这是为用户提供帮助的一种方法;如果您的应用可针对不同运动项目执行不同的任务,选择这种方法就对了。

对于健身应用,您可以选择第二个选项,以便立即提高 Google 助理的适用性。选择该选项后,用户可以使用包含其他支持的文本字段值的查询来让计时器开始计时。在本 Codelab 中,您将使用内嵌目录将“Start hiking”(开始徒步旅行)映射到针对“Start walking”(开始步行)的应用功能。

内嵌目录

内嵌目录可定义在用户使用 Google 助理触发与应用有关的 Action 时,您的应用希望用户包含的特定实体。您可以在 actions.xml 文件中添加内嵌目录,以便直接针对用户创建支持的选项列表。目录项在 元素中进行分组,并且 Action 定义可以引用实体集以用于映射参数。

如前所述,示例应用具备支持“跑步”、“骑车”和“步行”的功能。您可以创建一个实体集并在 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>

内嵌目录中的每个 元素都表示相应用户查询的唯一匹配。借助这些实体,Google 助理可以区分支持的输入,例如跑步、步行和骑车。如果您想让 Google 助理识别特定于您的应用的某些信息(例如菜单项或服务),这些实体非常有用。

通过针对“hiking”字符串添加实体,您可以让徒步旅行者充分利用您已针对步行构建的功能!

测试您的目录

在测试工具中,创建或更新预览即会提取您的应用已注册的内置 intent。之后,您可以直接为 intent 提供参数值,并通过 Android Studio 触发与应用有关的 Action。

在与应用有关的 Action 测试工具中试用您的目录:

  1. 点击 Update Preview
  2. Configure 下拉列表中选择“actions.intent.START_EXERCISE”。
  3. exercise.name 字段中输入“hiking”。
  4. Select Target Device 下拉列表中选择您的设备。
  5. 点击 Run

与应用有关的 Action 测试工具使用输入“hiking”来让步行运动计时器开始计时(在测试设备上)。

恭喜您!

现在,您已掌握向 Android 应用添加与应用有关的 Action 所需的技能。

所学内容

  • 如何标识具有用户可通过与应用有关的 Action 触发的相应内置 intent 的 Android activity。
  • 如何将参数从内置 intent 传递到 Android 应用。
  • 如何使用内嵌目录将支持的值映射到应用功能标识符。
  • 如何在 Android Studio 中测试与应用有关的 Action。

后续操作

接下来,您可以尝试进一步优化您的健身应用。为了给您一些启发,我们在 GitHub 上的代码库的 master 分支中提供了该应用的扩展版本。该扩展版本使用 Android Slices 进一步通过 Google 助理展示运动信息。此外,它还整合了适用于正式版 Android 应用的与应用有关的 Action 部署要求

如需详细了解 Actions on Google,请浏览下列资源:

欢迎关注我们的 Twitter 帐号 @ActionsOnGoogle,及时了解我们的最新公告,还可以使用标签 #AoGDevs 发布 Twitter 微博,分享您构建的成果!

反馈意见调查

在您离开本页面前,请填写此表单,帮助我们改进本 Codelab。如果您遇到任何问题、需要更多信息以完成操作步骤,或想与我们分享顺利完成所有操作的经历,欢迎与我们联系!