Cómo crear y administrar dispositivos

En esta guía, se explica cómo crear, administrar y borrar dispositivos. La administración adecuada de dispositivos ayuda a crear una experiencia del usuario fluida y un uso eficiente de la API de Ambient.

Crear dispositivos

Después de que un usuario se autentique correctamente con el flujo de OAuth 2.0 para TV y aplicaciones de dispositivos de entrada limitada, crea un dispositivo en su cuenta de Google Fotos.

Cuando tu app crea correctamente un dispositivo con el método devices.create, la API de Ambient muestra un objeto AmbientDevice que incluye un id generado por Google. Almacena este id de forma segura y asócialo con tus usuarios.

Importante: Guarda el id. Si no guardas el id generado por Google, no podrás recuperar ni administrar un dispositivo más adelante. Esto puede generar dispositivos huérfanos en las cuentas de Google Fotos de tus usuarios, a los que tu aplicación no puede acceder ni limpiar.

Creación optimizada de dispositivos con OAuth

La API de Ambient ofrece un flujo de OAuth optimizado. Si pasas el parámetro state adicional en tu solicitud inicial de OAuth y llamas a devices.create con el requestId coincidente, puedes vincular el proceso de creación del dispositivo directamente al flujo de acceso del usuario, lo que simplifica la experiencia del usuario, ya que reduce la cantidad de códigos QR que debe escanear.

Para obtener más detalles y un ejemplo, consulta la guía Flujo de autenticación optimizado para la API de Ambient.

Límites de dispositivos

Tu aplicación puede crear hasta 100 dispositivos por usuario. Si se supera este límite, la API muestra un error RESOURCE_EXHAUSTED.

Administrar dispositivos

Una vez que se crea un dispositivo y se vincula a la cuenta de Google Fotos de un usuario, es posible que debas administrar su ciclo de vida.

Recuperar dispositivos

Para recuperar información sobre un dispositivo específico, usa el método devices.get con su id único. Esto es útil para verificar el estado del dispositivo, por ejemplo, si mediaSourcesSet es verdadero.

Actualizar dispositivos

Puedes actualizar ciertas propiedades de un dispositivo existente, como su nombre visible, con el método devices.patch. Esto permite que los usuarios personalicen sus dispositivos y facilita su identificación en Google Fotos.

Nota: Una práctica recomendada es ofrecerle al usuario la oportunidad de nombrar su dispositivo antes de crearlo. Esto facilita que el usuario reconozca su dispositivo cuando elige elementos multimedia en su cuenta de Google Fotos.

Borrar dispositivos

Implementa una estrategia para borrar dispositivos para una limpieza adecuada y el control del usuario. Puedes borrar un dispositivo con el método devices.delete.

Ten en cuenta las siguientes situaciones para borrar dispositivos:

• Desconexión del usuario: Si un usuario desconecta tu aplicación de su cuenta de Google Fotos, debes borrar el dispositivo correspondiente.
• Dispositivos huérfanos: Si pierdes el seguimiento de un id, pero aún tienes el requestId que se usó durante la creación, puedes usar el requestId con devices.delete para quitar un dispositivo huérfano. Esto ayuda a evitar duplicados accidentales y mantiene limpia la cuenta del usuario.

Consideraciones importantes y prácticas recomendadas

• Ciclo de vida del dispositivo y autorización del usuario: 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 controlarás las actualizaciones de tokens o la reautorización si un dispositivo se inactiva o vence su token.
• Manejo de errores: Implementa un manejo de errores sólido para todas las llamadas a la API relacionadas con el dispositivo. Prepárate para situaciones como las siguientes:
  • NOT_FOUND: Si un dispositivo no existe o no es propiedad del usuario.
  • RESOURCE_EXHAUSTED: Si superas el límite de dispositivos.
  • ALREADY_EXISTS: Si intentas crear un dispositivo con un requestId que ya existe.

Próximos pasos

• Aplicación de muestra: Nuestra aplicación de muestra incluye un ejemplo de cómo crear un dispositivo y trabajar con los datos de respuesta. Consulta la función createDevice para obtener más información.
• Documentación de referencia: Revisa la documentación de referencia completa sobre dispositivos para obtener información detallada sobre todos los métodos disponibles, los parámetros de solicitud y respuesta, y los códigos de error.
• Cómo enumerar y recuperar elementos multimedia: Una vez que hayas creado y administrado tus dispositivos, obtén información para enumerar y recuperar elementos multimedia para mostrarlos en ellos.