借助与应用有关的 Action 将 Android 应用扩展到 Google 助理（第 2 级）

在第一个关于与应用有关的 Action 的 Codelab 中，您学习了如何通过实现“健康与健身内置 intent”类别中的内置 intent (BII) 将 Google 助理的功能扩展到示例健身应用。BII 划分为多个类别，各个类别代表用户经常要求 Google 助理执行的各种任务。

在本 Codelab 中，您将学习如何使用 [常用 BII 类别] 中的 BII 向应用添加与应用有关的 Action，这些类别代表几乎所有 Android 应用都可以执行的常见应用任务。

本 Codelab 介绍了与应用有关的 Action 相关开发的中级概念。您最好拥有开发 Android 应用、处理深层链接、创建 actions.xml 资源以及使用与应用有关的 Action 测试工具插件的经验。之前没接触过与应用有关的 Action 的开发者最好先从上一个 Codelab 开始学习。

构建内容

在本 Codelab 中，您将向示例待办事项列表应用添加两个常用 BII，以便让用户能够要求 Google 助理执行以下任务：

转到应用内的各种功能，为此，您将使用 actions.intent.OPEN_APP_FEATURE BII。
使用应用内搜索功能搜索内容，为此，您将使用 actions.intent.GET_THING BII。

3 个进程屏幕，其中显示的是 Google 助理显示应用中正在进行的任务。

学习内容

如何使用常用类别 BII 将 Google 助理的功能扩展到大多数 Android 应用。
如何使用与应用有关的 Action 测试工具插件测试常用 BII。

前提条件

已安装 git 的终端，用于运行 shell 命令。
Android Studio 的最新稳定版本。
有权访问 Google Play 管理中心的 Google 帐号。
可连接到互联网以访问 Google Play 商店的 Android 设备或模拟器，用于测试您的 Action。

在本 Codelab 中，您将使用 Android 设备（实体设备或模拟器）来测试您的 Action。如果使用的是实体设备，请确保该设备已连接到您的本地开发机器。此外，您还必须在该设备（或模拟器）上登录 Google 应用，并使用同一 Google 帐号登录 Android Studio。设备还必须安装 Google 助理应用。

在本 Codelab 中，我们将从一款适用于 Android 的待办事项列表示例应用开始学习。该示例应用的用户可向待办事项列表添加项、按类别搜索列表项，以及查看已完成任务的相关信息。

下载基础文件

运行以下命令以克隆示例应用的 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 以启用测试

在本 Codelab 后面的内容中，您将使用与应用有关的 Action 测试工具在 Android 设备或模拟器上测试您的 Action。如要运行该测试工具，您必须先将应用上传到 Google Play 管理中心的某个项目。为避免在向 Play 管理中心上传应用时出现“Duplicate package name”（软件包名称重复）错误，请将示例应用的 applicationId 更改为独一无二的名称。

在 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 后，您可能会在 IDE 中看到一个黄色警告框，其中标有“Gradle files have changed since last project sync…”（上次项目同步后，Gradle 文件已更改）提示。如果发生这种情况，请点击该方框中的 Sync Now，以避免在向 Play 管理中心上传应用时可能出现的问题。

在设备上测试应用

在对该应用进行更多更改之前，最好了解一下该示例应用的功能。请尝试在模拟器上运行该应用：

在 Android Studio 中，依次选择“Run”>“Run app”，或点击工具栏中的 Run 图标。
在“Select Deployment Target”对话框中，选择虚拟设备，然后点击“OK”。虽然 Action 在搭载 Android 5（API 级别 21）的设备上也能运行，但我们推荐使用的操作系统版本是 Android 10 （API 级别 30）或更高版本。

长按主屏幕按钮，以便设置 Google 助理并验证它能否在您的设备上正常运行。您需要在设备上登录 Google 助理（如果您尚未登录的话）。

如需详细了解 Android 虚拟设备，请参阅：创建和管理虚拟设备。

演示待办事项列表示例应用的动画

快速浏览该应用以了解其功能。点按加号图标可创建新的任务项；借助右上角的菜单项，您可以按完成状态搜索和过滤任务项。

上传到 Play 管理中心

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

如需在 Android Studio 中构建应用，请按以下步骤操作：

依次转到 Build > Generate Signed Bundle / APK。
选择“Android App Bundle”，然后点击 Next。
输入详细信息以对应用进行签名，然后点击 Next。
选择“prodRelease”build 变体，然后点击 Finish。

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

