Introdução à API Ambient

A API Ambient permite que o aplicativo conecte dispositivos ambientais a uma conta do Google Fotos do usuário e mostre as fotos selecionadas.

Fluxo da API Ambient

Confira um detalhamento de como a API Ambient funciona para conectar um dispositivo e, em seguida, recuperar e mostrar itens de mídia:

  1. Verificar se já existe um dispositivo (recomendado): antes de criar um novo dispositivo, recomendamos verificar se já existe um para o usuário atual. O aplicativo precisa manter um mapeamento entre o usuário interno e o deviceId fornecido pelo Google para todos os dispositivos criados pelo app. Se um deviceId for encontrado para o usuário, você poderá atualizar o token de autorização (se necessário).

  2. Iniciar a autorização do OAuth 2.0: comece o fluxo do OAuth 2.0 para TV e dispositivos de entrada limitada solicitando um código de autorização.

  3. Criar um novo dispositivo: o app cria um dispositivo na conta do Google Fotos de um usuário chamando CreateDevice e fornecendo um UUID v4 válido.

    Após a criação do dispositivo, a API vai retornar um objeto AmbientDevice que contém um deviceId atribuído pelo Google. É fundamental que o aplicativo armazene esse deviceId e o associe aos usuários.

  4. Mostrar o settingsUri: um objeto AmbientDevice inclui um settingsUri. Apresente esse URI ao usuário, normalmente como um QR code, que ele pode ler usando o dispositivo móvel. Esse URI direciona o usuário ao app Google Fotos, em que ele pode configurar as origens de mídia (por exemplo, álbuns) que quer mostrar no dispositivo ambiental.

  5. Pesquisar mediaSourcesSet: o aplicativo precisa chamar o método GetDevice periodicamente, fornecendo o deviceId, para verificar o status do dispositivo ambiental. Monitore o campo mediaSourcesSet na resposta AmbientDevice. Ele será inicialmente falso.

    Depois que o usuário selecionar as origens de mídia no app Google Fotos, esse campo vai mudar para verdadeiro.

    A resposta AmbientDevice inclui um pollingConfig com um pollInterval que você deve usar como diretriz para a frequência de pesquisa.

  6. Recuperar itens de mídia: quando mediaSourcesSet retornar verdadeiro, o aplicativo poderá começar a buscar os itens de mídia selecionados pelo usuário.

    Chame o método ListMediaItems, fornecendo o deviceId. A API vai retornar uma ListMediaItemsResponse que contém uma lista de objetos AmbientMediaItem. Cada AmbientMediaItem inclui detalhes como um id, createTime e um objeto MediaFile com metadados adicionais. O MediaFile contém um baseUrl que pode ser usado para buscar os bytes reais de um item de mídia. Consulte o guia Listar e recuperar itens de mídia para mais detalhes sobre outros parâmetros baseUrl.

  7. Mostrar itens de mídia: use o baseUrl do MediaFile para fazer o download e mostrar o conteúdo de mídia no dispositivo ambiental.

Considerações importantes

Limite e gerenciamento de dispositivos:

  • Limites de dispositivos: há um limite de 100 dispositivos por usuário do aplicativo.
  • Atividade e tokens de dispositivos: é necessário gerenciar o ciclo de vida da atividade do dispositivo 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 a reautorização de tokens se um dispositivo ficar inativo ou o token expirar.

O guia Criar e gerenciar dispositivos tem mais detalhes.

Como trabalhar com itens de mídia:

  • Uso de itens de mídia: entenda como buscar e processar corretamente o conteúdo de itens de mídia usando o baseUrl, incluindo qualquer autenticação ou parâmetro necessário.
  • Tratamento de erros: implemente um tratamento de erros robusto para chamadas de API, incluindo cenários como NOT_FOUND para dispositivos, FAILED_PRECONDITION se as origens de mídia não estiverem definidas e RESOURCE_EXHAUSTED se os limites de dispositivos forem atingidos.

O guia Listar e recuperar itens de mídia tem mais detalhes, incluindo informações sobre política de conteúdo e filtragem.

Próximas etapas