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

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

关于此 Codelab

上次更新时间：5月 25, 2022

Google 助理开发者关系团队 编写

1. 概览

借助与应用有关的 Action，用户可以通过 Google 助理直接启动特定的应用功能，从而帮助您扩大 Android 应用的覆盖面。作为 Android 开发者，您可以实现相应的功能，让 Google 助理了解用户可以使用的功能类型以及您希望如何完成这些请求。

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

关键术语：Google 助理内置 intent（简称 BII）是用户想要实现的特定功能类型的预定义触发器。Google 负责构建和维护 BII 的语言模型，以解读与该特定 intent 相关的各种查询。

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

本 Codelab 介绍了与应用有关的 Action 相关开发的中级概念。您最好拥有开发 Android 应用和实现 Android intent 的经验。

构建内容

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

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

注意：具有搜索功能的应用必须实现 actions.intent.GET_THING BII。详细了解与应用有关的 Action 的部署要求。

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

学习内容

您将了解如何使用常用类别 BII 将 Google 助理的功能扩展到大多数 Android 应用。您还将了解如何使用适用于 Android Studio 的 Google 助理插件来测试常用 BII。

前提条件

• 已安装 git 的终端，用于运行 shell 命令。
• Android Studio 的最新稳定版本。
• 有权访问 Google Play 管理中心的 Google 帐号。
• 一台可连接到互联网以访问 Google Play 商店的 Android 实体设备或虚拟设备，该设备用于测试您的 Action。
• 您必须在测试设备上用同一个 Google 帐号登录 Android Studio、Google Play 管理中心、Google 应用和 Google 助理应用。

注意：您可以在少数几个语言区域内使用 Google 助理测试本 Codelab 中所述的与应用有关的 Action。请参阅常用 BII 参考文档，了解基于语言区域的可用 intent。

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

2. 了解运作方式

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

在用户向 Google 助理表明他们想要使用您的应用后，Google 助理会从 shortcuts.xml 文件中查找已向您的应用注册的与应用有关的 Action。此文件包含应用的各种功能，可将 Google 助理内置 intent 或自定义 intent 与 Android intent 或深层链接关联起来。

关键术语：功能是您在 shortcuts.xml 中定义的模板，用于声明用户启动应用时可以执行的操作类型，并会直接跳转到特定任务。如需了解详情，请参阅 Android 功能文档。

当用户向 Google 助理发出查询请求后，Google 助理会解析用户的输入，并将其与应用相关 Action 的 intent（在本 Codelab 中，这是一个 BII）匹配。Google 助理可以通过 Android 应用中的 shortcuts.xml 文件了解受支持的功能。进行 intent 匹配后，具有该 BII 的功能便会包含可执行该请求的方法。在此 Codelab 中，fulfillment 是一个在应用中启动 activity 的 Android intent。

下图展示了此 Google 助理流程：

图 2。描述 Google 助理如何处理语音查询的流程。

shortcuts.xml 项目文件包含每个与应用有关的 Action 的以下信息：

• 与应用有关的 Action 使用的内置 intent 或自定义 intent
• 应向用户提供的 Android activity 或深层链接
• 该内置 intent 的参数如何映射到用户提供给 Google 助理的信息

然后，您的 Android activity 会过滤并处理所提供的 Android intent 或深层链接，以便为用户提供所需的功能。这将产生如下的用户体验：Google 助理调用您的应用功能，以便响应用户的查询。

3. 准备开发环境

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

下载基础文件

运行以下命令以克隆示例应用的 GitHub 代码库：

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

克隆完代码库后，按照以下步骤在 Android Studio 中将其打开：

1. 在 Welcome to Android Studio 对话框中，点击 Import project。
2. 查找并选择克隆代码库的文件夹。

如需查看代表 Codelab 完成后的应用的版本，请使用 --branch master 标记克隆示例应用的代码库。

更改 Android 应用 ID 以启用测试

在本 Codelab 后面的内容中，你将使用 Google 助理插件在实体设备或虚拟设备上测试你的 Action。如要运行该测试工具，你必须先将应用上传到 Google Play 管理中心的某个项目。为避免在将你的应用上传到 Play 管理中心时出现“Duplicate package name”错误，请将示例应用的 applicationId 更改为唯一 ID（Google Play 不允许上传的任何两个应用具有相同 applicationId）。

