Criar e gerenciar dispositivos

Este guia explica como criar, gerenciar e excluir dispositivos. O gerenciamento adequado do dispositivo ajuda a criar uma experiência do usuário tranquila e o uso eficiente da API Ambient.

Criar dispositivos

Depois que um usuário for autenticado usando o fluxo do OAuth 2.0 para aplicativos de TV e dispositivos de entrada limitada, crie um dispositivo na conta do Google Fotos.

Quando o app cria um dispositivo usando o método devices.create, a API Ambient retorna um objeto AmbientDevice que inclui um id gerado pelo Google. Armazene com segurança esse id e o associe aos usuários.

Importante: salve o id. Se você não salvar o id gerado pelo Google, não vai ser possível recuperar ou gerenciar um dispositivo mais tarde. Isso pode levar a dispositivos órfãos nas contas do Google Fotos dos usuários, que não podem ser acessados nem limpas pelo seu aplicativo.

Criação simplificada de dispositivos com o OAuth

A API Ambient oferece um fluxo simplificado do OAuth que pode criar um dispositivo simultaneamente à autenticação do usuário. Ao transmitir o parâmetro state adicional na solicitação inicial de OAuth, é possível vincular o processo de criação do dispositivo diretamente ao fluxo de login do usuário, simplificando a experiência do usuário ao reduzir o número de QR codes que ele precisa ler.

Para mais detalhes e um exemplo, consulte o guia Fluxo de autenticação simplificado para a API Ambient.

Limites de dispositivos

Seu app pode criar até 100 dispositivos por usuário. Se esse limite for excedido, a API vai retornar um erro RESOURCE_EXHAUSTED.

Gerenciar dispositivos

Depois que um dispositivo é criado e vinculado à conta do Google Fotos de um usuário, talvez seja necessário gerenciar o ciclo de vida dele.

Recuperar dispositivos

Para extrair informações sobre um dispositivo específico, use o método devices.get com o id exclusivo. Isso é útil para verificar o status do dispositivo, como se mediaSourcesSet é verdadeiro.

Atualizar dispositivos

É possível atualizar determinadas propriedades de um dispositivo, como o nome exibido, usando o método devices.patch. Isso permite que os usuários personalizem os dispositivos e facilita a identificação deles no Google Fotos.

Observação: uma boa prática é oferecer ao usuário a oportunidade de nomear o dispositivo antes de criá-lo. Isso facilita muito a identificação do dispositivo pelo usuário ao escolher itens de mídia na conta do Google Fotos.

Excluir dispositivos

Implemente uma estratégia para excluir dispositivos para limpeza adequada e controle do usuário. É possível excluir um dispositivo usando o método devices.delete.

Considere os seguintes cenários para excluir dispositivos:

• Desconexão do usuário: se um usuário desconectar seu app da conta do Google Fotos, exclua o dispositivo correspondente.
• Dispositivos órfãos: se você perder o controle de um id, mas ainda tiver o requestId usado durante a criação, use o requestId com devices.delete para remover um dispositivo órfão. Isso ajuda a evitar duplicações acidentais e mantém a conta do usuário limpa.

Considerações importantes e práticas recomendadas

• Ciclo de vida do dispositivo e autorização do usuário:você precisa gerenciar o ciclo de vida dos dispositivos e dos tokens de autorização do usuário. Considere por quanto tempo os dispositivos permanecem ativos e como você vai lidar com as atualizações ou reautorizações de tokens se um dispositivo ficar inativo ou se o token dele expirar.
• Tratamento de erros:implemente um tratamento de erros robusto para todas as chamadas de API relacionadas ao dispositivo. Esteja preparado para cenários como:
  • NOT_FOUND: se um dispositivo não existe ou não pertence ao usuário.
  • RESOURCE_EXHAUSTED: se você exceder o limite de dispositivos.
  • ALREADY_EXISTS: se você tentar criar um dispositivo com um requestId que já existe.

Próximas etapas

• Exemplo de aplicativo:nosso exemplo de aplicativo inclui um exemplo de criação de um dispositivo e como trabalhar com os dados de resposta. Confira a função createDevice para mais informações.
• Documentação de referência:consulte as documentação de referência completa sobre dispositivos para informações detalhadas sobre todos os métodos, parâmetros de solicitação e resposta e códigos de erro disponíveis.
• Listar e recuperar itens de mídia:depois de criar e gerenciar seus dispositivos, aprenda a listar e recuperar itens de mídia para exibição neles.