Como a analytics.js funciona

Quase todas as avaliações na analytics.js podem ser feitas usando a fila de comandos do ga(). Neste guia, explicamos o que é a fila de comandos, como ela funciona e como executar comandos para acompanhar as interações do usuário.

Fila de comandos do ga

A tag do Google Analytics define uma função global ga conhecida como "fila de comandos". Ela é chamada assim porque, em vez de executar os comandos que recebe imediatamente, ela os adiciona a uma fila que atrasa a execução até que a biblioteca analytics.js esteja totalmente carregada.

Em JavaScript, as funções também são objetos. Isso significa que elas podem conter propriedades. A tag do Google Analytics define uma propriedade q no objeto de função ga como uma matriz vazia. Se você chamar a função ga() antes de a biblioteca analytics.js ser carregada, a lista de argumentos enviados à ga() será anexada no final da matriz q.

Por exemplo, se você executar a tag do Google Analytics e registrar imediatamente o conteúdo de ga.q no console, verá uma matriz com dois itens de tamanhos diferentes, contendo os dois conjuntos de argumentos já enviados à função ga():

console.log(ga.q);

// Outputs the following:
// [
//   ['create', 'UA-XXXXX-Y', 'auto'],
//   ['send', 'pageview']
// ]

Depois que a biblioteca analytics.js for carregada, ela inspecionará o conteúdo da matriz ga.q e executará cada comando na ordem. Em seguida, a função ga() será redefinida, de modo que todas as chamadas subsequentes sejam executadas imediatamente.

Esse padrão permite que os desenvolvedores usem a fila de comandos do ga() sem se preocuparem se a biblioteca analytics.js terminou de carregar. Ele proporciona uma interface simples de aparência síncrona que elimina a maioria das complexidades do código assíncrono.

Adição de comandos à fila

Todas as chamadas à fila de comandos do ga() compartilham uma assinatura em comum. O primeiro parâmetro, o "command", é uma string que identifica um método específico da analytics.js. Os parâmetros adicionais são os argumentos transmitidos para esse método.

Um comando específico pode se referir a um método global, como create, um método no objeto ga ou um método de instância em um objeto do rastreador, como send. Se a fila do ga() receber um comando que não reconhece, ela irá ignorar esse comando e fazer chamadas seguras à função ga(), que raramente gera erros.

Para ver uma lista abrangente de todos os comandos que podem ser executados por meio da fila, consulte a referência da fila de comandos do ga().

Parâmetros de comando

A maioria dos comandos do analytics.js (e seus métodos correspondentes) aceita parâmetros em diversos formatos diferentes. O motivo disso é facilitar a transmissão de campos usados com frequência a determinados métodos.

Por exemplo, considere os dois comandos na tag do Google Analytics:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');

No primeiro, create aceita que os campos trackingId, cookieDomain e name sejam especificados como o segundo, terceiro e quarto parâmetros, respectivamente. O comando send aceita um segundo parâmetro hitType opcional.

Além disso, todos os comandos permitem que um parâmetro fieldsObject final seja usado para especificar qualquer campo. Por exemplo, os dois comandos de tag acima podem ser reescritos como:

ga('create', {
  trackingId: 'UA-XXXXX-Y',
  cookieDomain: 'auto'
});
ga('send', {
  hitType: 'pageview'
});

Consulte a referência da fila de comandos do ga() para ver uma lista abrangente dos parâmetros opcionais permitidos para cada um dos comandos.

Próximas etapas

Agora que leu este guia, você já sabe como executar comandos com a analytics.js e como a fila de comandos funciona. O próximo guia abrangerá como criar objetos do rastreador.