内嵌目录

在为 Android 应用实现与应用有关的 Action 时，您可能会发现自己必须处理的请求属于同一主题的不同变体。例如，假设您的健身应用实现了 START_EXERCISE 内置 intent (BII)，可让用户通过向 Google 助理下达“Hey Google, start a run on Example App”之类的语音指令来启动各种锻炼项目。

若要执行此 intent，您需要请求匹配逻辑来处理包括“jog”“sprint”或“race”等变体在内的各类锻炼项目。随着支持的锻炼项目增加，这种逻辑很快就会变得非常繁琐。

对于受支持的 BII（例如 START_EXERCISE），您可以使用内嵌目录来避免这种复杂的匹配逻辑。内嵌目录是在 shortcuts.xml 中定义的一组静态 Android 快捷方式，代表应用中的功能和内容。

每个快捷方式都包含一个项目标识符和一个同义词列表（代表用户如何引用相应项目的不同变体）。在调用过程中，该 BII 会将用户提供的 BII 参数与同义词列表进行比较。如果找到匹配项，BII 参数便会更新为匹配快捷方式的项目标识符。

利用内嵌目录，Google 助理便可简化在调用与应用有关的 Action 期间向应用提供的 BII 参数值。

内嵌目录的作用类似于 BII 参数的对照表，会使用您定义的项目标识符来表达用户引用应用功能或内容的各种方式。这种目录可让您的执行方式预测 BII 参数中的项目标识符，从而简化应用的请求匹配逻辑。

内嵌目录用户流程图
图 1. START_EXERCISE capability 的流程图：运用内嵌目录将用户提供的健身项目名称解读为应用支持的运动类型。

限制和替代方案

内嵌目录快捷方式具有以下限制：

  • 快捷方式限制：每个应用最多可以定义 1,000 个内嵌目录快捷方式。
  • 同义词限制：每个内嵌目录快捷方式最多可以包含 20 个同义词值。
  • 静态定义：内嵌目录快捷方式以静态方式在 shortcuts.xml 中进行声明，并且只能通过发布应用新版本的方式为用户提供更新。

由于需要静态配置，因此内嵌目录最适合将不常更改的非个性化应用信息（如菜单项、公交路线或饮品杯型）扩展到 Google 助理端。对于其他类型的内容，请考虑以下替代方案：

  • 网站目录：可让 Google 助理在为用户查询匹配支持的应用内容标识符时，查询公开的 Web 内容。网站目录查询是在调用期间实时执行的，因此，您可以将商品清单、社交媒体帖子以及其他经常更新的内容扩展到 Google 助理端。

  • 动态快捷方式：可将个性化应用内容的目录扩展到 Google 助理端。动态快捷方式可让用户快速再次执行常见操作，例如从订餐应用中再次订购喜欢的饮品，或在记事应用中提取购物清单。

创建内嵌目录

内嵌目录为 Google 助理提供了一种便捷方式，可将用户在请求应用内容和功能时采用的各种方式转换为应用预期的可预测标识符，从而简化开发工作。例如，假设您的应用提供了各种用户可通过语音启动的锻炼项目，并希望用户针对相同类型的运动发出以下请求：

  • Hey Google, start a run on Example App.
  • Hey Google, start a jog on Example App.

在内嵌目录快捷方式中，您将 shortcutId 设为应用所需的运动标识符 "CARDIO_RUN"，然后将“run”和“jog”指定为与 shortcutId 关联的同义词。等到用户通过上述查询触发与应用有关的 Action 时，Google 助理会在生成执行方式 intent 时将标识符 "CARDIO_RUN" 用作 BII 参数。

示例 app/res/shortcuts.xml 文件中的以下代码段便会实现这种情况：

<capability android:name="actions.intent.START_EXERCISE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
    </capability-binding>
</shortcut>

在上述示例中，内嵌目录 shortcut 在 <capability-binding> 元素中声明了 <parameter-binding> 标记，并将其绑定到 <capability> 中定义的 exercise.name BII 参数。

字符串数组资源 @array/run_names 用于在 res/values/arrays.xml 中指定 Google 助理将识别并映射到 "CARDIO_RUN" 项目 ID 的同义词列表：

<!-- Synonym values for "CARDIO_RUN" inline inventory -->
<resources>
  <string-array name="run_names">
    <item>Run</item>
    <item>Jog</item>
    <item>Sprint</item>
  </string-array>
</resources>

