Cómo crear Acciones en apps

Las Acciones en apps permiten que los usuarios inicien funciones en tu app para Android si se lo piden a Asistente de Google o con atajos que sugiere Asistente. A continuación, se indican los pasos principales que debes seguir para extender tu app para Android con las Acciones en apps:

1. Identifica la función integrada en la app que se debe activar y su intent integrado (BII) correspondiente.
2. Proporciona detalles de entrega del BII.
3. Envía atajos de tu Acción en la app a Asistente.
4. Obtén una vista previa de tus Acciones en apps en un dispositivo de prueba.
5. Crea una versión de prueba de tu app.
6. Solicita la revisión y la implementación de Acciones en apps.

De manera opcional, puedes definir atajos dinámicos para brindar a Asistente para que pueda sugerirlos a los usuarios. Crea una Acción en la app con una app de ejemplo siguiendo el codelab de Acciones en apps.

Precaución: Debido a restricciones regulatorias, las apps que participan en el programa Diseñado para familias (DFF) no pueden tener Acciones en apps. Si envías a revisión una Acción en la app para una app incluida en el programa DFF, no se podrá aprobar.

Requisitos

Antes de comenzar a desarrollar Acciones en apps, asegúrate de que tú y tu app cumplan con los siguientes requisitos:

• Debes tener una Cuenta de Google con acceso a Google Play Console.
• Tu app debe estar publicada en Google Play Store, ya que las Acciones en apps solo están disponibles para apps publicadas en esa plataforma. Además, asegúrate de que tu app no esté diseñada para usarse en un perfil de trabajo, ya que las Acciones en apps no son compatibles con Google Play administrado.
• Necesitas un dispositivo físico o virtual para probar tus Acciones en apps.
• Necesitas la versión más reciente de Android Studio.
• Debes usar la misma Cuenta de Google para acceder a Android Studio, a la app de Google en tu dispositivo de prueba y a Google Play Console.
• Debes configurar Asistente en tu dispositivo de prueba y mantener presionado el botón de inicio para probarlo.

Cómo hacer coincidir los intents integrados con las funciones de la app

Identifica las funciones de tu app para Android a las que los usuarios quieran acceder rápidamente con una solicitud por voz y consulta la referencia sobre intents integrados para conocer los BIIs apropiados para tus casos de uso. Los BIIs modelan las consultas de los usuarios para las tareas que quieren realizar, por lo que debes buscar BIIs que coincidan con las funciones clave y los flujos de usuarios de tu app.

Hay BIIs comunes que casi cualquier app para Android puede usar, como extender tu búsqueda en la app al Asistente con el BII actions.intent.GET_THING o permitir que los usuarios inicien funciones específicas de la app con la voz implementando el BII actions.intent.OPEN_APP_FEATURE.

Importante: Como parte de los requisitos de implementación de Acciones en apps, las apps que tienen una función de búsqueda deben implementar el BII actions.intent.GET_THING para que los usuarios puedan buscar contenido en tu app con comandos por voz de uso frecuente, como "Hey Google, busca calzado para correr en App de Ejemplo".

También hay BIIs que permiten los casos de uso verticales o específicos de categorías. Por ejemplo, una app de ejercicio podría usar el BII actions.intent.START_EXERCISE.

Nota: En los casos en que no hay un BII para las funciones de tu app, puedes usar un intent personalizado y extender la app con Acciones en apps.

Para garantizar una experiencia del usuario óptima y evitar posibles retrasos en la aprobación, asegúrate de que cada BII que implementes sea relevante para las funciones de tu app.

Las Acciones en apps inician los intents de Android desde la app de Asistente para llevar a los usuarios directamente a contenido específico de tu app. Puedes definir intents para iniciar una actividad de forma explícita si especificas los campos targetClass y targetPackage. Si tu app ya implementa URLs de vínculo directo de Android, tienes la opción de configurar el intent para que use un vínculo directo en la entrega. Para obtener más detalles, consulta la sección Cómo probar los vínculos directos de tu actividad.

