Acesso e definiçã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.

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 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 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: 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 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 da analytics.js e dos nomes deles.

Uma outra maneira de acessar e definir campos é consultá-los pelos nomes de parâmetros do Protocolo de avaliação 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.