Introdução à ga.js (legada)

ga.js é uma biblioteca JavaScript para medir como os usuários interagem com seu site. Esta é uma biblioteca legada. Se você estiver começando a usar o Google Analytics, use a biblioteca de acompanhamento mais recente, a analytics.js.

Guia de início rápido do código de acompanhamento

O snippet do Google Analytics é um pequeno código JavaScript que você cola nas suas páginas. Ele ativa o acompanhamento do Google Analytics inserindo ga.js na página. Para usar esse recurso nas suas páginas, copie o snippet de código abaixo, substituindo UA-XXXXX-X pelo ID da propriedade da Web. Cole esse snippet na página de modelo do seu site para que ele apareça antes da tag de fechamento </head>.

Se você precisar fazer mais do que o acompanhamento básico de páginas, consulte a referência de acompanhamento para uma lista dos métodos disponíveis na API e o Guia de uso para detalhes sobre como usar a sintaxe assíncrona. Para instruções detalhadas sobre como configurar o acompanhamento, consulte o artigo da Central de Ajuda sobre como configurar o acompanhamento.

<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-XXXXX-X']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>

O snippet acima representa a configuração mínima necessária para acompanhar uma página de forma assíncrona. Ele usa _setAccount para definir o ID da propriedade da Web da página e, em seguida, chama _trackPageview para enviar os dados de acompanhamento de volta aos servidores do Google Analytics.

Importante:se você estiver atualizando suas páginas do snippet tradicional para a versão assíncrona mais recente, remova o snippet de acompanhamento existente primeiro. Não recomendamos usar os dois snippets na mesma página. Para instruções de migração, consulte Como migrar para o plano assíncrono.

Como funciona a sintaxe assíncrona

O objeto _gaq é o que torna a sintaxe assíncrona possível. Ele age como uma fila, que é uma estrutura de dados primeiro a entrar,primeiro a sair que coleta chamadas de API até que ga.js esteja pronto para executá-las. Para adicionar algo à fila, use o método _gaq.push.

Para enviar uma chamada de API para a fila, você precisa convertê-la da sintaxe JavaScript tradicional em uma matriz de comandos. As matrizes de comando são simplesmente matrizes JavaScript que seguem um determinado formato. O primeiro elemento em uma matriz de comandos é o nome do método do objeto do rastreador que você quer chamar. Ele deve ser uma string. Os outros elementos são os argumentos que você quer transmitir para o método do objeto de acompanhamento. Eles podem ser qualquer valor JavaScript.

O código abaixo chama _trackPageview() usando a sintaxe tradicional:

var pageTracker = _gat._getTracker('UA-XXXXX-X');
pageTracker._trackPageview();

O código equivalente na sintaxe assíncrona requer duas chamadas para _gaq.push.

_gaq.push(['_setAccount', 'UA-XXXXX-X']);
_gaq.push(['_trackPageview']);

Na sintaxe assíncrona, a criação do objeto de acompanhamento é implícita, mas ainda é necessário definir o ID da propriedade da Web do rastreador. O método _setAccount foi adicionado para fornecer esse recurso. Todos os outros métodos de objeto de acompanhamento são iguais nos dois tipos de acompanhamento. Somente a sintaxe é diferente.

Para mais informações sobre a sintaxe assíncrona, consulte a Referência de acompanhamento do método _gaq.push.

Voltar ao início

Acompanhamento com manipuladores de eventos HTML

A sintaxe de acompanhamento assíncrona também deve ser usada dentro de manipuladores de eventos DOM. Por exemplo, o botão a seguir gera um evento quando é clicado.

<button onclick="_gaq.push(['_trackEvent', 'button3', 'clicked'])"></button>

Mesmo que você clique nesse botão antes de o navegador terminar de carregar ga.js, o evento será capturado e executado. Com o acompanhamento tradicional, o navegador pode gerar uma exceção nessa situação.

Voltar ao início

Como enviar funções para a fila

