Cookies e identificação do usuário

Para que o Google Analytics determine que dois hits diferentes pertencem ao mesmo usuário, é necessário enviar um identificador exclusivo associado a esse usuário específico com cada hit.

A biblioteca analytics.js faz isso usando o campo Client-ID, uma string exclusiva gerada aleatoriamente que é armazenada nos cookies dos navegadores. Desse modo, as próximas visitas ao mesmo site podem ser associadas ao mesmo usuário.

Por padrão, a analytics.js usa um único cookie primário chamado _ga para armazenar o Client-ID, mas é possível personalizar o nome, o domínio e o prazo de validade. Os outros cookies criados pela analytics.js incluem _gid, AMP_TOKEN e _gac_<property-id>. Eles armazenam outros IDs gerados aleatoriamente e as informações da campanha do usuário.

O uso de cookies permite que a analytics.js identifique usuários únicos em sessões de navegação diferentes, mas não em navegadores ou dispositivos distintos. Se o seu site tem um sistema próprio de autenticação, você pode usar o recurso User ID, além do Client-ID, para identificar com mais precisão um usuário em todos os dispositivos que ele utiliza para acessar o site.

Este guia explica como personalizar as configurações de cookies e definir o campo "User ID" para medir de forma mais precisa a atividade do usuário em sessões diferentes.

A tabela a seguir mostra os valores padrão de campos de cookies usados pelo analytics.js:

Nome do campo Tipo de valor Valor padrão
cookieName texto _ga
cookieDomain texto O resultado da seguinte expressão JavaScript:
document.location.hostname
cookieExpires número inteiro 63072000 (dois anos, em segundos)
cookieUpdate booleano true
cookieFlags texto

Para modificar qualquer um desses valores, especifique-os no fieldObject em que você envia o comando create. Por exemplo:

ga('create', 'UA-XXXXX-Y', {
  'cookieName': 'gaCookie',
  'cookieDomain': 'blog.example.co.uk',
  'cookieExpires': 60 * 60 * 24 * 28  // Time in seconds.
  'cookieUpdate': 'false',
  'cookieFlags': 'SameSite=None; Secure',
});

O campo de cookie mais comum a ser definido é o cookieDomain. Sendo assim, o comando create aceita o cookieDomain como um terceiro parâmetro opcional:

ga('create', 'UA-XXXXX-Y', 'blog.example.co.uk');

A tag do Google Analytics recomendada define a string 'auto' para o campo cookieDomain:

ga('create', 'UA-XXXXX-Y', 'auto');

Especificar 'auto' como cookieDomain ativa a configuração automática do domínio de cookies, que faz a analytics.js determinar automaticamente o melhor domínio a ser usado.

A configuração automática define o cookie _ga no domínio de nível mais alto possível. Por exemplo, se o endereço do site for blog.example.co.uk, a analytics.js definirá o domínio de cookies como .example.co.uk. Além disso, se a biblioteca detectar que você está executando um servidor localmente (por exemplo, localhost), o cookieDomain será especificado como 'none' de forma automática.

Sempre que um hit é enviado ao Google Analytics, o prazo de validade do cookie é atualizado para a hora atual mais o valor do campo cookieExpires. Isso significa que se você usar o tempo padrão de cookieExpires de dois anos e um usuário acessar seu site todos os meses, o cookie dele nunca vai expirar.

Se você definir o tempo de cookieExpires como 0 (zero) segundo, o cookie será com base na sessão e vai expirar quando a sessão atual do navegador terminar:

Quando cookieUpdate for definido como true (o valor padrão), a analytics.js atualizará os cookies em cada carregamento de página. Dessa forma, a validade é definida em relação à visita mais recente ao site. Por exemplo, se o cookie expirar em uma semana e o usuário acessar a página com o mesmo navegador a cada cinco dias, a validade será atualizada em cada visita e, portanto, nunca vai expirar.

Quando for definido como false, os cookies não serão atualizados em cada carregamento de página. Dessa forma, a expiração terá como base a primeira visita do usuário.

Quando definidas, anexam sinalizações adicionais ao cookie. Elas devem ser separadas por ponto e vírgula.

Não acesse diretamente o cookie definido pela analytics.js, porque o formato dele pode mudar no futuro. Em vez disso, é recomendável que os desenvolvedores usem readyCallback para aguardar o carregamento da analytics.js e depois recebam o valor do clientId armazenado no rastreador.

ga(function(tracker) {
  var clientId = tracker.get('clientId');
});

Desativação dos cookies

Em alguns casos, convém usar seu próprio mecanismo de armazenamento, como localStorage ou service worker, para manter o Client-ID entre sessões diferentes sem usar cookies. Você pode desativar a configuração de cookies pela analytics.js definindo o campo storage como 'none'.

ga('create', 'UA-XXXXX-Y', {
  'storage': 'none'
});

Se você armazenar o campo clientId, será necessário definir o cliendId ao criar o rastreador.

ga('create', 'UA-XXXXX-Y', {
  'storage': 'none',
  'clientId': '76c24efd-ec42-492a-92df-c62cfd4540a3'
});

Para desativar os cookies _gac_<property-id>, defina o campo storeGac como false no comando create:

ga('create', 'UA-XXXXX-Y', {
  storeGac: false,
});

Uso de localStorage para armazenar o Client-ID

Veja no exemplo de código a seguir como modificar a tag JavaScript com o objetivo de usar o localStorage para armazenar o Client-ID em vez dos cookies:

var GA_LOCAL_STORAGE_KEY = 'ga:clientId';

if (window.localStorage) {
  ga('create', 'UA-XXXXX-Y', {
    'storage': 'none',
    'clientId': localStorage.getItem(GA_LOCAL_STORAGE_KEY)
  });
  ga(function(tracker) {
    localStorage.setItem(GA_LOCAL_STORAGE_KEY, tracker.get('clientId'));
  });
}
else {
  ga('create', 'UA-XXXXX-Y', 'auto');
}

ga('send', 'pageview');

User ID

O User ID permite a análise de grupos de sessões em vários dispositivos usando um ID de string exclusivo, persistente e sem identificação pessoal que representa um usuário. Para saber por que você deve implementar o User-ID, consulte o artigo Vantagens de utilizar o recurso User-ID.

Para implementar o User ID com a analytics.js, faça o seguinte:

  1. Informe seu próprio ID de string exclusivo, persistente e sem identificação pessoal que represente cada usuário conectado. Esse ID geralmente é fornecido por um sistema de autenticação.
  2. Defina o User ID no rastreador:
ga('create', 'UA-XXXXX-Y', 'auto', {
  userId: USER_ID
});
ga('send', 'pageview');

Como realizar a autenticação depois do carregamento de página

Quando você cria aplicativos de página única ou outros sites dinâmicos que fazem o login do usuário depois do carregamento inicial da página, o processo de configuração do valor do User ID no rastreador não pode ocorrer no momento da criação.

Nesses casos, você pode usar o comando set para definir o valor no rastreador assim que for conhecido.

// Creates the tracker and sends a pageview as normal
// since the `userId` value is not yet known.
ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');

// At a later time, once the `userId` value is known,
// sets the value on the tracker.
ga('set', 'userId', USER_ID);

// Setting the userId doesn't send data to Google Analytics.
// You must also use a pageview or event to send the data.
ga('send', 'event', 'authentication', 'user-id available');

Quando você usa essa abordagem, os hits enviados antes da definição do campo userId não contêm valores do User ID. No entanto, usando um processo chamado unificação de sessão, o Google Analytics associa esses hits ao usuário correto durante o processamento.