Method Reference - Web Tracking (analytics.js)

A biblioteca analytics.js fornece dois objetos principais para interagir com o Google Analytics. Cada objeto contém vários métodos:

Métodos do objeto ga

Quando você inclui o snippet JavaScript analytics.js padrão na sua página, ele cria um objeto global chamado ga. Os desenvolvedores usam o objeto ga para criar objetos de acompanhamento que, por sua vez, enviam dados para uma propriedade da Web do Google Analytics.

create

Cria um novo objeto de acompanhamento padrão.

ga('create', trackingId, opt_configObject);

Parâmetros

  • String trackingId - o ID da propriedade da Web do site sendo acompanhado.
  • Object opt_configObject - um objeto opcional que contém pares de campo/valor de configuração.

Exemplos

Criar um rastreador padrão.

ga('create', 'UA-XXXX-Y', 'auto');

Criar um rastreador usando um nome de cookie personalizado.

ga('create', 'UA-XXXX-Y', 'auto', {'cookieName': '_ga2'});

Criar um rastreador usando a sintaxe síncrona:

var tracker = ga.create('UA-XXXX-Y', 'auto');

ga('create', ...) pode aceitar argumentos de posição e argumentos de objeto para os campos trackingId, cookieDomain e name. A ordem é importante. Por exemplo, os dois snippets a seguir são idênticos:

ga('create', 'UA-XXXX-Y', 'auto', 'T1000');
ga('create', {trackingId: 'UA-XXXX-Y', cookieDomain: 'auto', name: 'T1000'});

getByName

Retorna o objeto de acompanhamento com o nome indicado ou nulo se nenhum objeto de acompanhamento com o nome indicado existir no momento.

ga.getByName(name);

Parâmetros

  • String name - nome do rastreador a ser buscado.

Retorna

  • Tracker - um objeto de acompanhamento.

Exemplo

Retornar o objeto de acompanhamento chamado shoehorn:

ga(function() {
  var tracker = ga.getByName('shoehorn');
});

getAll

Retorna uma matriz que contém todos os objetos de acompanhamento existentes atualmente, na ordem em que foram criados.

ga.getAll();

Retorna

  • Array<Tracker> - uma matriz de todos os objetos de acompanhamento.

Exemplo

Retornar todos os objetos de acompanhamento e alertar seus nomes:

ga(function() {
  var trackers = ga.getAll();

  for (var i=0; i < trackers.length; ++i) {
    var tracker = trackers[i];
    alert(tracker.get('name'));
  }
});

Métodos dos objetos de acompanhamento

Depois da criação de um objeto de acompanhamento usando o método create, os seguintes métodos podem ser usados para interagir com o Google Analytics.

send

Envia um beacon de acompanhamento aos servidores de coleta do Google. O objeto de campo opcional permite aos usuários substituir um ou mais valores de campo apenas para esse hit.

ga('send', hitType, opt_fieldObject);

Parâmetros

  • String hitType - o tipo de hit a ser enviado. Os valores suportados são:
  • Object opt_fieldObject - um objeto que contém um ou mais pares de campos/valores usados para substituir um valor de campo apenas para esse hit. Os campos são revertidos para seus valores originais após a conclusão do hit.

Exemplo

Enviar um tipo de hit "pageview" e substituir o título da página.

ga('send', 'pageview', {'title': 'my new title'});

set

Atualiza o valor atualmente associado ao campo especificado. O método set pode ser chamado com um único campo e valor:

ga('set', fieldName, value);

Parâmetros

  • String fieldName - nome do campo a ser definido.
  • String|Number|Object|Boolean value - o novo valor a ser associado ao campo especificado.

Você também pode chamar set com um objeto que contém vários pares de campos/valores para atualização em massa.

ga('set', fieldObject);

Os valores definidos persistem com todas as chamadas send subsequentes por toda a vida útil do objeto de acompanhamento.

Parâmetros

  • Object fieldObject - um objeto que contém um ou mais pares de campos/valores a serem definidos.

Exemplos

