自定义 intent

每个应用都是不同的,且并非所有应用功能都与可用的与应用有关的 Action 内置 intent 匹配。对于没有对应内置 intent (BII) 的应用功能,您可以改用自定义 intent 来通过与应用有关的 Action 扩展应用。

与 BII 一样,自定义 intent 遵循 shortcuts.xml 架构,并充当 Google 助理和您定义的执行方式之间的连接点。自定义 intent 也有 intent 参数,您可以将其映射到相应执行方式中的参数。

与 BII 不同,自定义 intent 需要查询格式来描述用户可能会说出的示例查询。此方法与内置 intent 不同,内置 intent 会对用户表达相应 intent 的常用方式进行建模。

限制

自定义 intent 具有以下限制:

  • 自定义 intent 的名称不得以 actions.intent 开头。
  • 一个应用的各个自定义 intent 的名称必须不同。
  • Google 助理只能提取特定数据类型的参数。如需查看受支持类型的列表,请参阅支持的类型
  • 每个查询最多支持两个文本参数。此限制不适用于其他数据类型。
  • 自定义 intent 仅支持 en-US 语言区域(设备语言设置和 Google 助理语言设置都必须匹配)。

支持的类型

自定义 intent 支持提取以下 schema.org 类型的参数:

  • https://schema.org/Text
  • https://schema.org/Date
  • https://schema.org/Time
  • https://schema.org/Number

使用自定义 intent 定义与应用有关的 Action

与其他使用内置 intent 的与应用有关的 Action 一样,您可以在 shortcuts.xml<capability> 元素中定义自定义 intent。

capability 在 <shortcuts> 根元素中定义。定义 <shortcuts> 元素时,必须添加要访问的属性的命名空间。

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

android:name 属性中提供自定义 intent 的名称,并在 queryPatterns 属性中引用查询格式资源文件。

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

在为自定义 intent 命名时,建议您使用前缀 custom.actions.intent 来区分自定义 intent 与内置 intent 和 Android intent(它们的运作方式不同)。自定义 intent 的名称不得以 actions.intent 开头,因为该命名空间是为内置 intent 预留的。

对于每个参数,请提供最能准确描述参数含义的受支持的 schema.org 类型。例如,可以使用 https://schema.org/Date 来描述希望接收的日期:

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

shortcuts.xml 中的快捷方式定义对自定义 intent 使用与内置 intent 相同的格式。以下代码描述了一个使用引用的查询格式触发 SCHEDULE_APPOINTMENT 自定义 intent 的与应用有关的 Action,以及 apptType 参数的一组已定义值:DRIVERS_LICENSEVEHICLE_REGISTRATION

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
      <url-template android:value="https://example.com/appt{?apptType,date,time}" />
      <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
      <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
      <!-- The following parameter has no type because the shortcuts are bound to it -->
      <parameter android:name="apptType" android:key="apptType" />
    </intent>
    ...

shortcuts.xml 中的快捷方式定义对自定义 intent 使用与内置 intent 相同的格式。以下代码描述了一个使用引用的查询格式触发 SCHEDULE_APPOINTMENT 自定义 intent 的与应用有关的 Action,以及 apptType 参数的一组已定义值:DRIVERS_LICENSEVEHICLE_REGISTRATION

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

您可以使用内嵌目录配置自定义 intent 参数,用于将 entity 提取引导到 shortcuts.xml 中指定的一组受支持 entity。

查询格式

您使用的每个自定义 intent 都需要具有用户预期会对该 intent 执行的一组查询。这种方法与内置 intent 不同,内置 intent 已经根据用户表达他们想要执行的任务或查找的信息的常用方式对查询进行建模。

在 Android 资源文件(通常是 /res/values/strings.xml)中,将查询格式指定为字符串数组中的项。调用与应用有关的 Action 时,Google 助理在为执行方式匹配用户 intent 的过程中,会针对您的查询格式检查用户查询。您提供的每个查询格式都代表一个您认为对相应自定义 intent 有效的短语。

在为自定义 intent 提供查询格式时,应要求每种格式遵循显式调用,例如“open ExampleApp and”或“start ExampleApp and”。例如,请考虑以下用户查询:

  • “Hey Google, open ExampleGameApp and start making a cake.”
  • “Hey Google, open ExampleGameApp and start making an apple pie.”
  • “Hey Google, start ExampleGameApp and craft 5 cake items.”
  • “Hey Google, use ExampleGameApp to produce cake 5 times.”

如需匹配用户查询,请提供包含调用短语之后的查询部分的查询格式。对于要从查询中提取的信息(如用户提供的文本或数字),可以通过查询格式中的占位符为相应的 intent 参数分配值。

如需在查询格式中引用参数,请在格式的参数名称中添加 $。例如,若要为参数创建占位值(例如 <parameter name="date1" ... [actions.xml] 或 <parameter android:name="date1" ... [shortcuts.xml]),则应使用 $date1

以下代码描述了与上述用户查询匹配的查询格式,并提取了项名称值和要创建的项数:

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

查询格式支持条件。例如,“set (an)? appointment $date $time”。在这种情况下,“set appointment today at noon”和“set an appointment today at noon”都是有效的查询。