Invocación de apps en primer plano

Las Acciones en apps permiten que los usuarios hablen con Asistente de Google y vayan directamente a destinos de apps específicos cuando dicen, por ejemplo: "Hey Google, pide un viaje en App de Ejemplo". Con la invocación de apps en primer plano, puedes mejorar aún más la experiencia cuando un usuario ya tiene la app abierta.

La invocación de apps en primer plano permite que los intents integrados (BIIs) coincidan sin que se mencione el nombre de la app mientras se realiza una actividad específica en el dispositivo, en primer plano.

Por ejemplo, un usuario tiene tu app de transporte compartido en primer plano y le dice o escribe "Pídeme un viaje a Mountain View" al Asistente de Google. Tu app usa esta entrada para establecer el campo de destino en Mountain View. Luego, cuando el usuario diga o escriba "Pídeme un viaje desde el aeropuerto de San Francisco", tu app también podrá establecer el lugar de recogida y preservar el estado de la app.

Limitaciones

La invocación de apps en primer plano solo está disponible para los siguientes BIIs:

Para obtener compatibilidad con la configuración regional y consultas de ejemplo relacionadas con la invocación de apps en primer plano para un BII específico, consulta la referencia del intent integrado.

Cómo admitir la invocación de apps en primer plano

Agregar compatibilidad con la invocación de apps en primer plano implica agregar un comportamiento de entrega basado en la actividad deseada en primer plano. Cuando esa actividad está en primer plano y se invoca la Acción en la app, Asistente pasa el intent de vínculo directo con una marca adicional a esa actividad para que tu app pueda actualizar su estado.

Si quieres implementar la invocación de apps en primer plano para un BII, haz lo siguiente:

  1. En tu archivo shortcuts.xml, agrega una etiqueta <intent> al BII <capability> que quieras admita la invocación de apps en primer plano.
  2. Dentro de la etiqueta <intent>, agrega una etiqueta <extra>.
  3. En la etiqueta <extra>, configura android:key como "requiredForegroundActivity" y android:value como la actividad que deseas que requiera estar en primer plano. Especifica la actividad sin abreviaturas de clase con el nombre del paquete de tu app, seguido de una barra diagonal (/) y, luego, el nombre de la actividad: APP_PACKAGE_NAME/ACTIVITY_NAME.
  4. En la actividad en primer plano que especificaste para "requiredForegroundActivity", implementa el método onNewIntent() para controlar un intent de vínculo directo con el conjunto de marcas SINGLE_TOP. Asistente pasa el intent de vínculo directo con esta marca como entrega cuando la actividad especificada está en primer plano.
  5. Considera que las llamadas a onNewIntent() son actualizaciones de tu actividad en primer plano y administra el estado de esa actividad con parámetros extraídos del vínculo directo.

Si tu app usa una actividad del router para permitir que todos los vínculos directos externos activen una sola actividad de router, consulta Cómo controlar las actividades del router.

Ejemplo

El siguiente fragmento de un shortcuts.xml de ejemplo muestra cómo agregar el atributo 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>

Permisos del usuario

En la configuración del dispositivo, los usuarios deben habilitar la opción &quot;Utilizar el texto de la pantalla&quot; para que funcione la invocación de apps en primer plano.

Para que la invocación de apps en primer plano funcione para un usuario, este debe haber habilitado la opción Utilizar el texto de la pantalla en el dispositivo. La ubicación y el nombre exacto de esta opción pueden variar según el OEM o el fabricante del dispositivo. Por ejemplo, podría llamarse Usar contexto de la pantalla en el dispositivo del usuario.

Para llegar a esta opción de Android en un teléfono Pixel, primero ve a Configuración > Apps y notificaciones > Apps predeterminadas > Aplicación de asistencia. Luego, en la pantalla Asistencia y entrada de voz, habilita Utilizar el texto de la pantalla.

Cómo probar tu invocación

Para probar la invocación de tu app en primer plano, sigue estos pasos:

  1. Sigue las instrucciones de la sección Permisos del usuario para habilitar la configuración del dispositivo Utilizar el texto de la pantalla.
  2. Abre tu app en la actividad que indicaste como actividad obligatoria en primer plano.
  3. Mantén presionado el botón de inicio para abrir Asistente como una superposición en la app actual. Proporciona una consulta que corresponda al BII que implementaste sin mencionar el nombre de la app. Si no hay errores, la app se actualiza en función de tu consulta mientras mantiene el estado y no reinicia la actividad.

Cómo controlar las actividades del router

Algunas apps controlan todos los vínculos directos externos con una sola actividad del router. Luego, la actividad del router inicia la actividad de lógica empresarial correspondiente (después de las comprobaciones y validaciones pertinentes) y la muestra en primer plano.

La activación de un vínculo directo puede hacer que la actividad del router se agregue a la parte superior de la pila de tareas encima de la actividad en primer plano. En el caso de las apps que usan una actividad del router, debes asegurarte de que esta proporcione el intent que envía Asistente de Google a la instancia de la actividad actual en primer plano. La forma de cumplir con este requisito cambia según el lugar donde comience la actividad del router.

Si el router se inicia en la misma pila de tareas que la actividad de lógica empresarial, reenvía el intent con el OR bit a bit de SINGLE_TOP, CLEAR_TOP y NEW_TASK:

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

Si tu router se inicia en una pila de tareas independiente de tu actividad lógica empresarial, reenvía el intent con la marca SINGLE_TOP a la actividad de lógica empresarial.