Esta página foi traduzida pela API Cloud Translation.

Introdução à ga.js (legada)

A ga.js é uma biblioteca JavaScript para medir 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, a analytics.js.

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

O snippet do Google 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 usar isso 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 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 acompanhamento para uma lista dos métodos disponíveis na API e o Guia de uso para detalhes sobre o uso da sintaxe assíncrona. Para 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 assíncrona mais recente, remova o snippet de acompanhamento existente primeiro. Não recomendamos usar os dois snippets na mesma página. Para ver instruções sobre a migração, consulte 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 age como uma fila, que é uma estrutura de dados primeiro a chegar,primeiro a sair que coleta chamadas de API até que a ga.js esteja pronta 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. Matrizes de comando 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ê deseja transmitir para o método do objeto de acompanhamento. 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 está 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 de acompanhamento são iguais no acompanhamento assíncrono e tradicional. 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. No entanto, 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, depois, faz referência a ele pelo 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 por push 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

Divisão do 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 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, 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>

Ambas as partes do código precisam ser unidas nas suas próprias tags de script, mas apenas as seis últimas linhas do snippet assíncrono original precisam ser movidas para a parte inferior. 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 adequada, 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.
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 tê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

Como desativar o 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 o 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 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 "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. É necessário definir essa propriedade 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 "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']

E se você quiser desativar esse código de acompanhamento para impedir que ele defina cookies ou envie dados de volta ao Google Analytics, use o código a seguir antes de chamar o código:

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

Se você usa vários rastreadores em uma página com diversos IDs de propriedade da Web, é 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

Veja 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ê transmite 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 muito tempo no futuro e desativa a coleta de dados da analytics.js. Quando um usuário retorna a esse site, o script acima verificará se o cookie de desativação foi definido. Em caso negativo, a coleta de dados da analytics.js também é desativada.

Forçar o uso de SSL (HTTPS)

Para forçar o Google Analytics a sempre enviar dados usando SSL, mesmo a partir 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