网站目录

借助与应用有关的 Action,用户可以通过说出“Hey Google, show me the menu for Three Dot Cafe on ExampleApp”之类的语音指令,直接跳转到应用中的相关内容。这种功能叫做深层链接,可让用户更轻松地使用应用处理事务。

为了执行此类请求,Google 助理会生成指向应用中的匹配内容的深层链接。如果您使用内容或商品信息积极维护自己的网站,并且围绕此公开提供的 Web 内容组织应用内深层链接,就可以将 Google 助理配置为使用网站目录从您的网站为操作执行方式提取网址。

网站目录是应用支持的内容网址的网站位置。当用户调用您的与应用有关的 Action 时,Google 助理会将用户查询(例如“Three Dot Cafe”)与您在 shortcuts.xml 中为您的 Android 应用指定的网站的 Google 搜索索引中的相应网址进行匹配。

优势

如果应用含有供用户在应用中查看或订购的庞大内容列表并且这些列表会定期更新,则网站目录可使其具备以下优势:

  • 内嵌目录数据会将内容列表存储在应用中不同,网站目录数据会驻留在网站上。允许 Google 助理访问网站数据可以避免内嵌目录数据过时的风险,内嵌目录数据只能通过发布应用的新版本进行更新。

  • 内嵌目录下的内容数量不能超过 1,000 件。相比之下,网站目录没有内容数量限制,可以根据您的需求进行扩展。

  • 网站目录允许执行方式仅处理从网站检索到的可预测内容网址,从而简化应用逻辑。相比之下,如果未配置网站目录,Google 助理会通过将 intent 参数映射到网址模板中的变量来为执行方式生成深层链接。然后,执行方式需要通过分析此动态生成的网址来确定用户是否请求了应用中受支持的 entity。

运作方式

在执行与应用有关的 Action 期间,Google 助理会通过您在 shortcuts.xml 中定义的内置 intent (BII) 深层链接到应用内容。Google 助理会使用自然语言处理技术识别用户请求中的相关内容,并将其提取到 BII 参数中。然后,Google 助理会根据 shortcuts.xml. 中的执行方式配置,使用这些参数来生成深层链接。

可以通过以下三种方式为执行方式生成深层链接:

  • 参数映射:将 intent 参数映射到执行方式网址模板中的占位符。
  • 内嵌目录:将 intent 参数与应用中定义的受支持 entities 列表进行匹配。
  • 网站目录:将 intent 参数与在网站的 Google 搜索索引中找到的内容进行匹配。

