Referência da fila de comandos do ga

A fila de comandos do ga() contém uma interface para quase tudo o que você precisa fazer com a biblioteca do analytics.js

O snippet de acompanhamento JavaScript define a função inicial da fila de comandos do ga() para que ela possa ser usada até mesmo antes que a biblioteca do analytics.js seja totalmente carregada. Assim que a biblioteca do analytics.js é carregada, os itens da fila de comandos são executados na ordem em que foram recebidos. Assim que isso é feito, novos comandos enviados à fila são executados imediatamente.

Para manter o snippet de acompanhamento com o menor tamanho possível, a fila de comandos do ga() é sobrecarregada para aceitar argumentos em muitos formatos diferentes. Este documento explica em detalhes todas as diversas maneiras de invocar a função da fila de comandos do ga().

Assinatura de função
ga(command, [...fields], [fieldsObject])

Invocar a função da fila de comandos do ga() com a assinatura de função a seguir envia comandos à fila com a finalidade de agendá-los para execução assim que a biblioteca é carregada.

ga(readyCallback)

Invocar a função da fila de comandos do ga() por meio da transmissão de uma função a ela agenda a função transmitida para execução no próximo ponto da fila.

Como os comandos são executados somente depois que a biblioteca do analytics.js é totalmente carregada, o retorno pronto é voltado principalmente às situações em que você precisa atrasar a execução do código até que o analytics.js esteja totalmente carregado e pronto.

Adição de comandos à fila

Invocar a função da fila de comandos do ga() com a assinatura de função a seguir envia comandos à fila com a finalidade de agendá-los para execução assim que a biblioteca é carregada.

Uso

ga(command, [...fields], [fieldsObject])

Parâmetros

Nome Tipo Obrigatório Descrição
command string sim

Um identificador que representa o comando a ser adicionado à fila. O identificador é composto por três partes (as duas primeiras são opcionais):

[trackerName.][pluginName:]methodName
trackerName Nome do rastreador no qual invocar o comando agendado. Se nenhum nome de rastreador for especificado, o comando será invocado no rastreador padrão.
pluginName Nome de um plug-in obrigatório do analytics.js. Se o pluginName for especificado, o methodName precisará ser um método fornecido pelo plug-in.
methodName Nome do método a ser agendado para execução. Quando você não especifica o nome de um plug-in, esse método precisa ser um dos métodos de comando listados abaixo.
...fields * não Um ou mais parâmetros de conveniência opcionais para especificar rapidamente os campos comuns. Os campos específicos permitidos e o número desses campos variam de acordo com o método de comando que está sendo chamado.
fieldsObject Object não

Um objeto para especificar os valores restantes não especificados em nenhum dos parâmetros fields.

Se um campo for definido em um parâmetro fields e no fieldsObject, o valor presente em fieldsObject será usado.

Consulte a referência de campo para ver a documentação de campo individual.

Exemplos

Consulte a seção métodos de comando abaixo para ver exemplos de comandos individuais.

Retorno pronto

Invocar a função da fila de comandos do ga() por meio da transmissão de uma função a ela agenda a função transmitida para execução no próximo ponto da fila.

Como os comandos são executados somente depois que a biblioteca do analytics.js é totalmente carregada, o retorno pronto é voltado principalmente às situações em que você precisa atrasar a execução do código até que o analytics.js esteja totalmente carregado e pronto.

Uso

ga(readyCallback)

Parâmetros

Nome Tipo Obrigatório Descrição
readyCallback Function sim

Uma função de retorno a ser invocada quando a biblioteca é totalmente carregada e está pronta para receber interações. A função é invocada com o objeto de acompanhamento padrão como o primeiro argumento. Se nenhum acompanhamento padrão for criado, o primeiro argumento será undefined.

Observação: Quando a função de retorno é invocada, todos os métodos do objeto ga ficam disponíveis para uso.

Exemplos

// Queues a tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto');

// Once the tracker has been created, log the
// client ID to the console.
ga(function(tracker) {
  console.log(tracker.get('clientId'));
});
// Queues a named tracker object for creation.
ga('create', 'UA-XXXXX-Y', 'auto', 'myTracker');

// When there is no default tracker, the first
// argument of the ready callback is `undefined`.
ga(function(tracker) {
  console.log(tracker); // Logs `undefined`.
});

Detalhes do método de comando

