Domains & Cookies - Web Tracking (analytics.js)

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.

Observação: o cookieDomain precisa ser um predecessor do domínio atual. Caso contrário, o cookie não será definido. Por exemplo, se seu domínio é one.two.three.root.com, você pode configurar o cookie para ser definido em root.com, mas não em someotherdomain.com. Se um domínio de cookie incorreto é definido, nenhum hit é enviado para o Google Analytics.

Observação: por padrão, o caminho do cookie é definido como /. Embora essa configuração possa ser modificada com o parâmetro de configuração cookiePath, isso não é recomendado. O ideal é que haja um único cookie _ga definido para um determinado domínio.

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.