Este guia descreve como o analytics.js utiliza cookies e como definir a configuração para sites com vários domínios.
Visão geral
Por padrão, a biblioteca analytics.js usa um único cookie chamado _ga
para armazenar um identificador de cliente exclusivo (ID de cliente), que é um número gerado aleatoriamente. Depois que o ID é gerado, ele é armazenado no cookie e incluído em cada hit/solicitação enviado ao Google Analytics. Esse ID depois é usado pelos servidores do Google Analytics para calcular dados do usuário, da sessão e da campanha.
O cookie _ga
é um cookie primário que só pode ser acessado pelo domínio em que o JavaScript é executado. Para determinadas implementações, convém modificar a forma com que o Google Analytics define seus cookies. Este documento mostra como fazer isso.
Implementação
O snippet de JavaScript padrão para analytics.js cria um rastreador usando o método create
:
ga('create', 'UA-XXXX-Y');
Isso cria um novo cookie em que:
- O nome do cookie é
_ga
. - O domínio do cookie é o domínio do website sem o prefixo
www
. - O cookie é definido para expirar em 24 meses (2 anos), e a validade é atualizada toda vez que um hit é enviado.
Definição das configurações padrão de cookie
Para modificar qualquer um desses valores, você transmite um objeto de configuração para o método create
como o último parâmetro. O objeto de configuração é um objeto JavaScript antigo e simples em que cada propriedade é o nome do campo que você deseja substituir. Por exemplo:
ga('create', 'UA-XXXX-Y', { 'cookieName': 'new_cookie_name', 'cookieDomain': 'mynew.domain.com', 'cookieExpires': 60 * 60 * 24 * 28 // Time in seconds. });
Ele altera as configurações padrão do cookie para seus respectivos valores.
Configuração automática do domínio de cookies
ga('create', 'UA-XXXX-Y', 'auto');
A configuração automática do domínio de cookies simplifica as implementações de acompanhamento de vários domínios gravando automaticamente os cookies no domínio de mais alto nível possível quando o parâmetro auto
é usado. Quando usada no domínio www.example.co.uk
, ela tentará gravar cookies na seguinte ordem:
co.uk
example.co.uk
www.example.co.uk
O analytics.js não conseguirá gravar um cookie em co.uk
, mas terá sucesso em example.co.uk
. Como um cookie foi gravado em um domínio de nível superior, www.example.co.uk
será ignorado.
Definição de cookies em localhost
Em alguns casos, convém executar o analytics.js de um servidor da Web executado em localhost
. Para definir os cookies analytics.js, é necessário desativar o domínio padrão do cookie usando:
ga('create', 'UA-XXXX-Y', { 'cookieDomain': 'none' });
De forma mais simples:
ga('create', 'UA-XXXX-Y', 'none');
Vários rastreadores no mesmo domínio
A biblioteca analytics.js define um único cookie com o ID de cliente exclusivo para que todos os rastreadores da página compartilhem esse mesmo cookie. Se você estiver implementando o analytics.js em vários subdomínios ou em subdiretórios diferentes do mesmo domínio:
- Configure todos os rastreadores para definir um cookie no domínio de mais alto nível possível.
- Omita o prefixo
www
e.
(ponto) do domínio.
Então, se você tivesse um site com dois subdomínios: one.example.com
e two.example.com
, configuraria ambos os rastreadores da seguinte forma:
// Configuration for one.example.com ga('create', 'UA-XXXX-Y', {'cookieDomain': 'example.com'});
// Configuration for two.example.com ga('create', 'UA-XXXX-Y', {'cookieDomain': 'example.com'});
Modificação da validade dos cookies
Todas as vezes que um hit/solicitação é enviado para os servidores do Google Analytics, o tempo de validade do cookie é atualizado para ficar definido como o momento atual acrescido do valor do tempo cookieExpires
(em segundos) em direção ao futuro. Por exemplo, a configuração:
ga('create', 'UA-XXXX-Y', { 'cookieExpires': 60 });
Definiria o tempo de validade do cookie como os próximos 60 segundos (1 minuto).
Se você define o tempo cookieExpires
como 0
(zero) segundos, o cookie se transforma em um cookie com base em sessão e expira ao final da sessão atual do navegador:
ga('create', 'UA-XXXX-Y', { 'cookieExpires': 0 });
Como conseguir o ID de cliente
Os desenvolvedores não devem acessar diretamente o cookie que o analytics.js define, pois o formato do cookie pode mudar sem aviso. Isso pode levar a erros de script e dados incorretos. Uma alternativa para os desenvolvedores é usar o comando get
para recuperar o valor clientId
quando necessário. Veja como fazer isso:
ga(function(tracker) { var clientId = tracker.get('clientId'); });
Depois do carregamento da biblioteca analytics.js, a função transmitida para ga
será executada e o parâmetro tracker
conterá uma referência para o objeto de acompanhamento padrão. O objeto de acompanhamento é usado para conseguir o clientId
.
Desativação dos cookies
Por padrão, o analytics.js usa um único cookie para aplicar um identificador de cliente exclusivo em várias páginas. Em alguns casos, convém usar seu próprio mecanismo de armazenamento e enviar dados diretamente para o Google Analytics sem usar cookies.
É possível desativar o analytics.js para que não defina cookies da seguinte forma:
ga('create', 'UA-XXXX-Y', { 'storage': 'none', 'clientId': '35009a79-1a05-49d7-b876-2b884d0f825b' });
Ao desativar o armazenamento de cookies, é necessário fornecer seu próprio parâmetro clientId
, com exceção do caso especial em que você usa parâmetros de vinculação de vários domínios.