Veja a seguir uma lista com todos os métodos que podem ser transmitidos à fila de comandos do ga() (excluindo os métodos de plug-in).

create

Cria uma nova instância do rastreador com os campos especificados.

Uso

ga('create', [trackingId], [cookieDomain], [name], [fieldsObject]);

Parâmetros

Consulte a referência de campo para ver a documentação de campo individual.

Retorna

undefined

Exemplos

// Creates a default tracker for the Property UA-XXXXX-Y
// and uses automatic cookie domain configuration.
ga('create', 'UA-XXXXX-Y', 'auto');
// Creates a tracker with the name "myTracker" for the Property
// UA-XXXXX-Y, sets the cookieDomain to "example.com", and specifies
// a transport mechanism of "beacon".
ga('create', 'UA-XXXXX-Y', 'example.com', 'myTracker', {
  transport: 'beacon'
});

send

Envia um hit ao Google Analytics.

Uso

ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);

Os campos enviados são os valores especificados nos parâmetros ...fields e em fieldsObject, combinados com os campos atualmente armazenados no rastreador.

Parâmetros

Os campos que podem ser especificados pelos parâmetros ...fields variam de acordo com o tipo de hit. A tabela a seguir lista os campos que correspondem a cada tipo de hit. Os tipos de hit não listados não aceitam parâmetros ...fields, somente o fieldsObject.

Tipo de hit ...fields
pageview page
event eventCategory, eventAction, eventLabel, eventValue
social socialNetwork, socialAction, socialTarget
timing timingCategory, timingVar, timingValue, timingLabel

Consulte a referência de campo para ver a documentação de campo individual.

Retorna

undefined

Exemplos

// Sends a pageview hit.
ga('send', 'pageview');
// Sends an event hit for the tracker named "myTracker" with the
// following category, action, and label, and sets the nonInteraction
// field value to true.
ga('send', 'event', 'link', 'click', 'http://example.com', {
  nonInteraction: true
});

set

Define um único campo e par de valores ou um grupo de pares de campo/valor em um objeto de acompanhamento.

Uso

// Sets a single field and value.
ga('[trackerName.]set', fieldName, fieldValue);
// Sets a group of field/value pairs.
ga('[trackerName.]set', fieldsObject);

Parâmetros

Consulte a referência de campo para ver a documentação de campo individual.

Retorna

undefined

Exemplos

// Sets the page field to "/about.html".
ga(set, 'page', '/about.html');
// Sets the page field to "/about.html" and the title to "About".
ga(set, {
  page: '/about.html',
  title: 'About'
});

require

Requer um plug-in do analytics.js.

Uso

ga('[trackerName.]require', pluginName, [pluginOptions]);

Parâmetros

Nome Tipo Obrigatório Descrição
pluginName string sim Nome do plug-in a ser obrigatório. Observação: Se não for um plug-in oficial do analytics.js, ele precisará ser fornecido em qualquer outro lugar da página.
pluginOptions Object não Um objeto de inicialização que será transmitido ao construtor do plug-in no momento da instanciação.

Retorna

undefined

Exemplo

// Requires the Enhanced Ecommerce plugin.
ga('require', 'ec');
// Requires the Display Features plugin for the tracker
// named "myTracker" and override its default cookie name.
ga('myTracker.require', 'displayfeatures', {
  cookieName: 'display_features_cookie'
});

provide

Fornece um plug-in do analytics.js e seus métodos de uso com a fila de comandos do ga().

ga('provide', pluginName, pluginConstuctor);

Parâmetros

Nome Tipo Obrigatório Descrição
pluginName string sim Nome do plug-in fornecido. O nome usado precisa ser igual àquele usado por qualquer chamada de solicitação.
pluginConstuctor Function sim Uma função de construtor que fornece toda a lógica e os métodos de plug-in. Esse construtor será invocado com o objeto pluginsOptions especificado no método de solicitação.

Exemplo

// Defines a plugin constructor
function MyPlugin(tracker, options) {
  // ...
}

// Provides the plugin for use with the ga() command queue.
ga('provide', 'myplugin', MyPlugin);

remove

Remove um objeto de acompanhamento.

Uso

ga('[trackerName.]remove');

Exemplos

// Remove the default tracker.
ga('remove');
// Remove the  tracker named "myTracker".
ga('myTracker.remove');