Cómo brindar detalles de entrega de intents integrados

La mayor parte de la compilación de una Acción en la app es declarar una capability en el archivo de recursos shortcuts.xml de la app para Android, en el que especificas el BII seleccionado y la entrega correspondiente. Un BII modela la consulta del usuario para una tarea y un intent de entrega brinda a Asistente información para realizar la tarea.

En tu archivo shortcuts.xml, los BIIs se representan como elementos <capability> y cada entrega se representa como un elemento <intent>:

<shortcuts>
    <capability android:name="actions.intent.START_EXERCISE">
        <intent
            android:action="android.intent.action.VIEW"
            android:targetPackage="com.example.app"
            android:targetClass="com.example.app.browse">
            <parameter
                android:name="exercise.name"
                android:key="exercise_name">
            </parameter>
        </intent>
    </capability>

Nota: Se requiere la biblioteca de Jetpack androidx.core:core:1.6.0 (o una posterior) en tu proyecto de Android para evitar errores de compilación a la hora de definir las capacidades de Acciones en apps en shortcuts.xml. Para obtener más información, consulta Cómo comenzar a usar Android Jetpack.

En la mayoría de los BIIs, debes extraer los parámetros del intent de la consulta del usuario en función de las entidades de schema.org. Luego, la app usa esos parámetros para dirigir a los usuarios a la capability seleccionada. Por ejemplo, el código anterior asigna el parámetro de BII exercise.name al parámetro intent de Android exercise_name.

Si entregas acciones usando vínculos directos, debes usar el campo urlTemplate para definir la URL del vínculo directo que genera Asistente:

<shortcuts>
    <capability android:name="actions.intent.START_EXERCISE">
        <intent android:action="android.intent.action.VIEW">
            <url-template android:value="myexerciseapp://start{?exercise_name}" />
            <parameter android:name="exercise.name"
                android:key="exercise_name"
                android:mimeType="text/*">
            </parameter>
        </intent>
    </capability>
</shortcuts>

Nota: Cuando la app proporciona varios intents para la entrega de un solo BII, Asistente intenta resolverlos en el orden en que aparecen dentro del elemento capability.

Si quieres obtener detalles importantes para agregar Acciones en apps al archivo shortcuts.xml, consulta Cómo crear shortcuts.xml. En esa página, también se describe cómo especificar los valores de parámetro que espera tu app.

Cómo implementar el intent integrado GET_THING

Si tu app tiene una función de búsqueda, debes implementar el BII actions.intent.GET_THING para esa función. Luego, Asistente puede redirigir a los usuarios a la función de búsqueda de tu app para los resultados en la app cuando realizan consultas como "Hey Google, busca Elemento de Ejemplo en App de Ejemplo".

En tu archivo shortcuts.xml, implementa una <capability> para el BII actions.intent.GET_THING como lo harías con cualquier otro BII. Puedes usar varias entregas para GET_THING, siempre y cuando proporciones al menos una entrega que pase la consulta del usuario a la función de búsqueda de la app.

A continuación, se muestra un ejemplo para agregar el BII actions.intent.GET_THING en shortcuts.xml:

  <capability android:name="actions.intent.GET_THING">
    <intent
      android:targetPackage="com.example.myapp"
      android:targetClass="com.example.myapp.MySearchActivity">
      <parameter android:name="thing.name" android:key="query" />
    </intent>
  </capability>

En Activity de búsqueda, extrae la búsqueda de los datos adicionales del intent y pásala a la función de búsqueda de tu app. En el código anterior, la búsqueda (que se pasa como la clave query) se asigna al parámetro de BII "thing.name". Luego, realiza una búsqueda con la consulta y muestra los resultados en la interfaz de usuario.

Cómo enviar atajos de tu Acción en la app a Asistente (opcional)

