Envio de dados ao Google Analytics

A última linha do snippet de acompanhamento 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. O snippet de acompanhamento JavaScript envia um hit do tipo pageview. Outros tipos de hit incluem screenview, event, transaction, item, social, exception e timing. Este guia descreve 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 Acompanhamento 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 Protocolo de avaliação.

Se você estiver com as ferramentas de desenvolvedor do seu navegador abertas ao carregar uma página que usa o 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 ao Protocolo de avaliação, os rastreadores enviam todos os campos que estão atualmente armazenados e são parâmetros válidos do Protocolo de avaliação. Por exemplo, campos como title e location são enviados, mas cookieDomain e hitCallback não.

Em alguns casos, convém enviar campos ao Google Analytics para o hit atual, mas não para hits subsequentes. Um exemplo disso é um hit de evento em que os campos eventAction e eventLabel são relevantes somente para o hit atual.

Para enviar campos somente com o hit atual, você pode transmiti-los como argumentos ao método send. Para que os dados de campo 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 de acompanhamento ou por meio da adição de um comando send à fila de comandos do ga(). Como na maior parte do tempo não há uma referência ao objeto de acompanhamento, o uso da fila de comandos do ga() é a maneira recomendada para 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]);

Conforme 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 de acompanhamento e não são enviados com hits subsequentes.

Se algum dos campos transmitidos com o comando send já estiver definido no objeto de acompanhamento, os valores transmitidos no comando serão usados no lugar dos valores armazenados no rastreador.

As chamadas para o comando send precisam especificar um hitType e, dependendo do tipo especificado, outros parâmetros também podem ser necessários. Consulte os guias individuais sobre Acompanhamento de interações comuns do usuário na navegação à esquerda para ver mais detalhes.

A maneira mais simples (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'
});

Por conveniência, 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 "evento" poderia ser reescrito como:

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 de acompanhamento

Se você tem uma referência ao objeto do rastreador, pode chamar diretamente o método send desse rastreador:

ga(function(tracker) {
  tracker.send('event', 'Video', 'play', 'cats.mp4');
});

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ê deseja 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 no botão "Enviar" inicia imediatamente o carregamento da próxima página, e todos os comandos ga('send', ...) não serão executados.

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

Para ser notificado quando o envio de um hit for concluído, defina o campo hitCallback. hitCallback é uma função chamada assim que o hit é enviado.

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, então, 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 do analytics.js não for carregada, a função hitCallback nunca será executada. Além disso, se a função hitCallback nunca for executada, os usuários nunca poderão enviar o formulário.

Todas as vezes que você insere funcionalidades críticas do site na função hitCallback, deve sempre usar 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 por todo 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 do período de tempo limite, a função de entrada será chamada 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 envolver todas as funções hitCallback facilmente com um tempo limite para garantir que seu site funcione conforme esperado até mesmo quando seus hits não forem enviados ou a biblioteca do 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, o analytics.js escolhe o método HTTP e o mecanismo de transporte com os quais enviar hits de modo ideal. 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 (em que os hits frequentemente 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 usuário é compatível com o navigator.sendBeacon, você pode especificar 'beacon' como o mecanismo transport e não precisa se preocupar em definir um retorno de hit.

O código a seguir define o mecanismo de transporte como 'beacon' nos navegadores compatíveis com ele.

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á fora desenvolvidas e disponibilizadas como plug-ins do analytics.js. O próximo guia explica como usar os plug-ins do analytics.js com a fila de comandos do ga().