构建与应用有关的 Action

借助与应用有关的 Action，用户可以通过向 Google 助理发出语音指令，或使用 Google 助理建议的 Android 快捷方式，来启动 Android 应用中的功能。您可以通过以下主要步骤使用与应用有关的 Action 扩展 Android 应用：

1. 确定要触发的应用内功能及其匹配的内置 intent (BII)。
2. 提供内置 intent 的执行方式详细信息。
3. 将与应用有关的 Action 的快捷方式推送到 Google 助理。
4. 在测试设备上预览与应用有关的 Action。
5. 创建应用的测试版本。
6. 请求审核和部署与应用有关的 Action。

您可以视需要定义要向 Google 助理提供的动态快捷方式，以便其向您的用户推荐这些指令。如需尝试使用示例应用创建与应用有关的 Action，请按照与应用有关的 Action Codelab 中的说明操作。

注意：由于监管限制，参与亲子同乐 (DFF) 计划的应用不允许采用与应用有关的 Action。如果您针对参与 DFF 计划的应用提交与应用有关的 Action 以供审核，将无法获得批准。

要求

在开始开发与应用有关的 Action 之前，请确保您和您的应用满足以下要求：

• 您必须拥有能够访问 Google Play 管理中心的 Google 账号。
• 您的应用必须发布到 Google Play 商店，因为与应用有关的 Action 仅适用于发布到 Google Play 商店的应用。此外，请确保您的应用不打算在工作资料中使用，因为 Google Play 企业版不支持与应用有关的 Action。
• 您需要一个实体或虚拟设备来测试您的与应用有关的 Action。
• 您需要使用最新版 Android Studio。
• 您必须使用同一个 Google 账号登录 Android Studio、测试设备上的 Google 应用以及 Google Play 管理中心。
• 您必须在测试设备上设置助手，并通过触摸并按住 Home 按钮来测试它。

将内置 intent 与应用功能进行匹配

确定您的 Android 应用中用户可能希望通过语音请求跳转到的功能，并查看内置 intent 参考文档 以找到适合您的应用场景的 BII。BII 会针对用户想要执行的任务对用户查询进行建模，因此需要查找与您应用中的关键功能和用户流匹配的 BII。

有一些常用 BII 可供几乎所有 Android 应用使用，例如使用 actions.intent.GET_THING BII 可将应用内搜索扩展到 Google 助理，或者实现 actions.intent.OPEN_APP_FEATURE BII 就能让用户通过语音启动特定应用功能。

重要提示：按照与应用有关的 Action 的部署要求，具有搜索功能的应用必须实现 actions.intent.GET_THING BII，这样用户才能通过常用的语音指令（例如：“Hey Google, search for running shoes on ExampleApp”）在应用中搜索内容。

此外，还有一些针对行业或具体类别应用场景的 BII。例如，锻炼应用可以使用 actions.intent.START_EXERCISE BII。

注意：如果您的应用功能没有适用的 BII，您可以使用自定义 intent 来通过与应用有关的 Action 扩展应用。

为了提供出色的用户体验并避免可能出现的审批延迟，请确保您实现的每个 BII 都与应用内功能相关。

与应用有关的 Action 的工作原理是从 Google 助理应用启动 Android intent，让用户直接转到应用中的特定内容。您可以通过指定 targetClass 和 targetPackage 字段来定义这些 intent，以显式启动某个 activity。如果您的应用已实现 Android 深层链接网址，您可以选择将 intent 配置为使用执行方式的深层链接。如需了解详情，请参阅测试您的 activity 深层链接部分。

提供内置 intent 的执行方式详细信息

构建与应用有关的 Action 的大部分工作是在 Android 应用的 shortcuts.xml 资源文件中声明 capability，您可以在其中指定选择的 BII 及其对应的执行方式。BII 会针对任务为用户查询建模，执行方式 intent 则会向 Google 助理提供有关如何执行该任务的信息。

在 shortcuts.xml 文件中，BII 表示为 <capability> 元素，每个执行方式表示为一个 <intent> 元素：

<shortcuts>
    <capability android:name="actions.intent.START_EXERCISE">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.app"
            android:targetClass="com.example.app.browse">
            <parameter
                android:name="exercise.name"
                android:key="exercise_name">
            </parameter>
        </intent>
    </capability>

注意 ：您的 Android 项目需要使用 Jetpack 库 androidx.core:core:1.6.0（或更高版本），以免在 shortcuts.xml 中定义与应用有关的 Action 的 capability 时出现编译错误。如需了解详情，请参阅 Android Jetpack 使用入门。

