前台应用调用

借助与应用有关的 Action，用户可以与 Google 助理对话，并直接跳转到特定 “Hey Google, order me a ride on”（Hey Google，约车 示例应用。”借助前台应用调用，您可以进一步提升用户在打开您的应用后获享的体验。

通过前台应用调用，无需匹配内置 intent (BII) 要求在 Chrome 中 设备前台运行

举例来说，某位用户在前台运行拼车应用，然后对 Google 助理说出或输入“Order me a ride to Mountain View”。该应用会根据此输入内容，将目的地字段设为 Mountain View。然后，当用户说出或 “给我订购来自 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 参考文档。

注意 ：无法使用 与应用有关的 Action 测试工具。若要在提交应用之前试用前台应用调用，请先为应用创建预览，然后在测试设备上通过 Google 助理触发与应用有关的 Action。

支持前台应用调用

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

注意 ：在应用中将 fragment 用作目的地时，请传达 intent 向相关 fragment 发送信息。

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

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

。

注意： intent 会按从上到下的顺序进行解析，因此请将 intent 与必需的 在 <capability> 中位于其他 intent 之上的前台 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：

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。