Guia do desenvolvedor

Este documento descreve como usar a API de relatórios em tempo real para receber dados do Google Analytics.

Introdução

A API de relatórios em tempo real exibe as atividades que ocorrem na sua propriedade em tempo real. Para acessar os dados em tempo real, você cria uma consulta que especifica uma Vista (perfil) e pelo menos uma métrica. Você também pode fornecer parâmetros de consulta adicionais, como dimensões e filtros, para refinar sua consulta. Essa consulta é enviada para a API de relatórios em tempo real, que retorna os dados na forma de uma tabela.

Se você estiver começando a usar a API, leia a Visão geral da API de relatórios em tempo real para ver uma introdução sobre a API de relatórios em tempo real e os dados que ela fornece.

Pré-requisito

Antes de usar a API de relatórios em tempo real para receber dados do Google Analytics:

  • Leia a página Bibliotecas cliente para ver uma lista completa de bibliotecas cliente específicas de linguagens de programação que funcionam com a API.
  • Leia o Guia de referência para saber como usar somente a API (sem usar um biblioteca cliente) para receber dados do Google Analytics.

Cada biblioteca cliente fornece um único objeto de serviço de análise para acessar todos os dados da API de relatórios em tempo real. Para criar um objeto de serviço:

  1. Registre seu aplicativo no console de APIs do Google.
  2. Autorize o acesso aos dados do Google Analytics.
  3. Crie um objeto de serviço "Analytics".

Se você não tiver concluído essas etapas, pare e leia o Tutorial de introdução da Google Analytics API, que mostra as etapas iniciais da criação de um aplicativo da Google Analytics API. Depois de fazer isso, você saberá como usar a API para receber dados do Google Analytics.

Uso da API de relatórios em tempo real

Para usar a API de relatórios em tempo real, um aplicativo:

  1. Consulta a API de relatórios em tempo real.
  2. Trata a resposta da API.

Consulta à API de relatórios em tempo real

O objeto de serviço de análise fornece um método para criar uma consulta da API de relatórios em tempo real. Para ver detalhes sobre os parâmetros de consulta e os dados disponíveis para a API, leia:

Depois de definir uma consulta, chame o método execute para enviar a consulta para os servidores do Google Analytics.

Tratamento da resposta da API

Se uma consulta para a API de relatórios em tempo real ocorre sem problemas, a API retorna os dados solicitados como parte de um recurso de dados em tempo real. Consulte a referência da API de relatórios em tempo real para detalhes sobre a estrutura e o formato de resposta da API.

Se ocorre algum erro, a API retorna um código de status específico e uma mensagem descrevendo o erro. Todos os aplicativos precisam encontrar e tratar os erros. Consulte Respostas de erro para ver a lista detalhada de erros e repita as recomendações.

Exemplos de códigos

A seção Exemplos na página Dados em tempo real: get fornece códigos de exemplo em várias linguagens de programação para consultar a API de relatórios em tempo real e tratar a resposta da API.

Restrições de consulta

Estas são as restrições das consultas à API em tempo real:

  • Se a métrica rt:activeUsers for incluída em uma consulta com os filtros de dimensão a seguir, somente o operador AND e o tipo de correspondência de igualdade (==) serão compatíveis.
    • rt:goalId
    • rt:eventAction
    • rt:eventCategory
    • rt:eventLabel

    Como a métrica rt:activeUsers recupera somente o número de usuários ativos no site em determinado momento, não use rt:minutesAgo com rt:activeUsers. Ou seja, rt:activeUsers pressupõe que rt:minutesAgo seja 0.

  • Não há suporte para filtros de métrica.
  • Não há suporte para o parâmetro fields.

Gerenciamento de cotas

Conforme descrito em Limites e cotas, existem cotas diárias para a API de relatórios em tempo real que são compartilhadas com outras Google Analytics APIs. Se você pesquisa a API de relatórios em tempo real em intervalos curtos, os limites diários de cotas podem ser atingidos muito rapidamente. Quando isso acontece, as solicitações de outras Google Analytics APIs também param de funcionar até a cota ser atualizada.

Algumas implementações de exemplo que podem atingir a cota muito rapidamente:

  • Você tem vários painéis em tempo real consultando diariamente dados para uma única vista da propriedade (perfil) do Google Analytics em intervalos muito curtos.
  • Você tem uma propriedade com um grande número de usuários e implementou um widget em tempo real. Cada vez que o widget é exibido para um usuário, você consulta o Google Analytics diretamente, em vez de usar um cache.

Para minimizar o uso da cota e gerenciá-la de modo eficiente:

  • Implemente o armazenamento em cache do lado do servidor. Quando vários usuários fazem uma solicitação para os mesmos dados em tempo real, você deve retornar uma resposta em cache em vez de consultar diretamente a API de relatórios em tempo real para cada solicitação. Em seguida, atualize periodicamente o cache com os últimos dados em tempo real em um intervalo de atualização razoável para você não ultrapassar os limites diários.
  • Combine várias consultas especificando dimensões adicionais e analise a resposta do lado do servidor ou do cliente.
  • Aumente o intervalo de solicitação de dados em tempo real.

Exemplo: Cálculo de um intervalo de atualização

Se você pretende fazer solicitações regulares de dados em tempo real, selecione um intervalo de atualização razoável com base no seu uso esperado.

Por exemplo, uma única Vista (perfil) do Google Analytics tem um limite de cota diário de 10.000 solicitações/dia. Em um único dia, se você espera fazer 6.000 consultas para a API de relatórios principais para uma única Vista (perfil), precisará uma cota de 4.000 solicitações restantes para essa Vista (perfil).

Imagine que você decida usar a API de relatórios em tempo real para implementar três painéis em tempo real em execução durante todo o dia para consultar dados em tempo real da mesma Vista (perfil). Cada painel pode fazer cerca de 1.333 consultas/dia (4.000 consultas/três painéis). Um dia tem 86.400 segundos. Portanto, o intervalo de atualização de cada painel precisa ser maior que 65 segundos (86.400/1.333), de modo que o número total de solicitações diárias para a Vista (perfil) fica abaixo do limite diário de 4.000.