与应用有关的 Action 的内置 intent

通过内置 intent (BII),应用可以向 Google 说明其能够执行的各种 capability。您只需在 shortcuts.xml 文件中声明 capability 并将 intent 形参映射到对应执行方式,Google 助理就能让相关应用启动并进入特定界面来响应查询,以便用户完成任务。

内置 intent 根据应用类别进行分组。每个类别代表用户经常想在相关应用中执行的一组常见任务。如需查看可用 BII 及其形参、可用于测试的示例查询的完整列表,请参阅内置 intent 参考文档

许多 BII 都包含特定的部署要求和建议。这些要求和建议有助于您的应用尽可能向用户提供最佳的体验。

图 1. 通过向 Google 助理发出语音查询来调用 START_EXERCISE BII。
图 2. 让应用启动并进入特定界面,以开始 START_EXERCISE 任务。
图 3. 显示一个 widget 来响应查询。

实现 BII 和处理 intent 形参

对于与应用有关的 Action,您可以在 shortcuts.xml 文件中声明 capability 并处理 BII 形参。如要实现 BII 并处理其形参,请按照以下步骤操作:

  1. 使用选定的 BII 声明 capability
  2. 为要添加的各个 BII 字段添加嵌套的 parameter 元素。
    1. 如果您使用 targetClasstargetPackage,请使用您选择的名称将其映射到 Android intent extras
    2. 如果您使用深层链接网址,请在网址模板的查询字符串中使用具名形参。

如需处理 BII 形参,请将 BII 形参映射到 capability 中显式 Android intent 的对应形参。 然后,您便可在应用中使用该形参的值。您的应用无需处理 BII 形参。不过,您的应用应尝试处理内置 intent 参考文档中标记为“推荐”的数据字段。

您可以定义多个 intent 执行方式,让每个 intent 执行方式都有自己的一组推荐形参。Google 会根据从用户查询中识别出的 capability 形参以及 intent 中已声明的这类形参来选择合适的执行方式。

举例来说,actions.intent.START_EXERCISE intent 会建议应用处理 exercise.name BII 形参,但是您可以在应用中实现不带形参的 BII。 如果您想处理不含具体运动名称的用户查询(例如“Ask Example App to start tracking exercise”),可能就需要这样做。

当用户的查询不含任何必需形参时,您可以使用以下代码段回退到没有必需形参的执行方式:

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">

    <capability android:name="actions.intent.START_EXERCISE">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetClass="com.example.myapplication.Activity1"
            android:targetPackage="com.example.myapplication">
            <parameter
                android:name="exercise.name"
                android:key="exerciseType"
                android:required="true"
                />
        </intent>
        <intent
            android:action="android.intent.action.VIEW"
            android:targetClass="com.example.myapplication.Activity2">
        </intent>
    </capability>
</shortcuts>

在向应用返回形参值时,Google 助理会尽力提供最相关的信息。例如,通过 Example Restaurant 的移动应用订购披萨的用户查询并不总是会包含位置信息。为了更好地为用户提供服务,Google 助理可能会选择为该应用提供最近的 Example Restaurant 的纬度和经度值。

此外还有一项要求是,应用不得在未事先与用户确认的情况下,直接执行会修改用户实际状态的操作(例如,转账、下单或发送消息)。

消除歧义

通过 <url-parameter> 或 intent extra 传递给应用的实参可能无法唯一标识您想要向用户显示的项目。在这种情况下,请使用实参值用作搜索实参,并让用户前往应用的搜索页。用户可以消除歧义,并选择正确的项目。

举例来说,如果用户向 BII ORDER_MENU_ITEM 发出的查询是“Order from Example Restaurant”,您可以向该用户显示名称与 "Example Restaurant" 一词相符的餐厅列表。

语言和语言区域支持

内置 intent 参考文档中列出了每个与应用有关的 Action BII 可用于开发和测试的语言区域。对于开发者测试以及来自 Google 助理的用户触发行为,某些 BII 会提供不同的语言区域支持。