Esta página foi traduzida pela API Cloud Translation.

Introdução à ga.js (legada)

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

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

O snippet do Analytics é um código JavaScript que você cola nas suas páginas. Ele ativa o acompanhamento do Google Analytics inserindo ga.js na página. Para usá-lo nas suas páginas, copie o snippet de código abaixo, substituindo UA-XXXXX-X pelo ID da propriedade da Web. Cole este snippet na página do 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 rastreamento para ver uma lista de métodos disponíveis na API e o Guia de uso para detalhes sobre como usar a sintaxe assíncrona. Para ver instruções passo a passo 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 mais recente e assíncrona, primeiro remova o snippet de acompanhamento existente. Não recomendamos usar ambos os snippets juntos na mesma página. Para instruções de migração, consulte Como migrar para o modo assíncrono.

Como funciona a sintaxe assíncrona

O objeto _gaq é o que torna a sintaxe assíncrona possível. Ele funciona 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, converta-a da sintaxe JavaScript tradicional em uma matriz de comandos. As matrizes de comandos são simplesmente matrizes JavaScript em conformidade com 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 passar para o método de objeto do rastreador. Eles podem ser qualquer valor JavaScript.

O código a seguir 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 precisamos de uma maneira de definir o ID da propriedade da Web para o rastreador. O método _setAccount foi adicionado para oferecer esse recurso. Todos os outros métodos de objeto do rastreador são iguais nos rastreamentos assíncrono e tradicional. Somente a sintaxe é diferente.

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

Voltar ao início

Como rastrear 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 recebe um clique.

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

Mesmo se você clicar nesse botão antes do navegador carregar o ga.js, o evento será capturado e executado. Usando o rastreamento tradicional, o navegador pode lançar 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, como as matrizes de comandos, elas são executadas na ordem em que são enviadas 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 para 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 é 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, em seguida, 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 enviada 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, é possível 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, o que permite enviar vários itens com uma invocação.

Voltar ao início

Como dividir o snippet

Se preferir colocar o snippet do Analytics na parte inferior da página, você não precisará colocar o snippet inteiro na parte inferior. Ainda é possível manter a maioria dos benefícios do carregamento assíncrono dividindo o snippet na metade. Mantenha a primeira metade na parte superior da página e mova o restante para a parte inferior. Como a primeira parte do snippet de acompanhamento tem pouco ou nenhum efeito na renderização da página, deixe essa parte no topo e coloque a parte do snippet que insere o 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>

Os dois códigos precisam ser unidos nas próprias tags de script, mas somente as últimas seis linhas do snippet assíncrono original precisam ser movidas para a parte inferior. Todas as linhas que enviam métodos para _gaq podem permanecer no topo.

Voltar ao início

Como evitar as armadilhas comuns

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

Os nomes dos métodos diferenciam maiúsculas de minúsculas.
Se você usar um nome de método sem a capitalização incorreta, as chamadas do método não funcionarão. Exemplos:
```
_gaq.push(['_trackpageview']);   // bad
_gaq.push(['_trackPageview']);   // good
```
Use os nomes de método 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.
Todos os valores que não são 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
```

As strings não podem ter 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 rastreamento

Em alguns casos, é necessário desativar o código de acompanhamento do Google Analytics em uma página sem precisar remover o snippet de código. Por exemplo, você poderá fazer isso se a política de privacidade do seu site incluir o recurso para 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 do snippet de acompanhamento para o Google Analytics. Quando o Analytics tenta definir um cookie ou enviar dados de volta para os servidores, ele verifica se essa propriedade está definida como true. Se tiver, o efeito será o mesmo que se o visitante tivesse o plug-in de desativação do Google Analytics para navegador instalado.

Para desativar o acompanhamento, defina a seguinte propriedade window como true:

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

Em que 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. Essa propriedade precisa ser definida em todas as páginas em que você quer desativar o acompanhamento do Google Analytics. Se a propriedade não for definida ou for definida como falsa, o acompanhamento funcionará normalmente.

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

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

Além disso, você gostaria de desativar esse código de acompanhamento para definir cookies ou enviar dados de volta ao Google Analytics e, em seguida, usar o seguinte código antes de o código de acompanhamento ser chamado:

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

Se você usa vários rastreadores em uma página com vários IDs de propriedade da Web, defina a variável window['ga-disable-UA-XXXXXX-Y'] equivalente como true para cada propriedade e desative completamente o acompanhamento do Google Analytics nessa página.

Exemplo

Veja um exemplo simples de um código que pode ser usado para oferecer recursos de desativação aos 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. Lembre-se de substituir o valor de gaProperty de UA-XXXX-Y pela propriedade usada no seu site. Esse é o mesmo valor que você transmite ao 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 clicar no link HTML de desativação, a função gaOptout personalizada será executada. Ele definirá um cookie por muito tempo no futuro e desativará 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. Se tiver sido, 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