对于大多数 BII，您可以根据 schema.org 实体从用户查询中提取 intent 参数。然后，您的应用会使用这些 BII 参数将用户引导至所选的 capability。例如，上述代码会将 exercise.name BII 参数映射到 exercise_name Android intent 参数。

如果您是使用深层链接执行操作，可以使用 urlTemplate 字段来定义 Google 助理生成的深层链接网址：

<shortcuts>
    <capability android:name="actions.intent.START_EXERCISE">
        <intent android:action="android.intent.action.VIEW">
            <url-template android:value="myexerciseapp://start{?exercise_name}" />
            <parameter android:name="exercise.name"
                android:key="exercise_name"
                android:mimeType="text/*">
            </parameter>
        </intent>
    </capability>
</shortcuts>

提示：如果应用为单个 BII 提供了多个要执行的 intent，Google 助理会尝试按照这些 intent 在 capability 元素中的显示顺序进行解析。

如需详细将与应用有关的 Action 添加到 shortcuts.xml 文件中的重要信息，请参阅创建 shortcuts.xml。该页面还描述了如何指定您的应用期望的参数值。

实现 GET_THING 内置 intent

如果您的应用具有搜索功能，您需要为该功能实现 actions.intent.GET_THING BII。之后，当用户进行诸如“Hey Google, search for Example Thing on Example App”之类的查询时，Google 助理便可为对方打开您应用的搜索功能，以提供应用内搜索结果。

在 shortcuts.xml 文件中，您可以为 actions.intent.GET_THING BII 实现 <capability>，就像实现所有其他 BII 一样。只要您提供的执行方式中至少有一个会将用户查询传递给应用的搜索功能，就可以对 GET_THING 使用多个执行方式。

以下示例展示了如何在 shortcuts.xml 中添加 actions.intent.GET_THING BII：

  <capability android:name="actions.intent.GET_THING">
    <intent
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.MySearchActivity">
      <parameter android:name="thing.name" android:key="query" />
    </intent>
  </capability>

在搜索 Activity 中，从 intent 的额外数据中提取搜索查询，并将其传递给应用的搜索功能。在上述代码中，搜索查询（以 query 键的形式传递）会映射到 "thing.name" BII 参数。然后，使用该查询执行搜索并在界面中显示结果。

（可选）将与应用有关的 Action 的快捷方式推送到 Google 助理

当您为操作定义 capability 后，用户只需说出“Hey Google, order a pizza on Example App”之类的语音指令即可轻松启动相应操作。Google 助理可以适时为用户提供与您的操作相关的 Android 快捷方式建议，以便用户发现和再次执行您的操作。Google 助理可以提供动态快捷方式和静态快捷方式建议。

如需将动态快捷方式推送到 Google 助理，请使用 Google 快捷方式集成库。借助此 Jetpack 库，Google 助理可以提取您的快捷方式，并在适当的时间向用户推荐这些快捷方式。

如需了解详情，请参阅将动态快捷方式推送到 Google 助理。

预览与应用有关的 Action

在开发和测试期间，请使用适用于 Android Studio 的 Google 助理插件测试与应用有关的 Action 是否适用于您的应用。该插件会在 Google 助理中针对您的 Google 账号创建与应用有关的 Action 的预览。使用该测试工具，您可以通过为 BII 提供您希望从用户那里收到的输入参数，在实体测试设备或模拟器上测试您的执行方式。

注意：您还可以为与应用有关的 Action 的集成添加其他测试人员，即使对方不共用同一个 Play 管理中心账号也没问题。如需了解详情，请参阅添加其他测试人员。

预览与应用有关的 Action 时，您可以在设备上通过语音触发查询。此功能仅适用于与应用有关的 Action 的 BII 参考文档中列出的查询。仅将语音触发用于演示目的，而不是常规测试。

注意：除非在相应的内置 intent 参考文档中提供了针对其他语言区域的示例查询，否则与应用有关的 Action 测试工具将仅支持在 en-US 语言区域中测试 BII。

在提交应用以供审核之前，请先使用 Google Play 管理中心的开发者工具在草稿模式下测试您的应用。如需详细了解如何使用 Google Play 管理中心部署应用的草稿版本，请参阅准备工作和版本发布。

创建测试版本

当您准备好与其他测试人员一起测试与应用有关的 Action 时，请创建应用的内部或封闭测试版本。默认情况下，您的内部和封闭发布测试人员可以访问已经过审核和批准的与应用有关的 Action。

