Referência de Protocolo de avaliação

Este documento descreve como enviar dados ao Google Analytics por meio do Protocolo de avaliação.

Visão geral

Há duas partes no envio de dados ao Google Analytics por meio do Protocolo de avaliação:

  • O transporte: para onde e como você envia os dados
  • O payload: os dados que você envia

Este documento descreve como formatar as duas partes.

Transporte

Ponto de extremidade do URL

Você envia dados por meio do Protocolo de avaliação fazendo solicitações HTTP para o seguinte ponto de extremidade:

https://www.google-analytics.com/collect

Todos os dados devem ser enviados de forma segura com o protocolo HTTPS.

Você pode enviar dados por meio de solicitações POST ou GET.

Como usar o POST

Recomendamos enviar dados por POST porque ele permite um payload maior. Ao usar POST, emita a seguinte solicitação HTTP:

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

Em que:

  • user_agent_string: é uma string de user agent formatada usada para registrar estas dimensões: navegador, plataforma e recursos para dispositivos móveis.

    Se esse valor não for definido, os dados acima não serão registrados.

  • payload_data: o BODY da solicitação post. O corpo precisa incluir exatamente 1 payload codificad pelo URI e não pode ter mais que 8.192 bytes.
  • Endereço IP: é enviado implicitamente na solicitação HTTP e é usado para computar todas as dimensões geográficas / de rede no Google Analytics.

GET

Para ambientes em que não é possível enviar dados POST, você também pode enviar solicitações HTTP GET para o mesmo ponto de extremidade:

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

Em que os dados do payload são enviados como parâmetros de consulta escapados para URI. O tamanho do URL codificado todo não pode ser maior que 8000 bytes.

Bloqueio de cache

Em alguns ambientes, como navegadores, solicitações HTTP GET podem ser armazenadas em cache. Quando uma solicitação é armazenada em cache, solicitações subsequentes podem ser recuperadas do cache, e não enviadas ao Google Analytics. Para bloquear o cache, o Protocolo de avaliação fornece um parâmetro especial (z) que pode ser definido com um número aleatório. Isso garante que todas as solicitações do Protocolo de avaliação sejam exclusivas e que as solicitações subsequentes não sejam recuperadas do armazenamento em cache.

Quando você usa o bloqueio de cache, recomendamos adicionar esse parâmetro como o último no payload.

https://www.google-analytics.com/collect?payload_data&z=123456

Códigos de resposta

O Protocolo de avaliação retornará um código de status 2xx se a solicitação HTTP tiver sido recebida. O Protocolo de avaliação não retorna um código de erro se os dados de payload estiverem malformados ou se estiverem incorretos ou não tiverem sido processados do Google Analytics.

Se você não receber um código de status 2xx, NÃO faça uma nova solicitação. Em vez disso, interrompa e corrija todos os erros na sua solicitação HTTP.

Dados de payload

Todos os dados coletados pelo Google Analytics por meio do Protocolo de avaliação são enviados como payload. O payload é semelhante a uma string de consulta de URL, em que cada parâmetro tem uma chave e um valor e é separado por um caractere =, e cada par é delimitado por um caractere &. Por exemplo:

key1=val1&key2=val2

Cada payload possui regras sobre: valores obrigatórios, codificação pelo URI, parâmetros que podem ser enviados juntos e tamanho do parâmetro. Além disso, cada parâmetro tem um tipo específico que exige um determinado formato. As seções a seguir contêm informações sobre essas regras.

Leia a Referência de parâmetros para uma listagem completa de todos os parâmetros que você pode enviar por meio do Protocolo de avaliação.

Valores obrigatórios para todos os hits

Os parâmetros a seguir precisam estar presentes em todo payload:

Nome Parâmetro Exemplo Descrição
Protocol Version v v=1 A versão do protocolo. O valor deve ser 1.
Tracking ID tid tid=UA-123456-1 O ID que distingue a propriedade do Google Analytics que deve receber os dados.
Client ID cid cid=xxxxx Um código exclusivo para um usuário específico.
Hit Type t t=pageview O tipo de interação coletada para um usuário específico.

Os dados de Client ID e Hit Type são valores mapeados diretamente para o modelo de dados do Google Analytics. Se você quiser acompanhar o usuário 5555 que acessou /pageA, /pageB e /pageC, envie estas três cargas úteis:

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

/ foi codificado para %2F.

Valores de codificação do URL

Todos os valores enviados ao Google Analytics precisam ser codificados para UTF-8 e URL. Para enviar a chave dp com o valor /my page €, primeiro você precisa garantir que ele esteja codificado para UTF-8 e para URL, o que resulta na string final:

dp=%2Fmy%20page%20%E2%82%AC

Se algum dos caracteres for codificado incorretamente, ele será substituído pelo caractere de substituição unicode xFFFD.

Valores obrigatórios para determinados tipos de hit

Alguns parâmetros só podem ser enviados com tipos de hit específicos. Por exemplo, o tipo de hit pageview exige que o parâmetro de caminho da página (dp) também seja definido. A Referência de parâmetros descreve quais parâmetros são obrigatórios para cada tipo de hit.

Tamanho máximo

Alguns valores de texto no Protocolo de avaliação possuem tamanhos máximos específicos em bytes. Por exemplo, o campo do referenciador do documento, dr, tem um tamanho máximo de 2.048 bytes. Se algum dos valores for maior que o tamanho máximo, ele será automaticamente truncado. Se um caractere de bytes múltiplos exceder o tamanho máximo, o caractere todo será truncado.

Tipos de dados suportados

Cada campo de dados no Protocolo de avaliação pertence a um tipo específico, cada um com suas regras de validação. Se algum dos valores dos parâmetros não seguir as regras de validação, esse parâmetro específico será ignorado e não será processado pelo Google Analytics. O restante dos parâmetros será processado normalmente.

O Protocolo de avaliação suporta estes tipos de dados:

Campos de dados individuais podem ter suas próprias restrições. Consulte a Referência de campos para uma lista completa de todos os campos de dados e tipos aceitos.

Texto

Usado para representar strings. Um processamento adicional é feito nos campos de texto. Todos os espaços em branco à esquerda e à direita são removidos. Execuções internas com dois ou mais caracteres de espaço em branco (incluindo espaço, tab, novas linhas etc.) são reduzidos a um único caractere de espaço. Essa transformação é aplicada ao texto bruto antes que aconteça qualquer truncagem. Por exemplo:

   Hello      World

se tornará:

Hello World

Moeda

Usado para representar o valor total de uma moeda. Um ponto decimal é usado como delimitador ente o número inteiro e a fração da moeda. A precisão é de até seis casas decimais. O exemplo a seguir é válido para um campo de moeda:

1000.000001

Depois que o valor é enviado para o Google Analytics, todo o texto é removido até o primeiro dígito, o caractere - ou . (decimal). Sendo assim:

$-55.00

se tornará:

-55.00

Booleano

Usado para determinar se um valor é verdadeiro ou falso. Os valores válidos são:

  • 1: verdadeiro
  • 0: falso

Número inteiro

Usado para representar um número inteiro. O valor é armazenado como um int64 assinado.

Número

Usado para representar um número inteiro ou um número de ponto flutuante.