在 app/build.gradle 中，将 applicationId“com.example.myapp”值更新为独一无二的 ID，如“com.codelabs.myname”。如需详细了解 applicationIds，请参阅设置应用 ID。以下代码段展示了更新后的 applicationId：

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 管理中心上传应用时可能出现的问题。

注意：请保持此 applicationId 可供访问；您稍后将在本 Codelab 中使用该 ID。

在设备上测试应用

在对该应用进行更多更改之前，最好了解一下该示例应用的功能。如需在模拟器上运行该应用，请按以下步骤操作：

1. 在 Android Studio 中，依次选择 Run > Run app，或点击工具栏中的 Run 图标 。
2. 在 Select Deployment Target（“选择目标部署”）对话框中，选择设备，然后点击 OK（“确定”）。虽然 Action 在搭载 Android 5（API 级别 21）的设备上也能运行，但我们推荐使用的操作系统版本是 Android 10 （API 级别 30）或更高版本。
3. 长按主屏幕按钮以设置 Google 助理并验证其是否正常运行。你需要在设备上登录 Google 助理（如果你尚未登录的话）。

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

图 3. 演示待办事项列表示例应用的动画。

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

上传到 Play 管理中心

你必须将应用上传到 Google Play 管理中心内的项目，然后才能在 Android Studio 中使用 Google 助理插件。在 Android Studio 中构建您的应用，并将其作为内部版本草稿上传到 Play 管理中心。

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

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

在 Google Play 管理中心内，请按照以下步骤将您刚刚创建的 app bundle 作为新应用进行上传：

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

注意：如果您在将应用上传到 Play 管理中心时遇到问题，请参阅与应用有关的 Action 问题排查指南。

安装测试插件

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

1. 依次转到 File > Settings（在 MacOS 中，依次转到 Android Studio > Preferences）。
2. 在“插件”部分中，转到 Marketplace 并搜索“Google 助理”。您也可以手动下载并安装测试工具。
   • 如果您在 Marketplace 中找不到该插件，请手动下载该插件，然后按照从磁盘安装该插件中的说明操作。
3. 安装该工具，然后重启 Android Studio。

注意：该测试插件会通过 Android 设备上的 Google 应用向 Google 助理发送信息。

4. 添加“Get Thing BII”功能

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

提示：GET_THING BII 用于使用默认的应用内搜索功能来搜索应用中的内容或实体。通过 thing.name intent 参数使用内容或实体名称来填充搜索条件，并向用户展示最相关的搜索结果。

定义“Get Thing”功能

在执行与搜索相关的与应用有关的 Action 期间，Google 助理会将用户查询中的搜索字词提取到 thing.name BII 参数中，然后将该值传递给 Android 应用。

如需将 GET_THING BII 添加到您的应用，请更新 shortcuts.xml（位于 app/src/main/res/xml 示例项目目录中），并在顶层 <shortcuts> 标记中添加 <capability> 元素：

shortcuts.xml

<shortcuts ....>
    <capability android:name="actions.intent.GET_THING">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.yourApplicationId.appaction"
            android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
            <parameter
                android:name="thing.name"
                android:key="q"/>
        </intent>
    </capability>
</shortcuts>

上面的配置会：

1. 声明应用会响应 GET_THING BII。
2. 指定如何构建一个 Android intent 来启动应用响应该 BII。
   • 该 activity 使用 targetPackage 和 targetClass 进行标识。
   • BII 参数 thing.name 会映射到名为 q 的 intent extra。

指定的 activity 必须存在于应用的清单中，并且必须已导出。

提供的 Android 应用包含元数据，因此 AndroidManifest 可以识别 shortcuts.xml 文件：

<meta-data
   android:name="android.app.shortcuts"
   android:resource="@xml/shortcuts" />

测试与应用有关的 Action

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

1. 确保您的 Android 设备已连接。
2. 依次点击 Tools > Google Assistant > App Actions Test Tool。
3. 点击创建预览，接受应用名称和语言区域的默认设置。
4. 在第一步中，该工具会让你选择并配置一个 BII；请选择 actions.intent.GET_THING。 将 name 值从 running shoes 更改为 milk。
5. 点击 Run App Action。

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

提示：如果您在运行该测试工具时遇到问题，请参阅问题排查指南。

5. 添加 Open app feature BII 功能

在该步骤中，您将实现 Open app feature BII，让用户能够使用 Google 助理查看正在进行的任务和已完成的任务。为此，请在 shortcuts.xml 中实现相应功能，其中包含有关如何触发功能、如何传递参数以及要调用哪些 Android intent 的信息。在本 Codelab 中，您将使用 OPEN_APP_FEATURE BII。实现此 BII 后，即可在您的设备上测试 Action。

