Envio de dados ao Google Analytics

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().