前台应用调用

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

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

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

限制

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

• actions.intent.CREATE_MONEY_TRANSFER
• actions.intent.CREATE_TAXI_RESERVATION
• actions.intent.OPEN_APP_FEATURE
• actions.intent.ORDER_MENU_ITEM
• actions.intent.PAUSE_EXERCISE
• actions.intent.RECORD_EXERCISE
• actions.intent.RECORD_FOOD_OBSERVATION
• actions.intent.RESUME_EXERCISE
• actions.intent.START_EXERCISE
• actions.intent.STOP_EXERCISE

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

支持前台应用调用

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

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

1. 在 shortcuts.xml 文件中，向您希望支持前台应用调用的 BII <capability> 添加一个 <intent> 标记。
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_TOP、CLEAR_TOP 和 NEW_TASK 的按位“或”来转发 intent：

Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_NEW_TASK

Intent.FLAG_ACTIVITY_SINGLE_TOP | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK