Algumas vezes, para acessar e definir dados de campo em um rastreador, é necessário ter uma referência ao próprio objeto do rastreador. Como os comandos adicionados à fila de comandos do ga() são executados de forma assíncrona e não retornam um valor e como os rastreadores normalmente são criados usando o comando create é preciso aguardar até que o create seja executado para acessar uma referência ao objeto do rastreador. É possível fazer isso com o ready callback.
Ready callback
O ready callback é uma função que você pode adicionar à fila de comandos do ga(). A função será invocada assim que a biblioteca da analytics.js estiver totalmente carregada, e todos os comandos anteriores adicionados à fila forem executados.
Como todos os comandos adicionados à fila são executados em ordem, a adição de um "ready callback" à fila após a inclusão de um comando create garante que essa função seja executada depois que o rastreador é criado. Se um rastreador padrão tiver sido criado quando um "ready callback" for invocado, ele será transmitido como o primeiro (e único) argumento do callback.
O código a seguir mostra como acessar o objeto de acompanhamento padrão e registrá-lo no console:
ga('create', 'UA-XXXXX-Y', 'auto');
ga(function(tracker) {
// Logs the tracker created above to the console.
console.log(tracker);
});
Acesso a rastreadores por meio de métodos do objeto "ga"
Se você não usa um rastreador padrão ou tem mais de um rastreador na página, é possível acessá-los com um dos métodos do objeto ga.
Depois que a biblioteca analytics.js é totalmente carregada, ela adiciona outros métodos ao próprio objeto ga. Dois desses métodos, getByName e getAll, são usados para acessar os objetos do rastreador.
getByName
Se você sabe o nome do rastreador que gostaria de acessar, use o método getByName:
ga('create', 'UA-XXXXX-Y', 'auto', 'myTracker');
ga(function() {
// Logs the "myTracker" tracker object to the console.
console.log(ga.getByName('myTracker'));
});
getAll
Para ter uma matriz de todos os rastreadores criados, use o método getAll:
ga('create', 'UA-XXXXX-Y', 'auto', 'tracker1');
ga('create', 'UA-XXXXX-Z', 'auto', 'tracker2');
ga(function() {
// Logs an array of all tracker objects.
console.log(ga.getAll());
});
Acesso aos dados armazenados em um rastreador
Quando você tiver uma referência a um objeto do rastreador, poderá usar o método get para acessar o valor de qualquer campo atualmente armazenado no rastreador.
ga('create', 'UA-XXXXX-Y', 'auto');
ga(function(tracker) {
// Logs the trackers name.
// (Note: default trackers are given the name "t0")
console.log(tracker.get('name'));
// Logs the client ID for the current user.
console.log(tracker.get('clientId'));
// Logs the URL of the referring site (if available).
console.log(tracker.get('referrer'));
});
Atualização de dados
Os objetos do rastreador podem ser atualizados utilizando o método set. O método set de um rastreador pode ser chamado no próprio objeto do rastreador ou adicionando um comando set à fila de comandos do ga().
Como a inserção de uma referência em um objeto do rastreador exige o uso do "ready callback", é recomendável utilizar a fila de comandos do ga() para atualizar um rastreador.
Fila de comandos do ga()
O comando set pode ser invocado de duas maneiras: pelo envio de dois parâmetros, um campo e o valor correspondente, ou pelo envio de um objeto de pares de campo/valor.
O exemplo a seguir define o campo page como '/about' no rastreador padrão:
ga('set', 'page', '/about');
Este exemplo define os campos page e title ao mesmo tempo:
ga('set', {
page: '/about',
title: 'About Us'
});
Uso de um rastreador nomeado
Se você usa um rastreador nomeado em vez do rastreador padrão, pode transmitir o nome dele na string de comando.
A chamada a seguir define o campo page no rastreador chamado "myTracker":
ga('myTracker.set', 'page', '/about');
No próprio objeto do rastreador
Se você tem uma referência ao objeto do rastreador, chame o método set desse rastreador de modo direto:
ga(function(tracker) {
tracker.set('page', '/about');
});
Sintaxe do "e" comercial
Os campos do rastreador geralmente são acessados e definidos utilizando os nomes de campo deles. Consulte a referência de campo para ver uma lista completa dos campos do analytics.js e seus nomes.
Uma outra maneira de acessar e definir campos é consultá-los pelos nomes de parâmetros do Measurement Protocol correspondentes.
Por exemplo, as duas expressões console.log a seguir registram o título do documento no console:
ga(function(tracker) {
// Gets the title using the analytics.js field name.
console.log(tracker.get('title'));
// Gets the title using the measurement protocol
// parameter name, prefixed with an ampersand.
console.log(tracker.get('&dt'));
});
Em geral, a sintaxe do "e" comercial não é recomendada e só deve ser usada quando o nome do campo da analytics.js em um parâmetro do Protocolo de avaliação não existe. Isso acontece às vezes quando um novo recurso é adicionado ao Protocolo de avaliação antes de ser implementado na analytics.js.
Próximas etapas
Agora que você sabe como criar rastreadores e atualizar os dados armazenados neles, a próxima etapa é aprender a enviar esses dados ao Google Analytics para processamento.