确定要实现的应用内功能和对应的内置 intent (BII) 后,需要在 shortcuts.xml
资源文件中定义一个 capability
元素来声明您的功能支持的 BII。通过将 BII 声明为 capability
,可在应用中注册对该语义 intent 的支持,并使用 Google 助理实现该 intent 的语音查询执行方式。
Google 助理使用自然语言处理技术从用户查询中提取参数。内置 Intent 参考文档中列出了每个 BII 能从关联的用户查询中提取的字段。例如,如果用户通过说出“Hey Google,问问 ExampleApp 我上周五中午吃了什么”调用您应用中的 [actions.intent.GET_FOOD_OBSERVATION
][] capability,Google 助理就会从用户请求中提取以下 BII 参数:
foodObservation.forMeal
= "https://schema.googleapis.com/MealTypeLunch"foodObservation.startTime
=“2024-09-06T00:00:00”foodObservation.endTime
= "2024-09-06T23:59:59"
Google 助理会将这些 BII 参数传递给 capability
中定义的执行方式 intent
。可以在一个 capability 中定义一个或多个 intent
元素来适应用户调用 BII 的不同方式。例如,可以定义一个需要用到上述示例中的两个 BII 参数的执行方式 intent
。然后,可以再定义一个 intent,该 intent 只需要单个 BII 参数 foodObservation.forMeal
,当用户提出更简单的请求(例如“Hey Google,问问 ExampleApp 我今天中午吃了什么”)时,它会报告特定日期的所有餐食。
概览
可以按以下方式配置与应用有关的 Action:在应用项目的 res/xml
目录中放置一个 shortcuts.xml
文件,然后在应用清单中创建对该 shortcuts.xml
的引用。可以按以下步骤在应用清单中添加对 shortcuts.xml
的引用:
在应用的清单文件 (
AndroidManifest.xml
) 中,找到 intent 过滤器设为android.intent.action.MAIN
操作和android.intent.category.LAUNCHER
类别的 activity。使用同时具有针对
MAIN
和LAUNCHER
的 intent 过滤器的Activity
中的<meta-data>
标记,在AndroidManifest.xml
中添加对shortcuts.xml
的引用,如下所示:<meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts" />
上述示例为 APK 中的 xml/shortcuts.xml
文件声明了一个 XML 资源。如需详细了解如何配置快捷方式,请参阅 Android 开发者文档中的创建静态快捷方式。
Android 项目需要使用 Jetpack 库 androidx.core:core:1.6.0
(或更高版本)来避免在 shortcuts.xml
中定义与应用有关的 Action 的 capability 时出现编译错误。如需了解详情,请参阅 Android Jetpack 使用入门。
静态快捷方式
定义 capability
时,可以在 shortcuts.xml
中声明静态 shortcut
元素来扩展该 capability 的功能。当您将版本上传到 Google Play 管理中心时,Google 助理会提取静态快捷方式。由于静态快捷方式只能通过创建新版本来创建和更新,因此最适合用来突出显示应用中的常见活动和内容。
可以通过静态快捷方式启用以下与应用有关的 Action 功能:
capability 快捷方式。这类快捷方式可用于启动包含预定义
intent
参数值的capability
实例。例如,可以声明一个应用快捷方式“Start a run”,该快捷方式会在您的健身应用中调用START_EXERCISE
BII capability。这些快捷方式包含
intent
、shortLabel
和longLabel
属性,使其可以在主动 Surface(例如 Google 助理,或长按 Android 启动器上的应用图标时)中作为条状标签建议和执行。action 快捷方式也可用作 entity 快捷方式(详见下文),只需使用<capability-binding>
标记将其与capability
关联即可。entity 快捷方式。entity 快捷方式为
capability
的语音查询执行方式提供受支持的参数值列表。例如,一个带有一系列运动类型(“hike”“run”等)的 entity 快捷方式绑定到START_EXERCISE
capability 的exercise.name
BII 参数。如果用户话语与某个 entity 匹配,系统会将shortcutId
ID 而不是原始用户查询值传递给 intent。Entity
快捷方式不会定义intent
、shortLabel
或longLabel
属性,因此不会在主动 Surface 上建议。如需了解详情,请参阅与应用有关的 Action 的内嵌目录。
capability 架构
下表列出了 shortcuts.xml
中 capability
元素的与应用有关的 Action 的架构。添加标记时,需要提供除标记为“可选”的属性之外的所有属性。
Shortcuts.xml 标记 | 包含于 | 属性 |
---|---|---|
<capability> |
<shortcuts> |
|
<intent> |
<capability> |
|
<url-template> |
<intent> |
|
<extra> |
<intent> |
仅适用于前台应用调用 |
<parameter> |
<intent> |
|
<shortcut-fulfillment> |
<capability> |
仅适用于内嵌目录 |
<parameter> |
<shortcut-fulfillment> |
android:name |
<slice> |
<capability> |
仅适用于 Android Slice |
capability 架构说明
本部分介绍 capability
架构元素。
<capability>
capability
,用于定义应用支持的与应用有关的 Action intent。shortcuts.xml
文件中的每个 <capability>
元素都必须至少提供一个 <intent>
才能处理相应操作的执行方式。
属性:
android:name
:内置 intent 操作 ID(例如 [actions.intent.GET_FOOD_OBSERVATION
][])。如需查看受支持的内置 intent 的列表,请参阅内置 intent 参考文档。app:queryPatterns
:用户预期会对此 intent 执行的查询的字符串数组资源。此属性仅适用于自定义 intent,因为 BII 已包含用户表达尝试执行的任务或尝试搜索的信息的常见方式模型。
<intent>
Android intent
元素,用于定义应如何使用应用内功能来执行用户查询。开发者可以在 capability
中提供多个 <intent>
标记。Google 助理会尝试使用 capability
中的第一个 <intent>
(已为其提供所有必需参数)来执行用户查询。
属性:
android:action
:intent 的Action
类型。默认为ACTION_VIEW
。android:targetClass
:目标 activity 类,例如:"com.example.exercise.ExerciseActivity"
android:targetPackage
:包含目标 activity 类的软件包,例如:"com.example.exercise
android:data
:如果intent
中声明了<url-template>
标记,则此字段会被该标记重写。
<url-template>
用于构造要在设备上打开的深层链接 URI 的模板。如果为模板提供了所有必需参数,则可以使用内置 intent 参数展开该模板。如需查看 HTTP 网址模板示例,请参阅关于网址模板的维基百科文章。模板格式遵循 RFC 6570 URI 模板规范。
以下是网址模板值的一些示例:
模板 | 值 | 展开值 |
---|---|---|
https://example.com/test{?foo,bar} |
"foo": "123"
|
https://example.com/test?foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{&foo,bar} |
"foo": "123"
|
https://example.com/test?utm_campaign=appactions&foo=123&bar=456 |
https://example.com/test?utm_campaign=appactions{#foo} |
"foo": "123" |
https://example.com/test?utm_campaign=appactions#foo=123 |
myapp://example/{foo} |
"foo": "123" |
myapp://example/123 |
如需详细了解如何配置网址模板,请参阅执行方式中的网址模板。
<extra>
定义 intent
的 extra 数据。对于与应用有关的 Action,此字段仅用于为 capability
启用 [前台应用调用]。
<parameter>
将 BII 参数映射到 intent 参数值。如需了解详情,请参阅参数数据和匹配。
属性:
android:name
:要与此intent
参数关联的 BII 参数的名称。该名称应为该 BII 参数的叶级字段(例如foodObservation.aboutFood.name
)。android:key
:BII 参数值的开发者定义键。例如,可以为message.recipient.name
BII 参数定义contact_name
。android:mimeType
:参数的 mimeType,例如text/*
。只有自定义 intent 的参数需要此字段。android:required
:声明用户查询是否需要包含此参数,以便此 intent 用于执行方式。如果该参数不可用,Google 助理会尝试使用为capability
定义的下一个intent
来执行用户查询。
<shortcut-fulfillment>
指定在内嵌目录快捷方式中为指定参数定义的 intent
用于执行方式。如需了解详情,请参阅采用快捷方式 intent 的执行方式。
<parameter>(适用于 <shortcut-fulfillment>
)
一个可选属性,用于将单个 BII 参数映射到内嵌目录快捷方式执行方式。如需了解详情,请参阅采用快捷方式 intent 的执行方式。
属性:
android:name
:要与内嵌目录快捷方式执行方式关联的 BII 参数的名称。该名称应为该 BII 参数的叶级字段(例如menuItem.name
)。
<slice>
使 Google 助理能够将匹配此 capability
的查询的结果作为 Android Slice 嵌入。如需了解详情,请参阅将与应用有关的 Action 与 Android Slice 集成。
快捷方式架构
下表列出了用于实现与应用有关的 Action 功能的 shortcut
元素的属性。添加标记时,需要提供除标记为“可选”的属性之外的所有属性。
Shortcuts.xml 标记 | 包含于 | 属性 |
---|---|---|
<shortcut> |
<shortcuts> |
|
<intent> |
<shortcut> |
|
<capability-binding> |
|
|
<parameter-binding> |
<capability-binding> |
|
<extra> |
<shortcut> |
仅适用于枚举参数匹配。 |
快捷方式架构说明
本部分介绍 shortcut
架构元素。
<shortcut>
在 shortcuts.xml
中定义的 Android <shortcut>
,其中包含与与应用有关的 Action 相关的某些属性。shortcutShortLabel
和 shortcutLongLabel
字段的字符串值通过 APK 的字符串资源进行引用。
属性:
android:shortcutId
:此快捷方式的标识符。android:shortcutShortLabel
:表示短快捷方式的字符串资源。例如,"@string/callDavidShort"
表示值“给 David 打电话”。android:shortcutLongLabel
:表示长快捷方式的字符串资源。例如,"@string/callDavidLong"
表示值“向 David 发起语音通话”。
<intent>
与此快捷方式关联的 Android intent。当用户通过语音或触摸启动此快捷方式时,系统就会执行此 intent
。
shortcut
intent 属性与 capability
intent
属性相同。
<capability-binding>
将 shortcut
关联到与应用有关的 Actioncapability
。将此元素添加到 shortcut
可使其可用于使用 Assistant
执行语音指令。
属性:
android:key
:此shortcut
绑定到的capability
的android:name
属性,例如actions.intent.START_EXERCISE
。
<parameter-binding>
将 shortcut
关联到与应用有关的 Action capability
的单个参数的可选属性。如果为 shortcut
定义了 parameter-binding
,则可以使用该快捷方式向 BII 参数提供内嵌目录 entity。如需了解详情,请参阅与应用有关的 Action 的内嵌目录。
属性:
android:key
:要将此快捷方式关联到的capability
BII 参数的名称,例如exercise.name
。android:value
:entity
值。这可以是单个entity
或资源列表。
<extra>
快捷方式的 extra
bundle 数据。sameAs 是和与应用有关的 Action shortcut
元素相关的唯一数据。sameAs 网址指向明确标识该 entity 的参考网页。当且仅当 intent 参数类型是 schema.org/Enumeration 的子类型时,才用于指定枚举值。对于类型为 schema.org/Enumeration
的子类型的参数字段(例如 MealTypeBreakfast
),必需提供该属性。
属性:
android:key
:与应用有关的 Action 支持的值为:sameAs
android:value
:sameAs
网址值
如需了解详情,请参阅匹配枚举参数值。
intent 执行方式选项
可以在 <capability>
中定义 intent
元素,以声明 Google 助理如何响应或执行与该 capability 匹配的用户语音指令。可以通过多种方式配置 intent
在应用中启动执行方式目标页面的方式,具体取决于应用的导航结构。
可以使用以下执行方式选项:
显式 intent:通过为
intent
定义targetClass
和targetPackage
属性来启动特定的应用组件。这是与应用有关的 Action 的推荐执行方式。深层链接:通过在
intent
元素中定义<url-template>
标记,使用 Android 深层链接启动应用目标页面。如果您的应用导航已经依赖于深层链接,则此方法会很有用。intent 数据:您可以在
intent
android:data
属性中提供执行方式 URI。如果还在intent
中定义了<url-template>
标记,则该字段会被该标记的数据重写。
参数数据和匹配
默认情况下,Google 助理会将从用户查询中提取的 BII 参数作为 capability
中定义的 Android intent
的 extra
数据发送到您的应用。
或者,您也可以在 capability
中声明 <url-template>
标记(包含动态参数的占位符)。此模板使用应用链接网址、自定义架构或基于 intent 的网址映射到您的其中一个 Android activity。
使用 intent extra
以下示例展示了为 capability
执行方式定义的显式 intent:
<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>
根据以上示例,对于诸如“Ok Google,从 ExampleApp 订一杯拿铁”之类的用户查询,应用会收到调用以下组件的 intent
:targetPackage
、targetClass
。相应组件通过 key = "exercise"
、value = "Running"
接收 extra。
为 Android 深层链接使用网址模板
如果您的应用已经能够处理链接应用的网址,则可以使用动态参数在 intent
中定义 <url-template>
来为执行方式生成 Android 深层链接。以下示例定义了 <url-template>
:
<capability android:name="actions.intent.START_EXERCISE">
<intent>
<url-template android:value="myapp://start{?exercise}" />
<parameter android:name="exercise.name" android:key="exercise" />
</intent>
</capability>
根据上述示例,对于诸如“Hey Google,从 ExampleApp 订一杯拿铁”之类的用户询问,应用会收到生成的网址:“myapp://start?exercise=Running”。
如需将 BII 参数映射到网址中的某个位置,请使用 <parameter>
标记的 android:name
属性。此属性对应于网址模板中您想使用用户信息替换的 android:key
值。android:key
值必须存在于您的 <url-template>
中并用大括号 ({}
) 括起来。
匹配枚举参数值
某些 BII 参数会向您的执行方式 intent 提供枚举值,例如 RECORD_FOOD_OBSERVATION
BII 的支持的文本值。对于这些参数,Google 助理会将用户的查询(“Breakfast”)与 sameAs
值与枚举架构网址 (https://schema.googleapis.com/MealTypeBreakfast
) 匹配的 entity 进行匹配。如需关联受支持的 entity
的枚举值,请在 shortcut
中声明 sameAs
关联。以下示例展示了内嵌 entity 快捷方式的 sameAs
关联:
<shortcut android:shortcutId="meal_breakfast" >
<capability-binding android:key="actions.intent.RECORD_FOOD_OBSERVATION">
<parameter-binding android:key="foodObservation.forMeal" />
</capability-binding>
<extra
android:key="sameAs"
android:value="http://schema.googleapis.com/MealTypeBreakfast" />
</shortcut>
<capability android:name="actions.intent.RECORD_FOOD_OBSERVATION">
<intent targetPackage="com.example.app" targetClass="com.example.app.Class">
<parameter android:name="foodObservation.forMeal" android:key="for_meal" />
</intent>
</capability>
在以上示例中,如果 RECORD_FOOD_OBSERVATION
capability 触发了对“breakfast”餐点类型的匹配,则执行方式 intent
会发送以下 extra:
key = "for_meal"
value = "meal_breakfast"
功能
shortcuts.xml
中提供了以下与应用有关的 Action 功能。
与应用有关的 Action 的内嵌目录
对于某些 BII 参数,可以使用快捷方式将 entity 提取引导到 shortcuts.xml
中指定的一组受支持的 entity(称为内嵌目录)。如需了解详情,请参阅内嵌目录。
自定义 intent
您可以在 shortcuts.xml
中声明自定义 intent,以在您的应用中用语音实现与可用 BII 不匹配的功能。虽然在功能上与 BII 定义类似,但自定义 intent 需要在 shortcuts.xml
中添加两个额外的属性:
app:queryPatterns
:为自定义 intent 声明不同查询格式的数组资源。android:mimeType
:自定义 intent 的参数类型。对于 BII 而言,参数类型是已知的,因此不需要此字段。对于自定义 intent 参数,必须声明支持的语义类型。
如需了解详情,请参阅自定义 intent。