Configurar o app para a API Ambient

Para começar a usar a API Ambient, ative a API no Console de APIs do Google e configure um ID de cliente OAuth 2.0. A API Ambient usa OAuth 2.0 para apps de TV e dispositivos de entrada limitada.

Seu aplicativo interage com a API Ambient em nome de um usuário da API Ambient. O usuário autoriza essas solicitações de API usando o protocolo OAuth 2.0.

O ID do cliente OAuth 2.0 permite que os usuários do aplicativo façam login, se autentiquem e usem a API Ambient. A API Ambient não oferece suporte a contas de serviço. Para usar essas APIs, os usuários precisam fazer login em uma Conta do Google válida.

Configurar o app

Primeiro, ative a API e, em seguida, solicite um ID do cliente OAuth 2.0.

Ativar a API

Antes de usar a API Ambient, é necessário ativá-la no projeto.

Acesse o Console de APIs do Google.
Na barra de menus, selecione um projeto ou crie um novo.
Para abrir uma das APIs do Google Fotos, no menu de navegação, selecione APIs e serviços > Biblioteca.
Pesquise "API Ambient". Selecione a API Ambient e clique em Ativar.

Solicitar um ID do cliente OAuth 2.0

Siga estas etapas para solicitar um ID de cliente OAuth e configurá-lo para seu app. A API Ambient usa o OAuth 2.0 para apps de TV e dispositivos de entrada limitada.

Acesse o Console de APIs do Google e selecione seu projeto.
No menu, selecione APIs e serviços > Credenciais.
Na página Credenciais, clique em Criar credenciais > ID do cliente OAuth.

Observação: se você estiver configurando um novo projeto, talvez seja necessário configurar a tela de consentimento dele.
Selecione o Tipo de aplicativo. Neste exemplo, o tipo de aplicativo é TVs e dispositivos de entrada limitada.
Dê um nome ao cliente OAuth 2.0 e clique em Criar.
Na caixa de diálogo do cliente OAuth resultante, copie o seguinte:
- ID do cliente
- Chave secreta do cliente

O app pode acessar as APIs do Google ativadas usando esses valores.

Antes de lançar um aplicativo público que acesse a API Ambient, seu app precisa ser analisado pelo Google. Uma mensagem "App não verificado" aparece na tela quando você testa o aplicativo, até que ele seja verificado.

Depois de configurar o app, você estará pronto para começar. Confira os recursos a seguir ou leia mais sobre o fluxo de autenticação simplificado da API Ambient.

Como mudar o ID do cliente

Os recursos criados com qualquer uma das APIs do Google Fotos só podem ser acessados ou modificados usando o ID de cliente original usado para criá-los. Por exemplo, se você criar um session na API Picker com um ID do cliente específico e depois mudar esse ID no app, o app vai perder o acesso a todos os recursos de API criados com o ID do cliente anterior.

Planeje com cuidado e escolha o tipo de ID de cliente correto para a API do Google Fotos que você está usando. Só mude o ID do cliente se for absolutamente necessário para evitar problemas de acesso.

Fluxo de autenticação simplificado para a API Ambient

O fluxo de autenticação padrão da API Ambient exige que os usuários digitalizem dois códigos QR:

Primeiro, faça login na Conta do Google (se ainda não tiver feito isso).
Uma segunda chave que vincula o dispositivo Ambient recém-criado à conta do Google Fotos, onde o usuário pode selecionar os itens de mídia a serem exibidos.

O fluxo simplificado permite fornecer um único código QR aos usuários transmitindo o parâmetro state adicional com sua chamada de autenticação inicial.

Ao solicitar códigos de dispositivo e de usuário como parte do OAuth para dispositivos de entrada limitados, inclua o parâmetro state adicional com sua solicitação. Adicione o seguinte ao parâmetro state:

Parâmetros

Parâmetros
`requestId`	`string` Obrigatório. Um identificador exclusivo fornecido pelo cliente para essa solicitação. Isso é usado para reduzir a duplicação de recursos em caso de falha na rede. Esse ID precisa ter o formato de uma string UUID (versão 4) e seguir estes requisitos: Não pode conter informações sensíveis de identificação do usuário. Precisa conter 32 caracteres hexadecimais divididos em cinco grupos separados por hifens, no formato "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (ou 8-4-4-4-12).
`displayName`	`string` Opcional. Um nome de exibição definido pelo usuário para esse dispositivo. Essa informação vai ficar visível para os usuários nas configurações do app Google Fotos, mas só poderá ser editada por essa API. Os nomes de exibição válidos precisam ter entre 1 e 100 caracteres.