Una vez que hayas definido una capability para tu acción, los usuarios podrán iniciarla si dicen, por ejemplo: "Hey Google, pide una pizza en App de Ejemplo". Asistente puede sugerirles atajos de Android a tus acciones en momentos relevantes, lo que les permitirá descubrir y reproducir tus acciones. Asistente puede sugerir atajos dinámicos y estáticos.

Para enviar atajos dinámicos a Asistente, usa la biblioteca de integración de atajos de Google. Esta biblioteca de Jetpack permite que Asistente adquiera tus atajos y los sugiera a los usuarios en el momento oportuno.

Si deseas obtener más información, consulta Cómo enviar atajos dinámicos a Asistente.

Cómo obtener una vista previa de tus Acciones en apps

Durante el desarrollo y las pruebas, usa el complemento de Asistente de Google para Android Studio para probar que las Acciones en apps funcionen en tu app. El complemento crea una vista previa de las Acciones en apps en Asistente (para tu Cuenta de Google). Con esta herramienta, puedes probar las entregas en un dispositivo físico o emulador de prueba proporcionando BIIs con los parámetros de entrada que esperas recibir de los usuarios.

Nota: También puedes agregar verificadores adicionales para tu integración de Acciones en apps, incluso si no comparten la misma cuenta de Play Console. Si deseas obtener más información, consulta Cómo agregar verificadores adicionales.

Durante la vista previa de tus Acciones en apps, puedes activar consultas por voz en el dispositivo. Esta función solo está disponible para las consultas que se indican en la referencia de BII de las Acciones en apps. Usa activadores de voz solo con fines demostrativos y no para pruebas periódicas.

Nota: La herramienta de pruebas de Acciones en apps solo admite pruebas de BIIs en la configuración regional en-US, a menos que se proporcionen consultas de ejemplo para otras configuraciones regionales en la referencia de intents integrados correspondiente.

Prueba tu app en modo de borrador usando las herramientas para desarrolladores de Google Play Console antes de enviarla para su revisión. Si quieres obtener más información para usar Google Play Console para implementar un borrador de tu app, consulta Prepara y lanza una versión.

Cómo crear una versión de prueba

Cuando tengas todo listo para probar tus Acciones en apps con verificadores adicionales, crea una versión de prueba interna o cerrada de tu app. De forma predeterminada, los verificadores de tu versión interna y cerrada pueden acceder a las Acciones en apps que ya se revisaron y aprobaron.

Si deseas otorgar acceso a las pruebas a todas las Acciones en apps, incluidas las acciones no aprobadas, indícales a los verificadores que se unan al Grupo de Google del Programa de desarrollo de Acciones en apps. Los miembros de este grupo tienen acceso a todas las Acciones en apps de tus versiones de prueba internas y cerradas sin tener que crear vistas previas con la herramienta de pruebas de Acciones en apps. El acceso puede demorar hasta tres horas después de unirse al grupo.

Nota: Las Acciones en apps de los segmentos de pruebas abiertas no estarán disponibles para los usuarios hasta que se hayan revisado y aprobado. Para obtener más información, consulta la siguiente sección.

Cómo solicitar la revisión e implementación de Acciones en apps

Las Acciones en apps no estarán disponibles para los usuarios de tus apps publicadas o de las versiones de prueba abierta hasta que se hayan revisado y aprobado. La revisión de Acciones en apps no afecta el estado de implementación y revisión de tu app para Android en Google Play. Incluso si se aprueba el envío de tu app y se publica en Play Store, es posible que el shortcuts.xml esté en proceso de revisión por parte de Google. Las Acciones en apps no funcionan para tus usuarios finales hasta que también se apruebe esa revisión.

Cuando implementes la app, las Acciones en apps permanecerán activadas. Sin embargo, Google revisa las versiones que se vuelven a implementar. Si la versión nueva no funciona correctamente o contiene incumplimientos de política, Google se reserva el derecho de desactivar las Acciones en apps para tu app.

