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.