Autorização da API Tag Manager

O documento descreve como um aplicativo pode receber autorização para fazer solicitações à API Tag Manager.

Autorizar solicitações

Os usuários precisam primeiro fazer login com uma Conta do Google para visualizar as informações dela nos sites do Google. Da mesma forma, no primeiro acesso ao seu aplicativo, os usuários precisam autorizar o app a acessar os dados deles.

Todas as solicitações enviadas pelo seu aplicativo à API Tag Manager precisam incluir um token de autorização. O token também identifica o aplicativo para o Google.

Sobre os protocolos de autorização

O aplicativo deve obrigatoriamente usar o OAuth 2.0 para autorizar solicitações. Não há mais protocolos de autorização compatíveis. Se seu aplicativo usa o login do Google+, alguns aspectos da autorização são preenchidos para você.

Autorizar solicitações com OAuth 2.0

Todas as solicitações à API Tag Manager devem ser obrigatoriamente autorizadas por um usuário autenticado.

Os detalhes do processo de autorização ou “fluxo” para o OAuth 2.0 variam um pouco, dependendo do tipo de aplicativo que você está criando. O processo geral a seguir se aplica a todos os tipos de aplicativo:

  1. Ao criar seu aplicativo, registre-o usando o console de APIs do Google. Em seguida, o Google fornece informações que serão usadas mais tarde, como um ID e uma chave secreta do cliente.
  2. Ative a API Tag Manager no Console de APIs do Google. Se ela não estiver no Console de APIs, pule essa etapa.
  3. Quando seu aplicativo precisar de acesso aos dados do usuário, ele solicitará ao Google um determinado escopo do acesso.
  4. O Google exibe uma tela de consentimento ao usuário, pedindo autorização para que seu aplicativo solicite alguns dados dele.
  5. Se o usuário aprovar, o Google concederá ao seu aplicativo um token de acesso de curto prazo.
  6. Seu aplicativo solicita os dados do usuário, anexando o token de acesso à solicitação.
  7. Se o Google determinar que sua solicitação e o token são válidos, ele retorna os dados solicitados.

Alguns fluxos incluem etapas adicionais, como usar tokens de atualização para adquirir novos tokens de acesso. Para mais informações sobre fluxos de vários tipos de aplicativos, acesse a documentação OAuth 2.0 do Google.

Veja as informações de escopo do OAuth 2.0 para a API Tag Manager:

Escopo Significado
https://www.googleapis.com/auth/tagmanager.readonly Visualizar Containers do Gerenciador de tags do Google.
https://www.googleapis.com/auth/tagmanager.edit.containers Gerenciar Containers do Gerenciador de tags do Google.
https://www.googleapis.com/auth/tagmanager.delete.containers Excluir Containers do Gerenciador de tags do Google.
https://www.googleapis.com/auth/tagmanager.edit.containerversions Gerenciar Container Versions do Gerenciador de tags do Google.
https://www.googleapis.com/auth/tagmanager.publish Publicar Containers do Gerenciador de tags do Google.
https://www.googleapis.com/auth/tagmanager.manage.users Gerenciar User Permissions dos dados do Gerenciador de tags do Google.
https://www.googleapis.com/auth/tagmanager.manage.accounts Gerenciar Accounts do Gerenciador de tags do Google.

Para solicitar acesso usando o OAuth 2.0, seu aplicativo precisa de informações do escopo, bem como informações fornecidas pelo Google durante o registro do aplicativo, como o ID e a chave secreta do cliente.

Primeiros passos

Para começar a usar a API Tag Manager, primeiro use a ferramenta de configuração, que fornece orientações para criar um projeto no Console de APIs do Google, ativar a API e criar credenciais.

Para configurar uma nova conta de serviço:

  1. Clique em Criar credenciais > Chave da conta de serviço.
  2. Escolha se você quer fazer o download da chave pública/privada da conta de serviço como um arquivo P12 padrão ou como um arquivo JSON, que pode ser carregado por uma biblioteca cliente da API do Google.

