Este documento contém uma visão geral da biblioteca de coleções analytics.js.
O snippet JavaScript
Para ativar o Google Analytics no seu site, adicione um trecho de JavaScript antes da tag de fechamento </head> da página. Veja uma parte do snippet:
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
Quando o snippet é executado, primeiro ele cria uma nova função global chamada de ga.
Em seguida, ele carrega de forma assíncrona a biblioteca analytics.js na página.
A função global ga é a principal maneira de você interagir com a biblioteca analytics.js. A função aceita uma sequência de parâmetros, na qual o primeiro parâmetro representa um comando do Google Analytics. Por exemplo, no snippet padrão:
ga('create', 'UA-XXXX-Y', 'auto'); // Creates a tracker.
ga('send', 'pageview'); // Sends a pageview.
A primeira linha chama o comando create e a segunda linha chama o comando send.
Mesmo que o JavaScript carregue a biblioteca analytics.js de forma assíncrona, a função ga é projetada para ser usada antes do carregamento da biblioteca. Quando você começa a executar comandos, cada comando é adicionado a uma fila. Depois que o carregamento da biblioteca é concluído, todos os comandos na fila são executados, e novos comandos são executados imediatamente. Isso permite que os desenvolvedores ignorem a natureza assíncrona do Google Analytics e se concentrem em usar a função ga.
Renomear o objeto global
Em alguns casos, talvez o nome de variável ga já seja usado por um objeto existente na sua página. Para evitar a substituição do seu objeto existente, você pode renomear a função ga, por exemplo, para __gaTracker.
Para fazer isso, basta substituir o parâmetro ga no snippet acima:
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','__gaTracker');
Em seguida, você pode usar __gaTracker em vez de ga ao chamar os comandos:
__gaTracker('create', 'UA-XXXX-Y', 'auto');
__gaTracker('send', 'pageview');
Referência do snippet JavaScript
A referência a seguir mostra o snippet básico de JavaScript com comentários e espaços em branco incluídos:
<!-- Google Analytics -->
<script>
/**
* Creates a temporary global ga object and loads analy tics.js.
* Paramenters o, a, and m are all used internally. They could have been declared using 'var',
* instead they are declared as parameters to save 4 bytes ('var ').
*
* @param {Window} i The global context object.
* @param {Document} s The DOM document object.
* @param {string} o Must be 'script'.
* @param {string} g URL of the analytics.js script. Inherits protocol from page.
* @param {string} r Global name of analytics object. Defaults to 'ga'.
* @param {DOMElement?} a Async script tag.
* @param {DOMElement?} m First script tag in document.
*/
(function(i, s, o, g, r, a, m){
i['GoogleAnalyticsObject'] = r; // Acts as a pointer to support renaming.
// Creates an initial ga() function. The queued commands will be executed once analytics.js loads.
i[r] = i[r] || function() {
(i[r].q = i[r].q || []).push(arguments)
},
// Sets the time (as an integer) this tag was executed. Used for timing hits.
i[r].l = 1 * new Date();
// Insert the script tag asynchronously. Inserts above current tag to prevent blocking in
// addition to using the async attribute.
a = s.createElement(o),
m = s.getElementsByTagName(o)[0];
a.async = 1;
a.src = g;
m.parentNode.insertBefore(a, m)
})(window, document, 'script', '//www.google-analytics.com/analytics.js', 'ga');
ga('create', 'UA-XXXX-Y', 'auto'); // Creates the tracker with default parameters.
ga('send', 'pageview'); // Sends a pageview hit.
</script>
<!-- End Google Analytics -->
Snippet assíncrono alternativo
Embora o snippet canônico analytics.js acima garanta que o script será carregado e executado de forma assíncrona em todos os navegadores, ele tem a desvantagem de não permitir que navegadores modernos pré-carreguem o script.
O snippet alternativo abaixo adiciona suporte para o pré-carregamento, o que fornece um pequeno aumento de desempenho em navegadores modernos, mas pode prejudicar o carregamento síncrono e a execução no IE 9 e versões mais antigas de navegadores para dispositivos móveis que não reconhecem o atributo async. Sugerimos que você use esse snippet se seus visitantes usam principalmente navegadores modernos para acessar seu site.
<!-- Google Analytics -->
<script async src='//www.google-analytics.com/analytics.js'></script>
<script>
window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;
ga('create', 'UA-XXXX-Y', 'auto');
ga('send', 'pageview');
</script>
<!-- End Google Analytics -->
Criação de objetos de acompanhamento
Para enviar dados ao Google Analytics, você precisa criar um objeto de acompanhamento. Cada objeto de acompanhamento pode enviar dados para uma única propriedade da Web do Google Analytics. Para criar um objeto de acompanhamento, o snippet padrão usa este código:
ga('create', 'UA-XXXX-Y', 'auto');
Em que o primeiro parâmetro para a função ga é o comando create, e o segundo parâmetro é o ID da propriedade da Web para o qual enviar dados.
Personalização de objetos de acompanhamento
Toda personalização de objetos de acompanhamento precisa ser realizada quando o objeto é criado, passando um objeto de configuração para a função ga como o último parâmetro. Por exemplo, para substituir algumas das configurações de cookie, você usaria:
ga('create', 'UA-12345-6', {
'cookieDomain': 'foo.example.com',
'cookieName': 'myNewName',
'cookieExpires': 20000
});
No exemplo acima, o domínio, nome e horário de expiração do cookie foram modificados por meio do objeto de configuração opcional.
Leia a seção "Apenas create" no documento "Referência de campos" para detalhes completos sobre todos os campos que podem ser configurados no comando "create".
Como fazer testes em localhost
Em alguns casos, convém testar o snippet analytics.js a partir 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'
});
Envio de dados
Depois que um objeto de acompanhamento é criado e associado com uma propriedade da Web, você pode usar o comando send para enviar dados para essa propriedade da Web.
Os dados enviados ao Google Analytics são chamados de Hit, e a biblioteca do analytics.js permite que você envie vários tipos de dados especificando um hitType. Ao usar o comando send, também é necessário especificar o hitType dos dados que você deseja enviar.
Por exemplo, para enviar um hit "pageview", você usa:
ga('send', 'pageview');
Isso envia dados do URL padrão ao Google Analytics.
Objeto de nome de campo
Em alguns casos, convém substituir vários valores que são enviados como uma exibição de página. Com a biblioteca analytics.js, é possível passar um objeto de nome de campo como o último parâmetro no comando send. Essa função é útil, pois permite definir várias propriedades adicionais da exibição de página como, por exemplo, o título da página:
ga('send', 'pageview', {
'page': '/my-new-page',
'title': 'My New Page Title'
});
Leia o documento Referência de campos para detalhes completos sobre todas as maneiras como um objeto de acompanhamento pode ser configurado.
Definição do retorno de hit
Em alguns casos, como quando você acompanha links de saída, convém saber quando o rastreador terminar de enviar dados. Dessa forma, você pode enviar um usuário ao seu destino somente depois de o clique ter sido informado ao Google Analytics. Para resolver essa questão, o comando send permite especificar uma função hitCallback no objeto de nome de campo que será executado assim que o analytics.js concluir o envio de dados.
Veja como definir a função hitCallback:
ga('send', 'pageview', {
'page': '/my-new-page',
'hitCallback': function() {
alert('analytics.js done sending data');
}
});
Nesse exemplo, o objeto de nome de campo configura o parâmetro page e define o parâmetro hitCallback.
Depois que o rastreador conclui o envio de dados, uma caixa de alerta é exibida para o usuário.
Definição de parâmetros em vários comandos "send"
Em alguns casos, convém definir um parâmetro de modo que o valor persista em vários comandos send. Por exemplo, se você tem uma página da Web em que você deseja acompanhar uma exibição de página e dois eventos. Se você desejar substituir o caminho da página de cada hit pelo seu próprio caminho personalizado, pode definir o novo caminho em cada comando send ou usar o método set desta forma:
ga('set', 'page', '/my-custom-page');
ga('send', 'pageview');
ga('send', 'event', 'image1', 'clicked');
ga('send', 'event', 'image2', 'clicked');
Quando o seguinte código for executado, a página substituída /my-custom-page será enviada para os três comandos "send".
Envio de hits com useBeacon
Para enviar hits por meio do navigator.sendBeacon, defina o parâmetro useBeacon como true.
O método navigator.sendBeacon garante que os dados sejam transmitidos, mesmo que o usuário navegue para fora da sua página ou feche o navegador antes da conclusão da solicitação. Isso é especialmente útil quando você deseja acompanhar um evento logo antes de um usuário sair do seu site, sem atrasar a navegação.
ga('send', 'event', 'click', 'download-me', {useBeacon: true});
Envio de funções por push
Às vezes, convém executar um código apenas depois que a biblioteca analytics.js tiver sido carregada.
Para isso, passe uma função como um parâmetro para a função ga.
ga(function() {
alert('library done loading');
});
Depois que o carregamento da biblioteca estiver concluído, o usuário verá uma caixa de alerta.
Visualização de parâmetros
Com o analytics.js, você pode recuperar qualquer valor definido no objeto de acompanhamento usando o comando get. Como o objeto de acompanhamento só é criado depois que a biblioteca é carregada, é necessário conseguir os parâmetros em uma função enviada por push.
ga(function(tracker) {
var defaultPage = tracker.get('page');
});
Nesse exemplo, a função utiliza um parâmetro chamado tracker.
Depois que o carregamento da biblioteca é concluído, a função será executada e o valor de tracker será o objeto de acompanhamento padrão que foi criado como resultado do primeiro comando create. O tracker, então, é usado para conseguir o valor de página padrão.
Forçar o uso de SSL (HTTPS)
"Por padrão, o Google Analytics faz a correspondência do protocolo da página de host ao enviar solicitações de saída. Para forçar o Google Analytics a sempre enviar dados usando SSL, mesmo a partir de páginas não seguras (HTTP), defina o campo forceSSL como true:
ga('create', 'UA-XXXX-Y', 'auto');
ga('set', 'forceSSL', true); // Send all data using SSL, even from insecure (HTTP) pages.
ga('send', 'pageview');
Uso de vários objetos de acompanhamento
Em alguns casos, convém enviar dados para várias propriedades da Web a partir de uma única página. Isso é útil para sites cujas seções são supervisionadas por vários proprietários. Cada proprietário poderia visualizar sua propriedade da Web específica.
Para resolver essa questão, crie um objeto de acompanhamento para cada propriedade da Web para a qual você deseja enviar dados:
ga('create', 'UA-XXXX-Y', 'auto');
ga('create', 'UA-12345-6', 'auto', {'name': 'newTracker'}); // New tracker.
Depois da execução do comando, dois objetos de acompanhamento são criados. O primeiro rastreador é o objeto de acompanhamento padrão e não tem um nome. O segundo é chamado de newTracker.
Para enviar uma exibição de página usando ambos os rastreadores, insira o nome dele no início do comando, seguido por um ponto. Por exemplo:
ga('send', 'pageview');
ga('newTracker.send', 'pageview'); // Send page view for new tracker.
Esse comando enviaria uma exibição de página aos rastreadores padrão e novo.
Para acessar um objeto de acompanhamento pelo nome em uma função, use o método getByName:
ga(function() {
var newTracker = ga.getByName('newTracker');
});
Para ter uma matriz de todos os rastreadores que foram configurados, use o método getAll:
ga(function() {
var allTrackers = ga.getAll();
});
Atribuição melhorada de link
A Atribuição melhorada de link melhora a precisão do seu relatório de Análise de Página. Para isso, diferencia automaticamente vinculação múltipla para o mesmo URL em uma única página, por meio de códigos de elementos do link.
Para ativar a Atribuição melhorada de link:
- Ative a Atribuição melhorada de link na interface do usuário do administrador da sua conta do Google Analytics.
- Atualize seu código em cada página para carregar o plug-in da Atribuição melhorada de link, como neste exemplo:
ga('create', 'UA-XXXX-Y', 'auto');
ga('require', 'linkid'); // Load the plug-in. Note: this call will block until the plug-in is loaded.
ga('send', 'pageview');
Personalização da Atribuição melhorada de link
O plug-in da Atribuição melhorada de link diferencia links para o mesmo URL usando os códigos de elementos de um link ou elemento pai, além de um cookie. Você pode personalizar até que nível do DOM (modelo de objeto de documento) o plug-in deve procurar um ID de elemento, bem como o comportamento desse cookie, fornecendo opções de configuração ao carregar o plug-in:
ga('create', 'UA-XXXX-Y', 'auto');
ga('require', 'linkid', {
'cookieName': '_ela', // Cookie name. _gali by default.
'duration': 45, // Cookie duration. 30 seconds by default.
'levels': 5}); // Max DOM levels from link to look for element ID. 3 by default.
ga('send', 'pageview');
Anonimização de IP
Em alguns casos, pode ser necessário anonimizar o endereço IP do hit (solicitação http) enviado para o Google Analytics. É possível anonimizar os endereços IP para todos os hits enviados a partir de uma página (a vida útil do objeto de acompanhamento) usando o comando set e definindo o campo anonymizeIp como true:
ga('set', 'anonymizeIp', true);
Para anonimizar o endereço IP de um hit individual, defina o campo anonymizeIp no objeto de configuração opcional desse hit:
ga('send', 'pageview', {
'anonymizeIp': true
});
Para saber mais sobre como a anonimização de IP funciona, leia o artigo Anonimização de IP no Google Analytics na Central de Ajuda.
Desativação de usuário
Em alguns casos, pode ser necessário desativar o código de acompanhamento do Google Analytics em uma página sem precisar remover o snippet de código JavaScript. Por exemplo, você pode fazer isso se a política de privacidade do seu site permite que o usuário desative o acompanhamento do Google Analytics.
A biblioteca do analytics.js agora inclui uma propriedade de janela que, quando definida como true, desativa o envio de dados do analytics.js para o Google Analytics.
Quando o Google Analytics tenta definir um cookie ou enviar dados de volta para seus próprios servidores, ele verifica se essa propriedade está definida como true. Se estiver, o efeito será o mesmo que se o usuário tivesse instalado o Plug-in do navegador para desativação do Google Analytics.
Para desativar o acompanhamento, defina a seguinte propriedade de janela como true:
window['ga-disable-UA-XXXX-Y'] = true;
Em que o valor UA-XXXX-Y corresponde ao ID da propriedade da Web em que você deseja desativar o acompanhamento.
Essa propriedade de janela precisa ser definida antes de o código de acompanhamento ser chamado. É necessário defini-la em cada página em que você deseja desativar o acompanhamento do Google Analytics. Se a propriedade não estiver definida ou estiver definida como "false", o acompanhamento funcionará conforme de costume.
Exemplo
Veja um exemplo simples de um código que você pode usar para oferecer a funcionalidade de desativação para seus usuários.
Primeiro, adicione um novo link HTML ao seu site para executar a lógica de desativação:
<a href="javascript:gaOptout()">Click here to opt-out of Google Analytics</a>
Em seguida, adicione o seguinte snippet de código antes do snippet de código analytics.js. Altere o valor UA-XXXX-Y de gaProperty para a propriedade usada no seu site.
É o mesmo valor que você passa para o comando create.
<script>
// Set to the same value as the web property used on the site
var gaProperty = 'UA-XXXX-Y';
// Disable tracking if the opt-out cookie exists.
var disableStr = 'ga-disable-' + gaProperty;
if (document.cookie.indexOf(disableStr + '=true') > -1) {
window[disableStr] = true;
}
// Opt-out function
function gaOptout() {
document.cookie = disableStr + '=true; expires=Thu, 31 Dec 2099 23:59:59 UTC; path=/';
window[disableStr] = true;
}
</script>
Quando um usuário clica no link HTML de desativação, a função gaOptout personalizada é executada. Ela define um cookie por um longo tempo e desativa a coleta de dados do analytics.js.
Quando o usuário retorna a esse site, o script acima verifica se o cookie de desativação foi definido. Em caso afirmativo, a coleta de dados do analytics.js também é desativada.
Depuração
Você pode ativar a versão de depuração do analytics.js usando analytics_debug.js:
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics_debug.js','ga');
ga('create', 'UA-XXXX-Y', 'auto');
ga('send', 'pageview');
Ele só deve ser usado temporariamente ou durante o desenvolvimento, pois analytics_debug.js é maior e atrasa os hits para google-analytics.com.
Depuração de rastreio
A depuração de rastreio gera mais informações detalhadas sobre o console. Para ativar a depuração de rastreamento, use https://www.google-analytics.com/analytics_debug.js e a linha de código abaixo antes do snippet.
window.ga_debug = {trace: true};