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 aplicaciones de dispositivos de TV y de entrada limitada, crea un dispositivo en su cuenta de Google Fotos.

Cuando tu app crea un dispositivo correctamente con el método devices.create, la API de Ambient muestra un objeto AmbientDevice que incluye un id generado por Google. Almacena de forma segura este id 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 podrá acceder ni limpiar.

Creación de dispositivos optimizada con OAuth

La API de Ambient ofrece un flujo de OAuth optimizado que puede crear un dispositivo de forma simultánea con la autenticación del usuario. Si pasas el parámetro state adicional en tu solicitud de OAuth inicial, puedes vincular el proceso de creación de dispositivos 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 necesites administrar su ciclo de vida.

Cómo 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 los identifiquen más fácilmente en Google Fotos.

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

Borrar dispositivos

Implementa una estrategia para borrar dispositivos para una limpieza y un control de usuarios adecuados. Puedes borrar un dispositivo con el método devices.delete.

Considera 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 rastro 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 la cuenta del usuario ordenada.

Consideraciones y prácticas recomendadas importantes

• 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. Ten en cuenta durante cuánto tiempo los dispositivos permanecen activos y cómo controlarás las actualizaciones de tokens o la nueva autorización si un dispositivo se vuelve inactivo o si 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 ejemplo: Nuestra aplicación de ejemplo 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 las documentaciones de referencia completas sobre los 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.
• Enumera y recupera elementos multimedia: Una vez que hayas creado y administrado tus dispositivos, aprende a enumerar y recuperar elementos multimedia para mostrarlos en ellos.