A fila de comandos do ga()
contém uma interface para quase tudo que você precisa fazer com a biblioteca 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 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 o menor possível, a fila de comandos ga()
está sobrecarregada para aceitar argumentos em vários 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(readyCallback) |
Invocar a função da fila de comandos do 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
|
|||||||||
...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 Se um campo for definido em um parâmetro |
Consulte a referência de campos para ver a documentação referente a cada um.
Exemplos
Consulte a seção métodos de comando abaixo para ver exemplos de comandos individuais.
Ready callback
Invocar a função da fila de comandos do ga()
com a 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 rastreador padrão for criado, o primeiro argumento será Observação: quando a função de callback é invocada, todos os métodos do objeto
|
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 campos para ver a documentação referente a cada um.
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 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 os 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 campos para ver a documentação referente a cada um.
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 campos para ver a documentação referente a cada um.
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 o plug-in não for um recurso oficial da analytics.js, você precisará fornecê-lo 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 Advertising Features plugin // named "myTracker" and override its default cookie name. ga('myTracker.require', 'displayfeatures', { cookieName: 'display_features_cookie' });
provide
Fornece um plug-in da analytics.js e os 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 do plug-in. Esse construtor será invocado com o objeto pluginsOptions especificado no método require. |
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');