Comienza a usar la API de Ambient

La API de Ambient permite que tu aplicación conecte dispositivos Ambient a la cuenta de Google Fotos de un usuario y muestre las fotos que seleccionó.

El flujo de la API de Ambient

A continuación, se muestra un desglose de cómo funciona la API de Ambient para conectar un dispositivo y, luego, recuperar y mostrar elementos multimedia:

1. Verifica si ya existe un dispositivo (recomendado): Antes de crear un dispositivo nuevo, se recomienda verificar si ya existe un dispositivo para el usuario actual. Tu aplicación debe mantener una asignación entre tu usuario interno y el deviceId proporcionado por Google para cualquier dispositivo que cree a través de tu app. Si se encuentra un deviceId para el usuario, puedes proceder a actualizar su token de autorización (si es necesario).

2. Inicia la autorización de OAuth 2.0 (y, de manera opcional, crea un dispositivo): Inicia el flujo de OAuth 2.0 para dispositivos de TV y de entrada limitada solicitando un código de autorización.

   Nota: La API de Ambient admite la opción de incluir el parámetro state en tu solicitud de autorización. Esto indicará a la API de Ambient que también intente crear un dispositivo nuevo tras la autorización correcta.

3. Crea un dispositivo nuevo: Tu app crea un dispositivo en la cuenta de Google Fotos de un usuario llamando a CreateDevice y proporcionando un UUID v4 válido.

   Si se crea el dispositivo correctamente, la API devolverá un objeto AmbientDevice que contiene un deviceId asignado por Google. Es fundamental que tu aplicación almacene este deviceId y lo asocie con tus usuarios.

4. Muestra el settingsUri: Un objeto AmbientDevice incluye un settingsUri. Presenta este URI al usuario, por lo general, como un código QR que el usuario puede escanear con su dispositivo móvil. Este URI dirige al usuario a la app de Google Fotos, en la que puede configurar las fuentes de contenido multimedia (p.ej., álbumes) que desea mostrar en su dispositivo ambiente.

5. Sondea mediaSourcesSet: Tu aplicación debe llamar periódicamente al método GetDevice, proporcionando el deviceId, para verificar el estado del dispositivo ambiental. Supervisa el campo mediaSourcesSet en la respuesta de AmbientDevice. Inicialmente, será falso.

   Una vez que el usuario haya seleccionado correctamente las fuentes de medios en la app de Google Fotos, este campo cambiará a verdadero.

   La respuesta AmbientDevice incluye un pollingConfig con un pollInterval que debes usar como guía para tu frecuencia de sondeo.

6. Recupera elementos multimedia: Cuando mediaSourcesSet devuelve verdadero, tu aplicación puede comenzar a recuperar los elementos multimedia seleccionados por el usuario.

   Llama al método ListMediaItems y proporciona el deviceId. La API devolverá un ListMediaItemsResponse que contiene una lista de objetos AmbientMediaItem. Cada AmbientMediaItem incluye detalles como un id, un createTime y un objeto MediaFile con metadatos adicionales. El objeto MediaFile contiene un objeto baseUrl que puedes usar para recuperar los bytes reales de un elemento multimedia. Revisa la guía para listar y recuperar elementos multimedia para obtener detalles sobre parámetros baseUrl adicionales.

7. Mostrar elementos multimedia: Usa baseUrl de MediaFile para descargar y mostrar el contenido multimedia en el dispositivo ambient.

Consideraciones importantes

Límite y administración de dispositivos:

• Límites de dispositivos: Ten en cuenta el límite de 100 dispositivos por usuario de tu aplicación.
• Actividad y tokens del dispositivo: Deberás administrar el ciclo de vida de los dispositivos y los tokens de autorización del usuario. Ten en cuenta cuánto tiempo permanecen activos los dispositivos y cómo controlarás las actualizaciones de tokens o las reautorizaciones si un dispositivo se vuelve inactivo o el token vence.

En la guía para crear y administrar dispositivos, encontrarás más detalles.

Trabaja con elementos multimedia:

• Uso de elementos multimedia: Comprende cómo recuperar y controlar correctamente el contenido de los elementos multimedia con baseUrl, incluidos los parámetros o la autenticación necesarios.
• Manejo de errores: Implementa un manejo de errores sólido para las llamadas a la API, incluidos casos como NOT_FOUND para dispositivos, FAILED_PRECONDITION si no se configuran fuentes de medios y RESOURCE_EXHAUSTED si se alcanzan los límites de dispositivos.

En la guía para listar y recuperar elementos multimedia, encontrarás detalles adicionales, incluida información sobre la política de contenido y el filtrado.

Próximos pasos

• Configura tu aplicación: Verifica que tengas las credenciales necesarias y que hayas configurado tu aplicación para OAuth 2.0 para dispositivos de TV y de entrada limitada.
• Revisa la documentación de referencia de la API de Ambient: Explora la documentación de referencia detallada para todos los métodos disponibles, los parámetros de solicitud y respuesta, y los códigos de error.