Seu novo par de chave pública/privada é gerado, e o download dele é feito na sua máquina. Essa é a única cópia da chave. Você é responsável por armazená-la com segurança.

Fluxos comuns do OAuth 2.0

As diretrizes a seguir descrevem casos de uso comuns para fluxos específicos do OAuth 2.0:

Servidor da Web

Esse fluxo é bom para o acesso automatizado/off-line/programado do Account do Gerenciador de tags de um usuário.

Por exemplo:
  • Atualização automática de informações do Gerenciador de tags a partir de um servidor.

Cliente

Ideal quando os usuários interagem diretamente com o aplicativo para acessar o Account do Gerenciador de tags do Google em um navegador. Esse fluxo elimina a necessidade de recursos do lado do servidor, mas também torna relatórios automatizados/off-line/programados inviáveis.

Por exemplo:
  • Uma ferramenta de configuração personalizada com base no navegador.

Aplicativos instalados

Para aplicativos distribuídos como um pacote e instalados pelo usuário. Requer que o aplicativo ou usuário tenha acesso a um navegador para concluir o fluxo de autenticação.

Exemplos:
  • Um widget para computador em um PC ou Mac.
  • Um plugin para um sistema de gerenciamento de conteúdo. A vantagem desse fluxo em relação ao fluxo de servidor da Web ou do lado do cliente é que um único projeto do Console de APIs pode ser usado para seu aplicativo. Isso permite uma instalação mais simples para os usuários.

Contas de serviço

Útil para o acesso automatizado/off-line/programado aos dados do seu Account do Gerenciador de tags do Google. Por exemplo, para criar uma ferramenta personalizada para monitorar seu próprio Account do Gerenciador de tags do Google e compartilhá-la com outras pessoas.

Solução de problemas

Se seu access_token tiver espirado ou você usar o escopo errado para determinada chamada de API, um código de status 401 aparecerá na resposta.

Se o usuário autorizado não tiver acesso ao Account ou Container do Gerenciador de tags do Google, um código de status 403 aparecerá na resposta. Verifique se você está autorizado com o usuário correto e tem permissões para acessar o Account ou Container do Gerenciador de tags.

OAuth2 Playground

Com o OAuth 2.0 Playground, você pode percorrer todo o fluxo de autorização por meio de uma interface da Web. A ferramenta também exibe todos os cabeçalhos de solicitação HTTP necessários para fazer uma consulta autorizada. Se você está com dificuldade para conseguir autorização para trabalhar no seu próprio aplicativo, tente usar o OAuth 2.0 Playground. Em seguida, você pode comparar os cabeçalhos e as solicitações HTTP às informações que seu aplicativo enviou. Essa verificação é uma maneira simples de garantir que você está formatando suas solicitações corretamente.

Concessão inválida

Se você receber uma resposta de erro invalid_grant ao tentar usar um token de atualização, o erro foi causado por um ou mais dos itens a seguir:

  1. O relógio do seu servidor não está em sincronia com o NTP.
  2. Você excedeu o limite de tokens de atualização.
    Os aplicativos podem solicitar vários tokens de atualização para acessar um único Account do Gerenciador de tags do Google. Por exemplo, isso é útil em situações em que um usuário quer instalar um aplicativo em várias máquinas e acessar o mesmo Account do Gerenciador de tags do Google. Nesse caso, são necessários dois tokens de atualização, um para cada instalação. Quando o número de tokens de atualização excede o limite, os tokens antigos se tornam inválidos. Se o aplicativo tenta usar um token de atualização inválido, uma resposta de erro invalid_grant é retornada. Cada combinação exclusiva de ID do cliente/conta pode ter até 25 tokens de atualização. Esse limite está sujeito a alteração. Se o aplicativo continuar solicitando tokens de atualização para a mesma combinação de Client-ID/conta, quando o 26º token for emitido, o primeiro se tornará inválido. O 27º token de atualização solicitado invalidará o segundo emitido, e assim por diante.