在所有应用页面上，点击创建应用。
随意为该应用命名，然后点击创建应用。在本 Codelab 中，您无需在应用创建完成后填写任何应用信息。
在边栏菜单中，转到测试并找到 内部测试页面。
点击内部测试页面上的创建新版本。
点击继续以同意使用 Google Play 应用签名。
在 app bundle 和 APK 面板中，上传您之前生成的 AAB 文件（该文件可能位于 app/prod/release 目录中）。点击保存。

安装测试插件

借助与应用有关的 Action 测试工具插件，您可以在测试设备上针对单个用户测试与应用有关的 Action。如果您还没有安装该测试工具，请按以下步骤进行安装：

依次转到 File > Settings（在 MacOS 中，依次转到 Android Studio > Preferences）。
在“Plugins”部分中，转到 Marketplace 并搜索“App Actions test tool”。此外，您还可以手动下载并安装该测试工具。
安装该工具，然后重启 Android Studio。

在该步骤中，您将实现 Open app feature BII，让用户能够使用 Google 助理查看正在进行的任务和已完成的任务。为此，您可以通过在 actions.xml 中定义该 BII 来将任务过滤功能的现有深层链接扩展到 Google 助理。您将通过在设备上测试 Action 来完成这一部分的学习。

测试深层链接

实现 BII 之前，请验证您应用中的现有深层链接是否与您确定的与应用有关的 Action 的行为相符。

如需使用 Android 调试桥 (adb) 命令行工具来测试深层链接，请按以下步骤操作：

在您的设备上更新相应应用。
通过点按位于应用栏菜单中的刷新按钮，使用示例项填充待办事项列表：

待办事项列表工具栏菜单

如果系统显示使用 Google 打开的选项，请选择“Always”，以便让待办事项应用能够打开支持的链接。您以后可以在应用设置中更改该偏好设置。

在您的终端内，逐个输入以下 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

将任务过滤深层链接扩展到 Google 助理，方法是在 actions.xml 中定义已配置为可打开此类链接的 Open app feature BII。

使用以下代码更新位于 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>

使用内嵌目录处理 intent 参数

intent 参数表示从用户查询中提取的元素。例如，如果用户说出类似“Ok Google, order a pizza from ExampleApp”（Ok Google，从 ExampleApp 订一份披萨）这样的语音指令，Google 助理会将“pizza”（披萨）提取到 food.item schema.org intent 元素，并将该参数传递到您的 Action 以便处理该指令。

Open app feature BII 支持一个参数，即 feature，它代表从用户查询中提取的应用功能。该参数需要内嵌目录，以便为 Google 助理提供一组支持的应用功能名称（用于匹配相应参数值）。

如需处理 feature intent 参数，请使用以下代码更新 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>

借助以上示例代码，您已指示 Google 助理将功能参数值与内嵌目录 FeatureEntitySet 相匹配（已在相应参数标记中定义为 entity-set-reference）。

为您的 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 后，Google 助理会将 feature 参数值匹配到 entity 的 name 属性，以便将匹配的 entity 的 url 传递到您的执行方式。

例如，如果用户说出类似“Ok Google, show my completed tasks in ExampleApp”（Ok Google，在 ExampleApp 中显示我已完成的任务）这样的语音指令，Google 助理会将 feature intent 参数值“completed tasks”（已完成的任务）匹配到对应的目录 entity。然后，Google 助理会将关联的网址 https://todo.androidappactions.com/completed-tasks 发送到您的执行方式。

定义 Action 执行方式

如需执行 Action，您需要在 actions.xml 中定义 fulfillment 元素，以便处理 Google 助理传递的网址。使用以下代码将 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>

在以上示例中，您定义了两个 fulfillment 元素。第一个元素可触发 Google 助理根据 feature 参数生成的深层链接（表示为 urlTemplate 属性中的 {@url} 占位符）。第二个 fulfillment 是用于打开任务视图的备用执行方式，可在 feature 参数缺失，或找不到匹配的内嵌目录 element 的情况下显示未经过滤的任务列表。

测试与应用有关的 Action

在开发和测试期间，您可以使用与应用有关的 Action 测试工具，在测试设备上通过 Google 助理预览与应用有关的 Action。此外，您还可以使用该工具调整与应用有关的 Action 的 intent 参数，以便测试您的 Action 会如何处理用户在要求 Google 助理运行 Action 时可能采用的各种方式。