注意：此 BII 会启动该应用的一项功能。此 intent 特别适合用于帮助用户导航到您应用内可能难以找到的功能或需要多次点按才能找到的功能。您必须为该功能参数指定内嵌目录。

添加 Open app feature 功能

在 shortcuts.xml 中的“Get Thing”功能元素下为 Open app feature 添加另一个功能：

shortcuts.xml

<capability android:name="actions.intent.OPEN_APP_FEATURE">
   <intent
       android:action="android.intent.action.VIEW"
       android:targetPackage="yourApplicationId"
       android:targetClass="com.example.android.architecture.blueprints.todoapp.tasks.TasksActivity">
       <parameter
           android:name="feature"
           android:key="feature"/>
   </intent>
</capability>

此功能会将 Open app feature BII 和 Android intent 相互映射，因此触发 Open app feature 时，也会触发 Android intent。

在触发 Android intent 之前，系统会从用户的输入中提取受支持的参数。OPEN_APP_FEATURE BII 支持一个参数，即 feature，它代表从用户查询中提取的应用功能。此应用将支持两种类型的功能：正在进行的任务和已完成的任务。使用相应功能，用户将能够在打开应用时仅显示过滤后的任务列表视图。您需要使用内嵌目录来支持这些功能。

关键术语：内嵌目录通过向支持内嵌目录的 BII 参数提供应用能够解读的一组实体，来指导系统针对 BII 提取相应实体。如需了解详情，请参阅与应用有关的 Action 的内嵌目录。

使用内嵌目录处理 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 参数，请在 shortcuts.xml 中添加快捷指令，并在 Open app feature 功能上方添加以下代码：

shortcuts.xml

<shortcut
   android:shortcutId="active_tasks"
   android:shortcutShortLabel="@string/label_active"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/active_tasks_synonyms" />
   </capability-binding>
</shortcut>

<shortcut
   android:shortcutId="completed_tasks"
   android:shortcutShortLabel="@string/label_completed"
   android:enabled="false">
   <capability-binding
       android:key="actions.intent.OPEN_APP_FEATURE">
       <parameter-binding
           android:key="feature"
           android:value="@array/completed_tasks_synonyms" />
   </capability-binding>
</shortcut>

在上面的代码中，您定义了一个内嵌目录，以具有功能和参数绑定的 shortcut 元素表示。快捷指令可用作 BII 参数的目录。Google 助理会将用户查询与快捷指令的参数绑定值进行匹配。对于匹配的参数值，系统会将 shortcutId 添加到 fulfillment intent 中。当用户通过请求激活 OPEN_APP_FEATURE BII 时，Google 助理会将功能参数值与快捷指令的值属性进行匹配，并将该值作为 Extra 中的 parameter 传递给 targetClass。

例如，如果用户说出类似“Ok Google, show my completed tasks in ExampleApp”（Ok Google，在 ExampleApp 中显示我已完成的任务）这样的语音指令，Google 助理会将功能 intent 参数值“completed tasks”（已完成的任务）匹配到对应的目录快捷指令，并将该值传递给 OPEN_APP_FEATURE 功能。然后，Google 助理会触发 Android intent。

测试与应用有关的 Action

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

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

1. 连接实体 Android 测试设备，或启动 Android 模拟器
2. 如果看不到该测试工具，请依次转到 Tools > Google Assistant > App Actions Test Tool 以打开该工具。
3. 点击更新按钮刷新预览。
4. 在第一步中，该工具会让你选择并配置一个 BII；请选择 actions.intent.OPEN_APP_FEATURE。
5. 在 feature 框中，使用 Completed tasks 更新默认的 History 值。
6. 点击 Run App Action。

提示：如果您在运行该测试工具时遇到问题，请参阅问题排查指南。

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

6. 后续步骤

恭喜！

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

所学内容

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

• 如何利用 Google 助理让用户深入体验特定的应用功能。
• 用户如何通过 Google 助理访问应用内搜索。
• 如何使用 Google 助理插件测试常用 BII。

后续步骤

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

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

• 查看采用 Google Analytics for Firebase 的待办事项列表示例，了解如何跟踪与应用有关的 Action 的表现。
• 访问与应用有关的 Action“内置 intent”参考文档，探索将你的应用扩展到 Google 助理的更多方法。

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

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

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

反馈意见调查

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