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 pós-solicitação. O corpo precisa incluir exatamente 1 payload codificado de URI e não pode ter mais de 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 Measurement Protocol 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 Measurement Protocol 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 tente fazer a solicitação novamente. Em vez disso, interrompa e corrija todos os erros na 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, é separado por um caractere =
e cada par é delimitado por um caractere &
.
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 . |
ID de acompanhamento | 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 rastrear o usuário 5555
que acessou /pageA
, /pageB
e /pageC
, envie estes três payloads:
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
O /
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ê terá que confirmar se ela está codificada em UTF-8 e em url, resultando 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.
Tipo de dados compatíveis
Cada campo de dados no Measurement Protocol pertence a um tipo específico, cada um com as próprias 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. Exemplo:
Hello World
se tornará:
Hello World
Currency
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). Então:
$-55.00
se tornará:
-55.00
Booleano
Usado para determinar se um valor é verdadeiro ou falso. Os valores válidos são:
1
: verdadeiro0
: 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.