Introdução à API Ambient

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

Fluxo da API Ambient

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

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

  2. Iniciar a autorização do OAuth 2.0 (e, opcionalmente, criar o dispositivo): inicie 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. É crucial 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 código QR, que pode ser digitalizado pelo dispositivo móvel. Esse URI direciona o usuário ao app Google Fotos, onde ele pode configurar as fontes de mídia (por exemplo, álbuns) que quer exibir no dispositivo ambiente.

  5. Pesquisar mediaSourcesSet: o app 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, ele será falso.

    Depois que o usuário selecionar as fontes de mídia no app Google Fotos, esse campo será alterado para "true".

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

  6. Recuperar itens de mídia: quando mediaSourcesSet retornar "true", seu app 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 um ListMediaItemsResponse contendo 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 saber mais 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 ambiente.

Considerações importantes

Limite e gerenciamento de dispositivos:

  • Limites de dispositivo: há um limite de 100 dispositivos por usuário do seu app.
  • Atividade e tokens do dispositivo: você precisa gerenciar o ciclo de vida dos dispositivos e dos tokens de autorização do usuário. Considere o tempo que os dispositivos permanecem ativos e como você vai lidar com as atualizações ou reautorizaçõ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 do item 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.
  • Processamento de erros: implemente um processamento 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 do dispositivo forem atingidos.

O guia Listar e recuperar itens de mídia tem mais detalhes.

Próximas etapas