如需使用该测试工具测试您的与应用有关的 Action，请按以下步骤操作：

连接实体 Android 测试设备，或启动 Android 模拟器
依次转到 Tools > App Actions > App Actions Test Tool。系统可能会要求您登录 Android Studio。请使用之前用于登录 Google Play 管理中心的帐号。
在 Invocation Name 字段中，输入“Task List”。
如果 Google 助理的语言不是“English (en)”，请在“Locale”字段中输入与 Google 助理语言匹配的语言区域。
点击 Create Preview。
使用 Configure 下拉列表，选择 actions.intent.OPEN_APP_FEATURE intent。
在 feature 方框中，使用“Completed tasks”更新默认的“History”值。
点击“Run”。

除此之外，您还可以在设备上的 Google 助理应用中直接使用调用名称，以便试用您的与应用有关的 Action。例如，您可以说“Ok Google, show completed tasks in Task List”（Ok Google，在任务列表中显示已完成的任务）。

Get things BII 可将应用内搜索功能扩展到 Google 助理。在该步骤中，您将实现并测试 Get things BII，以便让用户能够在示例应用中搜索特定任务。

测试深层链接

示例应用包含应用内搜索功能的现有深层链接。实现 BII 之前，请使用 adb 验证该深层链接是否与您确定的与应用有关的 Action 的行为相符。

使用以下 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”的项列表 activity。

添加 BII

在执行与搜索相关的与应用有关的 Action 期间，Google 助理会将用户查询中的搜索字词提取到 thing.name intent 参数中。然后，Google 助理会将相应参数映射到您在 fulfillment 元素中定义的网址模板，以便针对执行方式生成网址。

如需在应用中定义 Get things BII，请使用以下新 Action 更新 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 intent 参数分配给 fulfillment 元素的 urlParameter 属性的“q”值。然后，Google 助理会将 urlParameter 值映射到 fulfillment urlTemplate 中的“{q}”占位符，以便生成深层链接。

测试与应用有关的 Action

如需通过 Google 助理测试您应用的应用内搜索功能，请按以下步骤操作：

连接实体 Android 测试设备，或启动 Android 模拟器
依次转到 Tools > App Actions > App Actions Test Tool。
点击 Update Preview。
使用“Configure”下拉列表，选择 actions.intent.GET_THING intent。将“name”的值从“running shoes”更改为“milk”。
点击 Run。

在该测试中，Get things BII 使用 name 属性在应用中搜索包含“home”的任务。与前面的与应用有关的 Action 一样，您可以使用测试工具来测试您的 Action，也可以在测试设备上直接说“Ok Google, search for cake mix in Task List”（Ok Google，在任务列表中搜索蛋糕混合配料）或其他搜索词组。

恭喜您！

现在，您几乎可以借助常用 BII 让任何 Android 应用与 Google 助理搭配使用。

所学内容

在本 Codelab 中，您学习了以下内容：

如何利用 Google 助理让用户深入体验特定的应用功能。
用户如何通过 Google 助理访问应用内搜索。
如何使用与应用有关的 Action 测试工具测试常用 BII。

后续操作

接下来，您可以尝试进一步优化您的任务列表应用。如需参考完成后的项目，请参阅 GitHub 上的代码库的 –master 分支。

如需进一步了解如何使用与应用有关的 Action 扩展该应用，请参阅以下建议：

查看采用 Google Analytics for Firebase 的待办事项列表示例，了解如何跟踪与应用有关的 Action 的表现。
使用 Slice 显示嵌入虚拟卡片且用户可通过 Google 助理与其互动的列表项。
访问与应用有关的 Action 内置 intent 参考页面，了解将您的应用扩展到 Google 助理的更多方法。

如需继续了解 Actions on Google，请浏览下列资源：

actions.google.com：Actions on Google 的官方文档网站。
与应用有关的 Action 示例索引：用于探索与应用有关的 Action 的功能的示例应用和代码。
Actions on Google GitHub 代码库：示例代码和库。
r/GoogleAssistantDev：从事 Google 助理相关工作的开发者的官方 Reddit 社区。

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

反馈意见调查

最后，请填写该调查问卷，就您学习本 Codelab 的体验提供反馈意见。