Comienza a usar la API de Ambient

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

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 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 continuar con la actualización de su token de autorización (si es necesario).

2. Inicia la autorización de OAuth 2.0: Para comenzar el flujo de OAuth 2.0 para TV y dispositivos de entrada limitada , solicita un código de autorización.

   Nota: La API de Ambient admite la inclusión del parámetro state en tu solicitud de autorización para habilitar el flujo de autenticación optimizado.

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 la creación del dispositivo se realiza correctamente, la API mostrará 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, donde puede configurar las fuentes de contenido multimedia (p.ej., álbumes) que desea mostrar en su dispositivo ambiente.

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

   Una vez que el usuario haya seleccionado correctamente las fuentes de contenido multimedia 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 muestra 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 mostrará un ListMediaItemsResponse que contiene una lista de objetos AmbientMediaItem. Cada AmbientMediaItem incluye detalles como un id, createTime y un objeto MediaFile con metadatos adicionales. MediaFile contiene un baseUrl que puedes usar para recuperar los bytes reales de un elemento multimedia. Consulta la guía para enumerar y recuperar elementos multimedia para obtener detalles sobre los parámetros baseUrl adicionales.

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

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 del dispositivo y tokens: Deberás administrar el ciclo de vida de los dispositivos y los tokens de autorización del usuario. Considera cuánto tiempo permanecen activos los dispositivos y cómo manejarás las actualizaciones de tokens o la nueva autorización si un dispositivo se inactiva o vence el token.

La guía para crear y administrar dispositivos tiene detalles adicionales.

Trabaja con elementos multimedia:

• Uso de elementos multimedia: Comprende cómo recuperar y manejar correctamente el contenido de los elementos multimedia con el 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 las fuentes de contenido multimedia y RESOURCE_EXHAUSTED si se alcanzan los límites de dispositivos.

La guía para enumerar y recuperar elementos multimedia tiene 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 TV y dispositivos 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.