A última linha do snippet de medição JavaScript adiciona um comando send
à fila de comandos do ga()
para enviar uma exibição de página ao Google Analytics:
ga('create', 'UA-XXXXX-Y', 'auto'); ga('send', 'pageview');
O objeto que faz o envio é o rastreador que foi agendado para criação na linha de código anterior, e os dados enviados são aqueles armazenados no rastreador.
Este guia descreve as várias maneiras de enviar dados ao Google Analytics e explica como controlar quais dados são enviados.
Hits, tipos de hit e o Protocolo de avaliação
Quando um rastreador envia dados ao Google Analytics, esse processo é chamado de envio de um hit, e todos os hits precisam ter um tipo. A tag do Google Analytics envia um hit do tipo pageview
. Os outros tipos de hit são screenview
, event
, transaction
, item
, social
, exception
e timing
. Neste guia, descrevemos os conceitos e os métodos comuns a todos os tipos de hit. É possível encontrar guias individuais para cada tipo de hit na seção Medição de interações comuns do usuário, na navegação à esquerda.
O hit é uma solicitação HTTP que consiste em pares de campo e valor codificados como uma string de consulta e enviados ao Measurement Protocol.
Se você estiver com as ferramentas de desenvolvedor do seu navegador abertas ao carregar uma página que usa a analytics.js, poderá ver os hits serem enviados na guia "Rede". Procure solicitações enviadas para google-analytics.com/collect
.
Quais dados são enviados
Ao enviar um hit para o Measurement Protocol, os rastreadores transferem todos os campos que estão armazenados e são parâmetros válidos do Measurement Protocol. Por exemplo, campos como title
e location
são enviados, mas cookieDomain
e hitCallback
não são.
Em alguns casos, convém enviar campos ao Google Analytics relacionados ao hit atual, mas não aos próximos hits. Um exemplo disso é um hit de evento em que os campos eventAction
e eventLabel
são relevantes apenas para o hit atual.
Para enviar campos somente com o hit atual, transmita-os como argumentos ao método send
. Se você quiser que os dados dos campos sejam enviados com todos os hits subsequentes, atualize o rastreador usando o método set
.
Método "send"
O método send
de um rastreador pode ser chamado diretamente no próprio objeto do rastreador ou adicionando um comando send
à fila de comandos do ga()
. Como na maioria das vezes você não tem uma referência ao objeto do rastreador, usar a fila de comandos do ga()
é a maneira recomendada de enviar dados do rastreador ao Google Analytics.
Uso da fila de comandos do ga()
A assinatura para adicionar um comando send
à fila de comandos do ga()
é a seguinte:
ga('[trackerName.]send', [hitType], [...fields], [fieldsObject]);
Como mencionado acima, os valores especificados nos parâmetros hitType
, ...fields
e fieldsObject
são enviados somente para o hit atual. Eles não são armazenados no objeto do rastreador e não são enviados com hits subsequentes.
Se algum dos campos transmitidos com o comando send
já estiver definido no objeto, os valores enviados no comando serão usados no lugar daqueles armazenados no rastreador.
As chamadas para o comando send
precisam especificar um hitType, e, dependendo do tipo definido, outros parâmetros também podem ser necessários. Consulte os guias individuais sobre avaliação de interações comuns do usuário na navegação à esquerda para ver mais detalhes.
O jeito mais fácil (e que funciona para todos os tipos de hit) de usar o comando send
é transmitir todos os campos usando o parâmetro fieldsObject
. Por exemplo:
ga('send', {
hitType: 'event',
eventCategory: 'Video',
eventAction: 'play',
eventLabel: 'cats.mp4'
});
Para facilitar o fluxo de trabalho, determinados tipos de hit permitem que os campos mais usados sejam transmitidos diretamente como argumentos para o comando send
. Por exemplo, o comando send
acima para o tipo de hit de "evento" poderia ser reescrito da seguinte forma:
ga('send', 'event', 'Video', 'play', 'cats.mp4');
Para ver uma lista completa dos campos que podem ser transmitidos como argumentos para os vários tipos de hit, consulte a seção "Parâmetros" da referência do método "send".
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.
O comando send
a seguir será chamado no rastreador chamado "myTracker":
ga('myTracker.send', 'event', 'Video', 'play', 'cats.mp4');
No próprio objeto do rastreador
Se você tem uma referência ao objeto do rastreador, chame o método send
desse rastreador de modo direto:
ga(function(tracker) {
tracker.send('event', 'Video', 'play', 'cats.mp4');
});
Como saber quando o hit foi enviado
Em alguns casos, é necessário saber quando o envio do hit ao Google Analytics foi concluído para que você possa agir imediatamente depois disso. Isso é comum quando você precisa registrar uma interação específica que tiraria o usuário da página atual. Muitos navegadores interrompem a execução de JavaScript assim que a página começa a ser descarregada. Isso significa que seus comandos do analytics.js para enviar hits nunca serão executados.
Um exemplo disso é quando você quer enviar um evento ao Google Analytics para registrar que um usuário clicou no botão "Enviar" de um formulário. Na maioria dos casos, clicar nesse botão inicia imediatamente o carregamento da próxima página, antes que qualquer comando ga('send', ...)
seja executado.
A solução para isso é interceptar o evento para interromper o descarregamento da página. Então, você poderá enviar seu hit ao Google Analytics como de costume. Além disso, depois que o envio do hit for concluído, você poderá reenviar o formulário de maneira programática.
hitCallback
Se você quiser receber notificações sobre a conclusão do envio de um hit, defina o campo hitCallback
. A função hitCallback
é chamada quando o hit é enviado com sucesso.
O exemplo a seguir mostra como cancelar a ação de envio padrão de um formulário, enviar um hit ao Google Analytics e depois reenviar o formulário usando a função hitCallback
:
// Gets a reference to the form element, assuming
// it contains the id attribute "signup-form".
var form = document.getElementById('signup-form');
// Adds a listener for the "submit" event.
form.addEventListener('submit', function(event) {
// Prevents the browser from submitting the form
// and thus unloading the current page.
event.preventDefault();
// Sends the event to Google Analytics and
// resubmits the form once the hit is done.
ga('send', 'event', 'Signup Form', 'submit', {
hitCallback: function() {
form.submit();
}
});
});
Gerenciamento de tempos limite
O exemplo acima funciona bem, mas tem um problema sério. Se, por qualquer motivo, a biblioteca analytics.js não for carregada, a função hitCallback
nunca será executada. E se a função hitCallback
nunca for executada, os usuários não conseguirão enviar o formulário.
Ao inserir funcionalidades essenciais do site na função hitCallback
, use sempre uma função de tempo limite para gerenciar casos em que a biblioteca analytics.js não é carregada.
O próximo exemplo atualiza o código acima para usar um tempo limite. Se um segundo se passar depois que o usuário clicar no botão "Enviar" e a função hitCallback
não tiver sido executada, o formulário será reenviado de qualquer maneira.
// Gets a reference to the form element, assuming // it contains the id attribute "signup-form". var form = document.getElementById('signup-form'); // Adds a listener for the "submit" event. form.addEventListener('submit', function(event) { // Prevents the browser from submitting the form // and thus unloading the current page. event.preventDefault(); // Creates a timeout to call `submitForm` after one second. setTimeout(submitForm, 1000); // Keeps track of whether or not the form has been submitted. // This prevents the form from being submitted twice in cases // where `hitCallback` fires normally. var formSubmitted = false; function submitForm() { if (!formSubmitted) { formSubmitted = true; form.submit(); } } // Sends the event to Google Analytics and // resubmits the form once the hit is done. ga('send', 'event', 'Signup Form', 'submit', { hitCallback: submitForm }); });
Se você usa o padrão acima em muitos lugares do seu site, provavelmente é mais fácil criar uma função de utilitário para gerenciar tempos limite.
A função de utilitário a seguir aceita uma função como entrada e retorna uma nova função. Se a função retornada for chamada antes do período de tempo limite (o tempo limite padrão é de um segundo), ela limpará o tempo limite e invocará a função de entrada. Se a função retornada não for chamada antes desse período, a função de entrada será invocada de qualquer maneira.
function createFunctionWithTimeout(callback, opt_timeout) {
var called = false;
function fn() {
if (!called) {
called = true;
callback();
}
}
setTimeout(fn, opt_timeout || 1000);
return fn;
}
Agora você pode unir todas as funções hitCallback
facilmente com um tempo limite para garantir que seu site funcione conforme esperado até mesmo quando os hits não forem enviados ou a biblioteca analytics.js nunca for carregada.
// Gets a reference to the form element, assuming // it contains the id attribute "signup-form". var form = document.getElementById('signup-form'); // Adds a listener for the "submit" event. form.addEventListener('submit', function(event) { // Prevents the browser from submitting the form // and thus unloading the current page. event.preventDefault(); // Sends the event to Google Analytics and // resubmits the form once the hit is done. ga('send', 'event', 'Signup Form', 'submit', { hitCallback: createFunctionWithTimeout(function() { form.submit(); }) }); });
Especificação de mecanismos de transporte diferentes
Por padrão, a analytics.js escolhe o método HTTP e o mecanismo de transporte com que enviar hits de forma mais eficiente. As três opções são 'image'
(usando um objeto Image
), 'xhr'
(usando um objeto XMLHttpRequest
) ou 'beacon'
(usando o novo método navigator.sendBeacon
).
Os dois primeiros métodos compartilham o problema descrito na seção anterior, ou seja, geralmente os hits não são enviados quando a página está sendo descarregada. O método navigator.sendBeacon
, em contrapartida, é um novo recurso HTML criado para resolver esse problema.
Se o navegador do seu usuário for compatível com navigator.sendBeacon
, você poderá especificar 'beacon'
como o mecanismo transport
, sem precisar definir um callback de hit.
O código a seguir define o mecanismo de transporte como 'beacon'
nos navegadores compatíveis.
ga('create', 'UA-XXXXX-Y', 'auto');
// Updates the tracker to use `navigator.sendBeacon` if available.
ga('set', 'transport', 'beacon');
Próximas etapas
Às vezes, a avaliação de determinados tipos de interações do usuário pode exigir implementações complexas. No entanto, em muitos casos essas implementações já foram desenvolvidas e disponibilizadas como plug-ins da analytics.js. O próximo guia explica como usar os plug-ins da analytics.js com a fila de comandos do ga()
.