Como o analytics.js funciona

Quase tudo o que precisa para acompanhar com o analytics.js pode ser feito usando a fila de comandos do ga(). Este guia explica o que é a fila de comandos, como ela funciona e como executar comandos para acompanhar as interações do usuário.

A fila de comandos do ga

O snippet de acompanhamento JavaScript define uma função ga global conhecida como "fila de comandos". Ela é chamada de fila de comandos 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 do analytics.js esteja totalmente carregada.

Em JavaScript, as funções também são objetos. Isso significa que elas podem conter propriedades. O snippet de acompanhamento define uma propriedade q no objeto de função ga como uma matriz vazia. Antes do carregamento da biblioteca do analytics.js, chamar a função ga() anexa a lista de argumentos transmitidos à função ga() ao final da matriz q.

Por exemplo, se você executar o snippet de acompanhamento e registrar imediatamente o conteúdo de ga.q no console, verá uma matriz e dois itens que contêm os dois conjuntos de argumentos já transmitidos à função ga():

console.log(ga.q);

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

Depois que a biblioteca do analytics.js é carregada, ela inspeciona o conteúdo da matriz ga.q e executa cada comando na ordem. Depois disso, a função ga() é redefinida para que todas as chamadas subsequentes sejam executadas imediatamente.

Esse padrão permite que os desenvolvedores usem a fila de comandos do ga() sem precisar se preocupar com a conclusão do carregamento da biblioteca do analytics.js. 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 para a fila de comandos do ga() compartilham uma assinatura em comum. O primeiro parâmetro, o "command", é uma string que identifica um método analytics.js específico. Todos os parâmetros adicionais são os argumentos transmitidos para esse método.

O método ao qual determinado comando se refere pode ser um método global, como create, um método no objeto ga ou um método de instância em um objeto de acompanhamento, como send. Se a fila de comandos do ga() receber um comando que não reconhece, ela simplesmente a ignorará, tornando as chamadas para a função ga() muito seguras, pois elas quase nunca resultarão em erro.

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

Parâmetros de comando

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

Como exemplo, considere os dois comandos no snippet de acompanhamento JavaScript:

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

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

Todos os comandos aceitam um parâmetro fieldsObject final que também pode ser usado para especificar qualquer campo. Por exemplo, os dois comandos acima no snippet de acompanhamento podem ser reescritos como:

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

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

Próximas etapas

Depois de ler este guia, você deve saber como executar comandos com o analytics.js e como a fila de comandos funciona. O próximo guia abrangerá como criar objetos de acompanhamento.