Acesso e definição dos dados do rastreador

Algumas vezes, para acessar e definir dados de campo em um rastreador, é necessário ter uma referência ao próprio objeto de acompanhamento. Como os comandos adicionados à fila de comandos do ga() são executados de maneira assíncrona e não retornam um valor e como os rastreadores geralmente são criados por meio do comando create, é necessário aguardar até que o comando create tenha sido executado para acessar uma referência a um objeto de acompanhamento. Você pode fazer isso com o retorno pronto.

Retorno pronto

O retorno pronto é uma função que você pode adicionar à fila de comandos do ga(). A função será invocada assim que a biblioteca do analytics.js estiver totalmente carregada, e todos os comandos anteriores adicionados à fila foram executados.

Como todos os comandos adicionados à fila são executados em ordem, a adição de um retorno pronto à fila após a adição de um comando create garante que o retorno pronto seja executado depois que o rastreador é criado. Se um rastreador padrão tiver sido criado quando um retorno pronto for invocado, ele será transmitido como o primeiro (e único) argumento do retorno.

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 se tem mais de um rastreador na página, pode acessar esses rastreadores por meio de um dos métodos do objeto ga.

Depois que a biblioteca analytics.js é totalmente carregada, ela acrescenta outros métodos ao próprio objeto ga. Dois desses métodos, getByName e getAll, são usados para acessar objetos de acompanhamento.

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 de acompanhamento, poderá usar o método get dela 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 dos dados do rastreador

Os objetos de acompanhamento podem ser atualizados utilizando o método set. O método set de um rastreador pode ser chamado em um objeto de acompanhamento em si ou por meio da adição de um comando set à fila de comandos do ga().

Como a inserção de uma referência a um objeto de acompanhamento requer o uso do retorno pronto, a utilização da fila de comandos do ga() é a maneira recomendada para atualizar um rastreador.

Uso da fila de comandos do ga()

O comando set pode ser invocado de duas maneiras: por meio da transmissão de dois parâmetros, um campo e seu valor correspondente, ou da transmissão 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 de acompanhamento

Se você tem uma referência ao objeto de acompanhamento, pode chamar o método set do rastreador em questão 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 maneira alternativa de acessar e definir campos é consultá-los pelos nomes de parâmetros do Protocolo de avaliação correspondentes deles.

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 do analytics.js para um parâmetro do Protocolo de avaliação não existe (isso acontece ocasionalmente quando um novo recurso é adicionado ao Protocolo de avaliação antes de ser implementado no 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.