前台应用调用

通过与应用有关的 Action,用户可在对 Google 助理说出“Hey Google, order me a ride on Example App”这样的指令后,直接跳转到应用中的特定目标页面。借助前台应用调用,您可以进一步提升用户在打开您的应用后获享的体验。

当特定 activity 位于设备前台时,可以通过前台应用调用来匹配内置 intent (BII),无需提及应用名称。

举例来说,某位用户在前台运行拼车应用,然后对 Google 助理说出或输入“Order me a ride to Mountain View”。该应用会根据此输入内容,将目的地字段设为 Mountain View。然后,当用户说出或输入“Order me a ride from SFO”后,该应用可在保持状态不变的同时设置上车点。

限制

前台应用调用仅适用于以下 BII:

如需获取与特定 BII 前台应用调用相关的语言区域支持和查询示例,请参阅内置 intent 参考文档

支持前台应用调用

如需添加对前台应用调用的支持,必须根据所需的前台 activity 添加执行方式行为。当该 activity 位于前台并调用与应用有关的 Action 时,Google 助理会将带有额外标志的深层链接 intent 传递给这个 activity,以便应用可以更新自己的状态。

如需为 BII 实现前台应用调用,请执行以下操作:

  1. shortcuts.xml 文件中,将 <intent> 标记添加到您希望支持前台应用调用的 BII <capability>
  2. <intent> 标记内,添加 <extra> 标记。
  3. <extra> 标记中,将 android:key 设为 "requiredForegroundActivity",并将 android:value 设为需要位于前台的 activity。请按以下方式指定不带任何类缩写的 activity:使用应用软件包名称后跟正斜杠 (/) 和 activity 名称:APP_PACKAGE_NAME/ACTIVITY_NAME
  4. 在您为 "requiredForegroundActivity" 指定的前台 activity 中,实现 onNewIntent() 方法来处理设有 SINGLE_TOP 标志集的深层链接 intent。当指定的 activity 位于前台时,Google 助理会将设有此标志的深层链接 intent 作为执行方式传递。
  5. 将对 onNewIntent() 的调用视为对前台 activity 的更新,并使用从深层链接中提取的参数管理该 activity 中的状态。

如果应用使用路由器 activity 以使所有外部深层链接触发单个关守路由器 activity,请参阅处理路由器 activity

示例

来自示例 shortcuts.xml 文件的以下代码段显示了如何添加 requiredForegroundActivity 属性:

  <capability name="actions.intent.CREATE_TAXI_RESERVATION">
      <!-- Trigger with foreground app invocation if MainActivity is in the foreground. -->
      <intent
          android:targetClass="com.example.app.MainActivity"
          android:targetPackage="com.example.app">
          <parameter
              android:name="taxiReservation.dropoffLocation.name"
              android:key="dropoff" />
          <extra
              android:key="requiredForegroundActivity"
              android:value="com.example.app/com.example.app.MainActivity" />
      </intent>
      <!-- This won't trigger if MainActivity is in the foreground. -->
      <intent
          android:targetClass="com.example.app.MainActivity"
          android:targetPackage="com.example.app">
          <parameter
              android:name="taxiReservation.dropoffLocation.name"
              android:key="dropoff" />
      </intent>
  </capability>

用户权限

在设备设置中,用户必须启用“使用屏幕上的文字内容”,才能让前台应用调用正常运行。

若要使前台应用调用对用户可用,就必须启用使用屏幕上的文字内容设备设置。此设置的位置和确切名称可能因原始设备制造商 (OEM) 或设备制造商而异。例如,在用户的设备上,该设备设置可能会改称为使用屏幕上的内容

如需在 Pixel 手机上访问此 Android 设置,请先依次前往设置 > 应用和通知 > 默认应用 > 辅助应用;然后,在助手和语音输入屏幕上,启用使用屏幕上的文字内容

测试调用

如需试用前台应用调用,请按以下步骤操作:

  1. 按照用户权限部分中的说明,启用使用屏幕上的文字内容设备设置。
  2. 打开相关应用,前往列为所需前台 activity 的 activity。
  3. 按住主屏幕按钮,打开 Google 助理作为当前应用的叠加层。请提供与已实现的 BII 对应的查询,无需提供应用名称本身。如果顺利的话,应用会根据查询自行更新,同时保持状态,不会重启 activity。

处理路由器 activity

某些应用使用单个关守路由器 activity 来处理所有外部深层链接。然后,路由器 activity 会启动对应的业务逻辑 activity(经过检查和验证)并将其返回到前台。

触发深层链接可能会导致路由器 activity 添加到前台 activity 上方的任务堆栈顶部。对于使用路由器 activity 的应用,您必须确保路由器 activity 会将 Google 助理发送的 intent 传递给当前的前台 activity 实例。达到此要求的方式取决于路由器 activity 的启动位置。

如果路由器会在与业务逻辑 activity 相同的任务堆栈中启动,则使用 SINGLE_TOPCLEAR_TOPNEW_TASK 的按位“或”来转发 intent:

Kotlin

Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_NEW_TASK

Java

Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK

如果路由器会在与业务逻辑 activity 的单独任务堆栈中启动,则改为将设有 SINGLE_TOP 标志的 intent 转发到业务逻辑 activity。