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. Buscar un dispositivo existente (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 el usuario interno y el deviceId proporcionado por Google para todos los dispositivos que cree a través de tu app. Si se encuentra un deviceId para el usuario, puedes actualizar su token de autorización (si es necesario).

2. Iniciar la autorización de OAuth 2.0 (y, de manera opcional, crear un dispositivo): Solicita un código de autorización para iniciar el flujo de OAuth 2.0 para TV y dispositivos de entrada limitada.

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

3. Crear 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 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. Sondeo de mediaSourcesSet: Tu aplicación debe llamar periódicamente al método GetDevice y proporcionar 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 la frecuencia de sondeo.

6. Recuperar elementos multimedia: Cuando mediaSourcesSet muestra un valor verdadero, tu aplicación puede comenzar a recuperar los elementos multimedia que seleccionó 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 objeto id, createTime y MediaFile con metadatos adicionales. El 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 si deseas obtener detalles sobre los parámetros baseUrl adicionales.

7. Mostrar 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 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 durante cuánto tiempo permanecen activos los dispositivos y cómo controlarás las actualizaciones de tokens o la reautorización si un dispositivo se vuelve inactivo o si 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 controlar correctamente el contenido del elemento multimedia con baseUrl, incluidos los parámetros o la autenticación necesarios.
• Control de errores: Implementa un control 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 del dispositivo.

La guía para enumerar y recuperar elementos multimedia tiene detalles adicionales.

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 ver todos los métodos, parámetros de solicitud y respuesta, y códigos de error disponibles.