Si deseas enviar tus Acciones en apps a revisión, haz lo siguiente:

1. Acepta las Condiciones del Servicio de Acciones en apps en Google Play Console (Configuración avanzada > Acciones en apps):

   

2. Sube la app con el archivo shortcuts.xml a Google Play Console como de costumbre para publicarla.

3. Después de subir la app a Play Console, Google se comunicará contigo a través del correo electrónico que figura en tu cuenta de Play Console con más información sobre el estado de la revisión de Acciones en apps. También puedes comunicarte con el equipo de asistencia para desarrolladores de Asistente si tienes preguntas sobre el estado de revisión de tus Acciones en apps. En el formulario de contacto, proporciona el ID de paquete de tu app y elige la opción de revisión de Acciones en apps en la casilla de selección ¿En qué podemos ayudarte?.

Nota: Si tu app está restringida en función de credenciales de acceso, proporciona un acceso de prueba con la entrega de la app. Para proporcionar las credenciales de prueba, selecciona tu app en Play Console, navega a Políticas > Contenido de la app y sigue las instrucciones que aparecen en Acceso a apps.

(Opcional) Cómo probar los vínculos directos de tu actividad

Si quieres usar un vínculo directo para iniciar una Activity usando una Acción en la app, debes configurar Activity con URLs de vínculo directo y tener un filtro de intents correspondiente en el manifiesto de la app para Android.

Nota: El vínculo directo se puede basar en URLs de App Links, en URLs basadas en intents o en esquemas personalizados, como myapp://do.thing/param=value.

Si deseas probar que tus actividades sean accesibles y que se puedan activar con Acciones en apps con vínculos directos, ejecuta el siguiente comando adb:

$ adb shell am start -a android.intent.action.VIEW -d "AppLinksURL"

Por ejemplo:

$ adb shell am start -a android.intent.action.VIEW -d "https://www.example.com/deeplink"

Si tu actividad no se inicia correctamente con el comando adb, verifica lo siguiente:

• En el archivo de manifiesto de la app, la actividad tiene el parámetro android:exported=true de modo que se puede iniciar con intents de Asistente de Google.
• Si usas URLs de App Links, sigue todos los pasos en Cómo controlar Android App Links.

Políticas de Acciones en apps

Las Acciones en apps deben cumplir con políticas específicas para ayudar a garantizar que los usuarios que las activen reciban la experiencia esperada. Revisa estas políticas antes de enviar tus apps para proporcionar la mejor experiencia del usuario y evitar demoras o rechazos en la revisión de Play Store.

• Cómo dirigir a los usuarios al contenido que esperan

  Los intents integrados (BIIs) de las Acciones en apps y los parámetros solo deben dirigir a los usuarios a la acción relevante que ellos esperan. Esto puede incluir contenido en la app o en el sitio web, o información que se muestra en slices o widgets, siempre y cuando la experiencia sea la que esperaba el usuario.

  Por ejemplo, las implementaciones del BII START_EXERCISE ayudan a los usuarios a iniciar un ejercicio de un tipo determinado, como correr o nadar. La única excepción a esta política es cuando tu BII OPEN_APP_FEATURE dirige a los usuarios a la pantalla principal de tu app.

• Cómo implementar BIIs de Acciones en apps relevantes

  Los BIIs implementados deben estar directamente relacionados con el contenido y las funciones de la app.

  Por ejemplo, si tu app está en la categoría Comunicaciones de Play Store, no implementes el BII START_EXERCISE, que se recomienda para apps de la categoría Salud y fitness.

• Cómo implementar intents personalizados relevantes

  Las consultas definidas para intents personalizados se relacionan con el contenido y las funciones de la app. Un ejemplo de una potencial infracción de esta política es crear el intent custom.action.intent.GET_RECIPE con el patrón de consulta asociado "Muéstrame recetas de burritos" para una app en la categoría Transporte de Play Store.

---