如果为该 capability 提供了 <url-template>，系统便会将匹配值的 shortcutId 插入到所生成网址中该参数的对应占位符处。示例 app/res/shortcuts.xml 文件中的以下代码便会实现这种情况：

<capability android:name="actions.intent.START_EXERCISE">
  <intent>
    <url-template android:value="myapp://workout{?exercise}" />
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
</shortcut>

在上述示例中，Google 助理会生成执行方式深层链接 myapp://workout?exercise=CARDIO_RUN。

采用快捷方式 intent 的执行方式

默认情况下，快捷方式会为所绑定 capability 的 intent 提供匹配内嵌目录值的 shortcutId，如快捷方式的 <capability-binding> 标记中所声明的那样。此外，您还可以向 capability 添加 <shortcut-fulfillment> 标记，以指定将在快捷方式自身中定义的 intent 用于执行方式。

示例 app/res/shortcuts.xml 文件中的以下代码便会实现快捷方式执行方式：

<capability android:name="actions.intent.START_EXERCISE">
  <shortcut-fulfillment>
    <parameter android:name="exercise.name"/>
  </shortcut-fulfillment>
</capability>

<shortcut android:shortcutId="CARDIO_RUN">
  <capability-binding android:key="actions.intent.START_EXERCISE">
    <parameter-binding
      android:key="exercise.name"
      android:value="@array/run_names" />
  </capability-binding>
  <intent android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ExerciseActivity">
    <parameter android:name="exercise.name" android:key="exercise" />
  </intent>
</shortcut>

在上述示例中，如果用户查询与 exercise.name 参数的内嵌目录值相符，<shortcut-fulfillment> 标记就会指定将绑定快捷方式的 intent 用于执行方式。

适用于 Open app feature BII 的内嵌目录

虽然内嵌目录通常是支持它的 BII 的一项可选 capability，但对于某些 BII（例如 OPEN_APP_FEATURE）而言，必须具有内嵌目录。这种常用 BII 可让用户使用 Google 助理深层链接到特定的应用功能。在将用户深层链接到应用之前，该 Open app feature BII 需要使用应用功能名称的内嵌目录来验证用户请求的功能是否存在。

示例 app/res/shortcuts.xml 文件中的以下代码便会使用一个代表应用订单状态功能的快捷方式来实现此 BII：

<capability android:name="actions.intent.OPEN_APP_FEATURE">
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="feature"
       android:key="featureParam" />
  </intent>
  <!-- Required fallback fulfillment to handle when parameters are missing from user query. -->
  <intent
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MyClass">
    <parameter
       android:name="HOME_SCREEN"
       android:key="featureParam" />
  </intent>
</capability>

<!-- Inline inventory for OPEN_APP_FEATURE. -->

<shortcut android:shortcutId="ORDER_STATUS">
  <capability-binding android:key="actions.intent.OPEN_APP_FEATURE">
    <parameter-binding
      android:key="feature"
      android:value="@array/order_status_names" />
    </capability-binding>
</shortcut>

res/values/arrays.xml 中的字符串数组资源 @array/order_status_names 用于指定此功能的同义词列表：

<resources>
  <string-array name="order_status_names">
    <item>Order status</item>
    <item>Orders</item>
    <item>Order history</item>
  </string-array>
</resources>

有了上述 capability 后，Google 助理就可以针对同一功能执行不同的短语指令：

  • "Hey Google, show my order status on Example App."
  • "Hey Google, show my orders on Example App."
  • "Hey Google, show my order history on Example App."

测试内嵌目录

您可以检查 Google 助理在执行与应用有关的 Action 的相关 capability 时向您应用提供的 BII 参数值，以测试自己的目录。内嵌目录的运作方式为：将用户为与目录绑定的 BII 参数提供的值替换为匹配内嵌目录快捷方式的 shortcutId。

例如，START_EXERCISE BII capability 可能会使用内嵌目录将用户提供的 BII 参数“run”转换为对应的运动 ID（即 "CARDIO_RUN"）。

您可以利用 Google 助理插件，在测试设备上预览 Google 助理中内嵌目录的与应用有关的 Action。如需使用该插件测试您的目录，请按照以下步骤操作：

  1. 使用与您的内嵌目录关联的同义词值来配置 BII capability 中与目录绑定的参数。
  2. 从插件中触发 BII，并在测试设备上调用该 BII。
  3. 检查在执行与应用有关的 Action 期间，Google 助理向您的应用提供的参数值。