Acesso e configuração de dados de campo

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 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.

Retorno pronto

O ready callback é 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 tem mais de um rastreador na página, é possível acessá-los 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 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 de acompanhamento, 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 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 em um objeto de acompanhamento requer o uso do "ready callback", é recomendável usar a fila de comandos do ga() para atualizar um rastreador.

Fila de comandos do ga()

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

Se você tem uma referência ao objeto de acompanhamento, pode invocar 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.