Além das matrizes de comandos, também é possível enviar objetos de função para a fila _gaq. As funções podem conter qualquer JavaScript arbitrário e, assim como as matrizes de comandos, elas são executadas na ordem em que são enviadas por push para _gaq. Essa técnica é útil para chamar as APIs de acompanhamento que retornam valores. Por exemplo, o código a seguir cria um URL do vinculador e define a propriedade href de um link com o resultado.

_gaq.push(function() {
  var pageTracker = _gat._getTracker('UA-XXXXX-X');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

O exemplo acima usa _gat para criar um objeto de acompanhamento, mas como ele está atribuído a uma variável local, o código fora da função não pode usá-lo. Embora isso seja aceitável, você pode usar o método _gat._createTracker para criar um objeto permanente e acessível globalmente. O código a seguir demonstra como isso funciona.

_gaq.push(function() {
  var pageTracker = _gat._createTracker('UA-XXXXX-X', 'myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

_gaq.push(['myTracker._trackPageview']);

O exemplo acima cria um rastreador assíncrono dentro da função e faz referência a ele posteriormente por nome na matriz de comandos.

O caso de uso oposto também é possível. Por exemplo, se você precisar usar um objeto de acompanhamento assíncrono criado por meio de uma matriz de comandos enviados anteriormente, use o método _gat._getTrackerByName. O código a seguir demonstra como isso funciona.

_gaq.push(['myTracker._setAccount', 'UA-XXXXX-X']);

_gaq.push(function() {
  var pageTracker = _gat._getTrackerByName('myTracker');
  var link = document.getElementById('my-link-id');
  link.href = pageTracker._getLinkerUrl('http://example.com/');
});

Voltar ao início

Um push, vários comandos

Em vez de digitar _gaq.push(...) para cada chamada, você pode enviar todos os comandos de uma só vez. O código a seguir demonstra essa técnica.

_gaq.push(
  ['_setAccount', 'UA-XXXXX-X'],
  ['_setDomainName', 'example.com'],
  ['_setCustomVar', 1, 'Section', 'Life & Style', 3],
  ['_trackPageview']
);

Isso funciona porque o método _gaq.push imita o método Array.push, que permite enviar vários itens com uma invocação.

Voltar ao início

Como dividir o snippet

Caso prefira colocar o snippet do Google Analytics na parte de baixo da página, não é necessário inserir o snippet inteiro. Você ainda pode manter a maioria das vantagens do carregamento assíncrono dividindo o snippet ao meio. Mantenha a primeira metade na parte de cima da página e mova o restante para a parte de baixo. Como a primeira parte do snippet de acompanhamento tem pouco ou nenhum efeito na renderização da página, você pode deixar essa parte no topo e colocar a parte do snippet que insere ga.js na parte inferior.

Uma página com o snippet assíncrono dividido ao meio pode ter esta aparência:

<html>

<head>
  <script type="text/javascript">
    var _gaq = _gaq || [];
    _gaq.push(['_setAccount', 'UA-XXXXX-X']);
    _gaq.push(['_trackPageview']);
  </script>
</head>

<body>
  <p>Page Content</p>

  <script src="some_random_script.js"></script>

  <p>Page Content</p>

  <script type="text/javascript">  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
  ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script> </body> </html>

As duas partes do código precisam ser incluídas nas suas próprias tags de script, mas somente as seis últimas linhas do snippet assíncrono original precisam ser movidas para o final. Todas as linhas que enviam métodos por push para _gaq podem permanecer na parte superior.

Voltar ao início

Como evitar as armadilhas comuns

Quando usar a sintaxe assíncrona ou tradicional, lembre-se dos seguintes pontos:

  • Os nomes de métodos diferenciam maiúsculas de minúsculas.
    Se você usar um nome de método sem a capitalização correta, as chamadas do método não funcionarão. Exemplos:
    _gaq.push(['_trackpageview']);   // bad
    _gaq.push(['_trackPageview']);   // good
  • Use os nomes de métodos corretos.
    Se o acompanhamento não estiver funcionando corretamente, verifique se você está usando o nome correto do método. Exemplos:
    _gaq.push(['_setDomain', 'example.com']);       // bad
    _gaq.push(['_setDomainName', 'example.com']);   // good
    
  • Somente strings devem ser passadas entre aspas. Todos os outros tipos devem ser deixados se m aspas.
    Qualquer valor que não seja uma string, como booleanos, literais de objeto, funções ou matrizes, precisam ser transmitidos sem aspas. Use aspas apenas quando estiver passando algo que deva ser interpretado como uma string. Se você estiver migrando da sintaxe tradicional, qualquer parâmetro de função que tenha sido passado sem aspas deverá permanecer sem aspas na sintaxe assíncrona. Exemplos:
    _gaq.push(['_setAllowLinker', 'false']);    // bad
    _gaq.push(['_setAllowLinker', false]);      // good
    
  • Verifique se as strings não contêm espaços em branco no início ou no fim.
    Exemplos:
    _gaq.push(['_setAccount', ' UA-65432-1']);    // bad
    _gaq.push(['_setAccount', 'UA-65432-1']);     // good
    

Voltar ao início

Desativação do acompanhamento

Em alguns casos, é necessário desativar o código de acompanhamento do Google Analytics em uma página sem remover o snippet de código. Por exemplo, você pode fazer isso se a Política de Privacidade do seu site permite que um visitante desative o acompanhamento do Google Analytics.

O snippet de acompanhamento ga.js agora inclui uma propriedade de janela que, quando definida como true, desativa o envio de dados pelo snippet ao Google Analytics. Quando o Google Analytics tenta definir um cookie ou enviar dados de volta para os servidores, ele verifica se essa propriedade está definida como true. Se estiver, o efeito será o mesmo que se o visitante tivesse instalado o Plug-in do navegador para desativação do Google Analytics.

Para desativar o acompanhamento, defina a seguinte propriedade de janela como verdadeira:

window['ga-disable-UA-XXXXXX-Y'] = true;

O valor UA-XXXXXX-Y corresponde ao ID da propriedade da Web em que você quer desativar o acompanhamento.

Essa propriedade de janela precisa ser definida antes que o código de acompanhamento seja chamado. É necessário defini-la em cada página em que você quer desativar o acompanhamento do Google Analytics. Se ela não for definida ou tiver o valor "false", o acompanhamento funcionará normalmente.

Por exemplo, se o código de acompanhamento do Google Analytics em uma página incluir:

_gaq.push['_setAccount', 'UA-123456-1']

Se você quiser desativar a configuração de cookies ou o envio de dados por esse código ao Google Analytics, use o código a seguir antes de chamar o código:

window['ga-disable-UA-123456-1'] = true;

Se você usar vários rastreadores em uma página com diversos IDs de propriedade da Web, será necessário definir a variável window['ga-disable-UA-XXXXXX-Y'] equivalente como true para cada propriedade da Web a fim de desativar completamente o acompanhamento do Google Analytics na página em questão.

Exemplo

Confira um exemplo simples de um código que pode ser usado 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 ga.js. Substitua o valor de gaProperty de UA-XXXX-Y pela propriedade usada no seu site. Esse é o mesmo valor que você passa para o comando _setAccount.

<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 período no futuro e desativa a coleta de dados da analytics.js. Quando um 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 da analytics.js também será desativada.

Forçar o uso de SSL (HTTPS)

Para forçar o Google Analytics a sempre enviar dados usando SSL, mesmo de páginas não seguras (HTTP), use o método _gat._forceSSL, como neste exemplo:

_gaq.push(['_setAccount', 'UA-12345-1']);
_gaq.push(['_gat._forceSSL']);       // Send all hits using SSL, even from insecure (HTTP) pages.
_gaq.push(['_trackPageview']);

Voltar ao início