Definir o campo page para todos os hits subsequentes:

ga('set', 'page', '/my-new-page');

Definir o campo page e title para todos os hits subsequentes:

ga('set', {
  'page': '/my-new-page',
  'title': 'my new title'
});

get

Retorna o valor atualmente associado ao campo especificado. Deve ser chamado em um objeto de acompanhamento instanciado.

var fieldValue = tracker.get(fieldName);

Parâmetros

  • String fieldName - nome do campo a ser recuperado.

Retorna

  • String|Number|Object - o valor do campo.

Exemplo

Conseguir a página atual de um rastreador:

ga(function(tracker) {
  var page = tracker.get('page');
});

Essa função é executa depois que a biblioteca analytics.js é carregada. Quando a função é executada, o parâmetro tracker tem uma referência para o rastreador padrão (supondo que ele tenha sido criado antes da função ser chamada). A referência do rastreador é, então, usada para conseguir o valor page.

Sintaxe da chamada

Existem algumas formas de chamar cada um dos métodos ga.

Assíncrona (rastreador padrão)

O snippet de JavaScript anaytics.js foi projetado para carregar de forma assíncrona e evitar que os navegadores pausem para carregar a biblioteca. Para que não precise sincronizar seu código com base no carregamento da biblioteca, você pode usar o objeto ga como uma função passando o nome do método como o primeiro parâmetro:

ga('create', 'UA-XXXX-Y', 'auto');
ga('send', 'pageview');

Essa função é executada assim que o carregamento da biblioteca é concluído. O método create cria um objeto de acompanhamento padrão chamado t0. Em seguida, o método send, ou qualquer outro método chamado com essa sintaxe, é executado no objeto de acompanhamento padrão.

Nesse caso, a criação de um objeto de acompanhamento padrão é realizada como uma conveniência para a maioria das implementações.

Assíncrona (rastreador nomeado)

Em alguns casos, convém criar vários rastreadores na mesma página. Para diferenciar os rastreadores, é necessário nomear cada rastreador adicional.

Crie um objeto de acompanhamento nomeado definindo o campo de configuração name usando o parâmetro de objeto de configuração opcional do método create.

ga('create', 'UA-XXXX-Y', 'auto', {'name': 'tracker2'});

Então, chame os métodos de acompanhamento nos rastreadores nomeados incluindo o nome do rastreador e um . (ponto) antes dos métodos:

ga('tracker2.send', 'pageview');

Síncrona

A biblioteca anaytics.js também suporta uma forma síncrona de chamar métodos. Nesse caso, você chama os métodos diretamente nos objetos ga ou tracker respectivamente:

var tracker = ga.create('UA-XXXX-Y', 'auto');
tracker.send('pageview');

Sincronização assíncrona

Em alguns casos, alguns métodos precisam ser chamados apenas depois que a biblioteca for carregada. Por exemplo, o método get só funciona depois que a biblioteca está carregada, o rastreador criado e os campos definidos. Para resolver isso, passe uma função para o objeto ga que só será executada quando a biblioteca estiver carregada:

ga(function(tracker) {
  var page = tracker.get('name');
});

A função que você passa para o objeto ga aceita um parâmetro que, após executado, terá o valor do rastreador padrão. O objeto de acompanhamento pode, então, ser utilizado com a sintaxe síncrona. Por exemplo, este comando também funciona:

ga('create', 'UA-XXXX-Y', 'auto');
ga(function(tracker) {
  tracker.send('pageview');
});

Da mesma forma, para acompanhar uma exibição de página em todos os rastreadores que foram criados, você pode usar:

ga(function() {
  var trackers = ga.getAll();
  for (var i=0; i<trackers.length; ++i) {
    var tracker = trackers[i];
    tracker.send('pageview');
  }
});

Isso é especialmente útil se você deseja desenvolver extensões em que não sabe quantos rastreadores foram criados em um site. Com essa sintaxe, a função pode executar uma grande quantidade de lógica adicional para cada rastreador na página, após o carregamento do código de acompanhamento.