Introdução à API Ambient

A API Ambient permite que seu aplicativo conecte dispositivos ambientais à conta do Google Fotos de um usuário e mostre as fotos selecionadas.

Fluxo da API Ambient

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

  1. Verifique se já existe um dispositivo (recomendado): antes de criar um novo dispositivo, é recomendável verificar se já existe um para o usuário atual. Seu 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. Inicie a autorização do OAuth 2.0 (e, opcionalmente, crie um dispositivo): 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: seu app cria um dispositivo na conta do Google Fotos de um usuário chamando CreateDevice e fornecendo um UUID v4 válido.

    Se a criação do dispositivo for bem-sucedida, a API vai retornar um objeto AmbientDevice que contém um deviceId atribuído pelo Google. É fundamental que seu 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, geralmente como um QR code, que ele pode ler usando o dispositivo móvel. Esse URI direciona o usuário para o app Google Fotos, onde ele pode configurar as fontes de mídia (por exemplo, álbuns) que quer mostrar no dispositivo ambiente.

  5. Pesquise mediaSourcesSet: seu aplicativo precisa chamar periodicamente o método GetDevice, fornecendo o deviceId, para verificar o status do dispositivo ambiente. Monitore o campo mediaSourcesSet na resposta AmbientDevice. Inicialmente, será "false".

    Quando o usuário selecionar fontes de mídia no app Google Fotos, esse campo vai mudar para "true".

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

  6. Recuperar itens de mídia: quando mediaSourcesSet retorna "true", seu aplicativo pode 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 um ListMediaItemsResponse que contém uma lista de objetos AmbientMediaItem. Cada AmbientMediaItem inclui detalhes como um id, um 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 para listar e recuperar itens de mídia e saber mais sobre outros parâmetros baseUrl.

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

Considerações importantes

Limite e gerenciamento de dispositivos:

  • Limites de dispositivos: saiba que há um limite de 100 dispositivos por usuário do seu aplicativo.
  • Atividade e tokens do dispositivo: você precisa gerenciar o ciclo de vida dos dispositivos e os tokens de autorização do usuário. Considere por quanto tempo os dispositivos permanecem ativos e como você vai lidar com atualizações ou novas autorizações de token se um dispositivo ficar inativo ou se 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 do item 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 fontes 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