如需授予对所有与应用有关的 Action（包括未获批准的操作）的测试访问权限，请让测试人员加入 App Actions Development Program Google 群组。作为此群组的成员，测试人员无需使用与应用有关的 Action 测试工具创建预览，即可访问封闭式版本和内部测试版本中的所有与应用有关的 Action。加入群组后最多可能需要三个小时才能获得访问权限。

注意：开放式测试轨道版本中的与应用有关的 Action 必须经过审核并获得批准，才可供用户使用。如需了解详情，请参阅下一部分。

请求审核和部署与应用有关的 Action

与应用有关的 Action 只有在经过审核并获得批准之后才能供已发布应用或开放式测试版本的用户使用。与应用有关的 Action 的审核不会影响 Android 应用在 Google Play 中的审核和部署状态。即使您提交的应用获得批准并发布到 Play 商店，Google 可能仍在审核您的 shortcuts.xml。在此审核也获得批准之前，最终用户无法使用与应用有关的 Action。

在您部署应用时，与应用有关的 Action 会保持激活状态。但是，重新部署的版本需要接受 Google 的审核。如果新版本无法正常工作或存在违反政策的问题，Google 保留为应用停用与应用有关的 Action 的权利。

如需提交与应用有关的 Action 以供审核，请执行以下操作：

1. 在 Google Play 管理中心内接受与应用有关的 Action 的服务条款（高级设置 > 与应用有关的 Action）：

   

2. 像往常一样上传应用（包含 shortcuts.xml）到 Google Play 管理中心进行发布。

3. 在您将应用上传到 Play 管理中心后，Google 会通过 Play 管理中心账号所用的电子邮件地址与您联系，为您提供有关与应用有关的 Action 的审核状态的更多信息。您也可以联系 Google 助理开发者支持团队，咨询与应用有关的 Action 的审核状态方面的问题。请在联系表单中，提供应用软件包 ID，并在您需要什么帮助？选择框中选择与应用有关的 Action 审核。

注意 ：如果您的应用需要登录凭据才能访问，请在提交应用时提供测试用登录信息。如需提供测试凭据，请在 Play 管理中心选择您的应用，依次浏览至政策 > 应用内容，然后按照针对应用访问权限列出的说明操作。

（可选）测试 activity 深层链接

要使用深层链接通过与应用有关的 Action 启动 Activity，必须使用深层链接 URL 设置 Activity，并在 Android 应用清单中具有相应的 intent 过滤器。

注意：深层链接可以 App Links 网址、基于 intent 的网址或自定义架构（例如 myapp://do.thing/param=value）为基础。

如需测试您的 activity 是否可访问以及是否可使用采用深层链接的与应用有关的 Action 触发，请运行以下 adb 命令：

$ adb shell am start -a android.intent.action.VIEW -d "AppLinksURL"

例如：

$ adb shell am start -a android.intent.action.VIEW -d "https://www.example.com/deeplink"

如果无法通过 adb 命令正确启动 activity，请检查以下内容：

• 该 activity 是否在应用清单文件中具有 android:exported=true，以便可以通过 Google 助理使用 intent 进行启动。
• 如果使用的是 App Links 网址，请按照处理 Android App Links 中的所有步骤操作。

与应用有关的 Action 政策

与应用有关的 Action 必须遵守特定政策，以确保触发它们的用户获得预期的体验。在提交您的应用之前，请查阅这些政策，以提供最佳的用户体验，并避免 Play 商店审核延迟或被拒。

• 将用户定向到用户想要的内容

  与应用有关的 Action 内置 intent (BII) 和/或参数必须仅将用户定向到用户所期望的相关 Action。这可以包括应用内内容、网站内容，或者在 Slice 或 widget 中显示的信息，只要这种体验符合用户的预期。

  例如，START_EXERCISE BII 的实现可帮助用户发起某种类型的锻炼，例如跑步或游泳。此政策的唯一例外是当您的 OPEN_APP_FEATURE BII 将用户定向到应用的主屏幕时。

• 实现相关的与应用有关的 Action BII

  实现的 BII 必须与应用的内容和功能直接相关。

  例如，如果您的应用属于“通信 Play 商店”类别，请勿实现 START_EXERCISE BII，这是建议用于健康与健身类别的应用。

• 实现相关的自定义 intent

  自定义 intent 的定义查询与应用的内容和功能相关。潜在违反此政策的示例是为 Play 商店“交通”类别中的应用创建带有关联查询模式“Show me burrito recipes”的 custom.action.intent.GET_RECIPE intent。

---