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.
Como definir configurações de campos de cookies
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');
Configuração automática do domínio de cookies
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.
Validade do cookie
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:
Atualização de cookies
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.
Sinalizações de cookies
Quando definidas, anexam sinalizações adicionais ao cookie. Elas devem ser separadas por ponto e vírgula.
Acesso ao Client-ID usando o cookie
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:
- 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.
- Defina o User-ID no rastreador:
ga('create', 'UA-XXXXX-Y', 'auto', { userId: USER_ID }); ga('send', 'pageview');
Gerenciar a autenticação depois do carregamento da 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.