网站目录是开发者定义的网站网址格式(如 https://www.exampleapp.com/restaurants/.*),表示应用支持的 entity 的 entity 集。

如果为网站目录配置了 BII 参数,Google 助理就会查询网站,以进行 entity 与用户查询的匹配。然后,Google 助理会将与配置的网址格式匹配的网址结果(例如 https://www.exampleapp.com/restaurants/three-dot-cafe)传递给执行方式。

图 1. 使用网站目录检索餐馆 entity 项的 Google 助理查询示例。

受支持的内置 intent

以下 BII 支持网站目录(针对特定 intent 参数):

  • [actions.intent.CREATE_REVIEW]
  • [actions.intent.GET_NEWS_ARTICLE]
  • [actions.intent.GET_REVIEW]
  • [actions.intent.GET_THING]
  • [actions.intent.ORDER_MENU_ITEM]
  • [actions.intent.GET_EXERCISE_PLAN]
  • [actions.intent.GET_DIGITAL_DOCUMENT]
  • [actions.intent.GET_ITEM_LIST]
  • [actions.intent.GET_OFFER]
  • [actions.intent.CREATE_OFFER]
  • [actions.intent.GET_PRODUCT]
  • [actions.intent.UPDATE_CART]
  • [actions.intent.CREATE_SOCIAL_MEDIA_CONNECTION]
  • [actions.intent.GET_IMAGE_OBJECT]
  • [actions.intent.GET_SOCIAL_MEDIA_POSTING]
  • [actions.intent.GET_SOCIAL_MEDIA_PROFILE]
  • [actions.intent.CREATE_TAXI_RESERVATION]
  • [actions.intent.CREATE_FLIGHT_RESERVATION]
  • [actions.intent.CREATE_LODGING_RESERVATION]
  • [actions.intent.GET_LOCAL_BUSINESS]
  • [actions.intent.GET_RESERVATION]
  • [actions.intent.UPDATE_RESERVATION]

添加网站目录

确定受支持的 BII 后,便可使用网站详细信息更新 shortcuts.xml,从而为网站目录启用该 BII。shortcuts.xml 文件是 Android 项目中的一项资源,您可以在其中定义映射到应用功能的 BII,以及每个 BII 应如何生成供应用执行的深层链接。如需详细了解 shortcuts.xml,请参阅创建 shortcuts.xml

若要将网站目录用于受支持的 BII,请按以下步骤操作:

  1. 在应用的 shortcuts.xml 文件中,添加一个 <capability> 标记,并将其 android:name 属性设为您正在通过网站目录处理的 BII 的名称,例如:actions.intent.ORDER_MENU_ITEM

  2. <capability> 标记中,添加一个 <intent> 标记,并将其 android:action 属性设为要由此 intent 激活的视图的名称。

  3. 在同一 <intent> 标记中,添加一个 <parameter> 标记,并将其 android:name 属性设为与您的网页所描述的 entity 最贴近的 BII 参数。例如,在为 ORDER_MENU_ITEM 提供网站目录时,应将菜单页面链接到 menuItem.name

  4. 在新的 <parameter> 标记中,添加一个 <data> 标记,并将其 android:pathPattern 属性设为要用于网站目录的路径的网址格式。

在您按照上述步骤配置 shortcuts.xml 后,Google 助理就能够从您在 android:pathPattern 属性中提供的网址格式的 Google 搜索索引中检索 Web 内容。然后,Google 助理会使用与您定义的网址路径格式匹配的结果为您的执行方式提供网址值。然后,您的应用会根据 Google 助理提供的网址数据将用户定向到应用中的特定位置。

例如,您的网站包含使用以 https://www.examplecafe.com/items/ 开头的网址路径的商品详情。如果您使用 pathPatternhttps://www.examplecafe.com/items/.*,Google 助理就会在网页搜索中使用此网址格式来查找执行方式网址,例如 https://www.examplecafe.com/items/item123

如果 Google 助理找到了匹配的网站目录网址,它会在执行方式 intent 的 <data> 字段中提供该网址,就像它是一个深层链接一样。使用 intent 的 getData() 方法将该网址作为 Uri 对象获取。接收该 intent 的应用 activity 负责解释该网址并激活相应的应用界面。

shortcuts.xml 示例

以下示例定义了一个 ORDER_MENU_ITEM BII,它会提供一个网站目录来为包含 menuItem.name BII 参数的请求返回网址结果:

<?xml version="1.0" encoding="utf-8"?>
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <capability android:name="actions.intent.ORDER_MENU_ITEM">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.OrderMenuItemActivity">
      <!-- Define URL match pattern in the pathPattern data field -->
      <parameter android:name="menuItem.name">
        <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
      </parameter>
    </intent>
  </capability>
</shortcuts>

在上述示例中,为 menuItem.name 指定了 pathPattern,以指示 Google 助理仅返回与以下网址格式匹配的网址:https://www.examplecafe.com/items/.*

如需查看更多支持网站目录的 BII 的 shortcuts.xml示例,请参阅参考文档

针对结果缺失情况处理回退方式

如果没有为执行方式返回网站目录结果,您的应用应实现回退逻辑来执行操作并尽可能提供最佳的用户体验。以下情况会导致结果缺失:

  • 缺少 intent 参数:用户查询中缺少预期的参数,或者 Google 助理无法理解用户请求中的参数。
  • 缺少网址结果:Google 助理在您网站上找不到与用户查询匹配的 entity。

可以通过为一个 capability 定义多个 <intent> 元素来处理缺失的参数值。如果 Google 助理无法满足第一个 intent,就会回退到下一个 intent,依此类推。

回退 intent 不应要求提供参数,而应使用更通用的深层链接来执行该 capability,例如显示用户查询的搜索结果。

在下面的示例 shortcuts.xml 中,一个 ORDER_MENU_ITEM BII 定义了两个执行方式:第一个需要来自 menuItem.name 参数的网址。第二个不需要任何参数,它会将用户引导至显示所有菜单项的页面。

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*"/>
    </parameter>
  </intent>
  <!-- Fallback intent with no required parameters -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.ViewMenuActivity">
    <url-template android:value="myapp://app.examplecafe.com/menu/all-items" />
  </intent>
</capability>

在未返回网站目录网址的情况下,用户查询的内容仍然可能被用于回退 intent,例如,用于显示搜索结果。

在以下示例 shortcuts.xml 中,定义了两个 intent 元素:

  1. 第一个需要来自 menuItem.name 参数的网站目录深层链接。
  2. 如果未返回深层链接,第二个 intent 就会使用来自 menuItem.name 的用户查询(如果存在)显示搜索结果。
<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter android:name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- Fallback intent displaying search results, using "menuItem.name" -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.SearchMenuActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

使用网站目录添加应用内搜索功能

您只需将网站目录与 actions.intent.GET\_THING BII 的实现相结合,便可让用户在您的应用中搜索 Web 内容。

该 BII 会使用默认的应用内搜索功能在应用中搜索内容或 entity,从而支持诸如“Hey Google, show me waterfall hikes on SampleApp”等查询。只需为 GET_THING BII 传递的 thing.name capability 参数配置网站目录,即可传递您网站上的匹配 entity 结果以供执行。

如需查看网站目录 shortcuts.xml 示例,请参阅 GET\_THING BII 参考文档

测试网站目录

当您为 BII 执行方式定义网站目录时,Google 助理会使用符合您为指定 BII 参数定义的 urlTemplate 格式的网页结果生成深层链接。如果找不到网站目录结果,Google 助理会生成与回退 intent 的 urlTemplate 格式匹配的网址。您可以通过验证 Google 助理提供的链接是否是与您的网站目录 urlTemplate 格式匹配的网址来测试您的网站目录实现。

在下面的示例 ORDER_MENU_ITEM BII 中,Google 助理会生成与 menuItem.name 参数中指定的 urlFilter 格式匹配的网站目录执行方式链接,例如:https://www.examplecafe.com/items/nuggets。如果第一个 intent 与网址格式不匹配,则第二个 intent 会采用 menuItem.name 的值并执行搜索。

<capability android:name="actions.intent.ORDER_MENU_ITEM">
  <!-- web inventory fulfillment -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.OrderMenuItemActivity">
    <parameter name="menuItem.name">
      <data android:pathPattern="https://www.examplecafe.com/items/.*" />
    </parameter>
  </intent>
  <!-- search intent -->
  <intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.example.myapp"
    android:targetClass="com.example.myapp.MenuSearchActivity">
    <parameter-mapping android:name="menuItem.name" android:key="food" />
    <url-template android:value="https://www.examplecafe.com/search?q={?food}" />
  </intent>
</capability>

与应用有关的 Action 测试工具可用于在实体设备或虚拟设备上测试网站目录。

如要使用该测试工具,请按以下步骤操作:

  1. 连接运行您的应用的测试设备。
  2. 在 Android Studio 中,依次点击 Tools > App Actions > App Actions Test Tool
  3. 点击 Create preview
  4. 在 Android Studio 中,在测试设备上运行您的应用。
  5. 使用测试设备上的 Google 助理应用测试与应用有关的 Action。例如,您可以这样说:“Hey Google, order nuggets on ExampleCafe”。
  6. 观察应用的行为,或使用 Android Studio 调试程序来验证是否取得了所需的操作结果。