requestId

string

Obrigatório. Um identificador exclusivo fornecido pelo cliente para essa solicitação. Isso é usado para reduzir a duplicação de recursos em caso de falha na rede.

Esse ID precisa ter o formato de uma string UUID (versão 4) e seguir estes requisitos:

Não pode conter informações sensíveis de identificação do usuário.
Precisa conter 32 caracteres hexadecimais divididos em cinco grupos separados por hifens, no formato "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (ou 8-4-4-4-12).

displayName

string

Opcional. Um nome de exibição definido pelo usuário para esse dispositivo.

Essa informação vai ficar visível para os usuários nas configurações do app Google Fotos, mas só poderá ser editada por essa API.

Os nomes de exibição válidos precisam ter entre 1 e 100 caracteres.

Por exemplo, confira o seguinte bloco de código:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

Uma resposta bem-sucedida incluirá um user_code e um verification_url, que você mostra ao usuário (provavelmente como um código QR) para que ele possa navegar em um dispositivo separado. Ao incluir o parâmetro state, quando você chamar createDevice com a API Ambient, poderá pular a apresentação do settingsUri em um segundo código QR, já que a última etapa no fluxo OAuth redirecionará automaticamente para esse local.

Incluímos uma explicação mais detalhada para você ter todos os detalhes. Você também pode analisar o código no nosso app de exemplo para conferir um exemplo de como usar o parâmetro state como parte do OAuth para dispositivos de entrada limitados com a API Ambient.

Detalhes sobre o fluxo de autenticação simplificado

Para entender completamente o fluxo simplificado do OAuth para a API Ambient, é útil entender o fluxo do OAuth 2.0 para TV e aplicativos de dispositivos de entrada limitada, bem como o fluxo padrão da API Ambient. Confira as etapas de cada fluxo.

OAuth 2.0 para aplicativos de TV e dispositivos de entrada limitada:

O aplicativo envia uma solicitação ao servidor de autorização do Google que identifica os escopos que o aplicativo vai solicitar permissão para acessar.
O servidor responde com várias informações usadas nas etapas posteriores, como um código do dispositivo e um código do usuário.
Você mostra informações que o usuário pode inserir em um dispositivo separado para autorizar seu app.
O aplicativo começa a consultar o servidor de autorização do Google para determinar se o usuário autorizou o app.
O usuário alterna para um dispositivo com recursos de entrada mais avançados, abre um navegador da Web, navega até o URL mostrado na etapa 3 e insere um código que também é mostrado na etapa 3. O usuário pode conceder (ou negar) acesso ao app.
A próxima resposta à solicitação de pesquisa contém os tokens necessários para autorizar solicitações em nome do usuário. Se o usuário recusou o acesso ao seu app, a resposta não vai conter tokens.

Fluxo da API Ambient:

Verifique se há um token OAuth e atualize ou solicite um novo.
Depois de receber um token OAuth, crie um novo dispositivo.
Mostre o settingsUri ao usuário e comece a consultar o dispositivo até que mediaSourcesSet retorne verdadeiro.
O usuário navega até o settingsUri e seleciona as fotos que ele quer compartilhar com seu app.
Quando mediaSourcesSet retornar verdadeiro, extraia a lista de mediaItems.
Agora você pode iniciar sua apresentação de slides ou outra experiência de ambiente.

Ambos os fluxos incluem uma etapa em que você mostra um URL para o usuário, que navega até ele no dispositivo de entrada mais rico. Ao incluir o parâmetro state na chamada OAuth inicial, você pode evitar o segundo URL que precisa ser mostrado.

Isso funciona porque a última etapa do fluxo do OAuth 2.0 para aplicativos de dispositivos com TV e entrada limitada normalmente redireciona o usuário para uma página que diz "Agora você pode retornar ao seu dispositivo". Ao incluir o parâmetro de estado, a última etapa do fluxo vai tentar redirecionar você para o settingsUri. O app ainda vai receber um token OAuth. Use esse token para chamar createDevice usando o mesmo requestId. Depois que um dispositivo com o mesmo ID for criado, o fluxo inicial do OAuth vai redirecionar o usuário para a página correta no dispositivo avançado no app Fotos.

Lembre-se do seguinte:

Ainda é recomendável mostrar o settingsUri caso haja algum problema de autenticação.
Você ainda pode usar o settingsUri em outros casos, como quando um usuário quer atualizar a seleção de fotos.