Tarefas

Neste guia, descrevemos as tarefas, um recurso avançado usado para personalizar como a analytics.js valida, cria e envia solicitações do Measurement Protocol.

Visão geral

Sempre que o comando send é chamado, a analytics.js executa uma sequência de tarefas para validar, criar e enviar uma solicitação do Measurement Protocol do navegador do usuário ao Google Analytics. A tabela a seguir descreve cada uma dessas tarefas na ordem em que são executadas:

Nome da tarefa Descrição
customTask Por padrão, essa tarefa não realiza nenhuma ação. Substitua-a para incluir um comportamento personalizado.
previewTask Cancela a solicitação se a página só estiver sendo renderizada para gerar uma miniatura de "Principais sites" para o Safari.
checkProtocolTask Cancela a solicitação se o protocolo da página não for http ou https.
validationTask Cancela a solicitação se os campos obrigatórios estiverem faltando ou forem inválidos.
checkStorageTask Cancela a solicitação se o rastreador estiver configurado para usar cookies, mas o navegador do usuário estiver com cookies desativados.
historyImportTask Importa informações de cookies "ga.js" e "urchin.js" para preservar o histórico dos visitantes quando um site migra para o Universal Analytics.
samplerTask Faz uma amostragem dos visitantes com base na configuração de sampleRate do rastreador.
buildHitTask Cria uma string de solicitação do Measurement Protocol e a armazena no campo hitPayload.
sendHitTask Transmite a solicitação do Measurement Protocol armazenada no campo hitPayload para os servidores do Google Analytics.
timingTask Gera automaticamente um hit de velocidade do site com base na configuração de siteSpeedSampleRate do rastreador.
displayFeaturesTask Enviará um hit adicional se os recursos de exibição estiverem ativados e um hit anterior não tiver sido enviado no período definido pelo cookie dos Recursos de publicidade (_gat).

Cada tarefa é implementada como uma função JavaScript, que usa um único parâmetro de modelo como entrada. O modelo é um objeto simples que dá acesso a qualquer um dos campos definidos na referência de campos da analytics.js.

É possível acessar ou substituir as tarefas usando os métodos get e set do rastreador padrão. Por meio desses métodos, você pode substituir tarefas pelas suas próprias funções personalizadas ou aumentar a funcionalidade existente ao definir a execução das suas funções personalizadas antes ou depois de uma tarefa existente.

Implementação

Esta seção descreve como adicionar novas funcionalidades a tarefas existentes, substituir as funções de tarefas incorporadas pelo seu próprio código personalizado ou desativar completamente a função de uma tarefa.

Modificação de uma tarefa

Se você quiser modificar uma tarefa, use set para definir o valor dela como uma função que faz algo diferente. Um motivo comum para modificar tarefas é fazer um stub da funcionalidade ao testar suas implementações da analytics.js.

O código a seguir substitui o sendHitTask por uma função que registra o payload do hit no console:

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'sendHitTask', function(model) {
  console.log(model.get('hitPayload'));
});

Adição a uma tarefa

Para inserir uma nova funcionalidade, você pode definir a execução da sua tarefa personalizada antes ou depois de uma tarefa existente. No exemplo abaixo, o sendHitTask é substituído por uma função de tarefa personalizada que primeiro chama a função sendHitTask original para enviar o beacon de solicitação normal para google-analytics.com/collection e, depois, executa o código personalizado para enviar uma cópia da solicitação do Measurement Protocol a um servidor local.

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

ga(function(tracker) {

  // Grab a reference to the default sendHitTask function.
  var originalSendHitTask = tracker.get('sendHitTask');

  // Modifies sendHitTask to send a copy of the request to a local server after
  // sending the normal request to www.google-analytics.com/collect.
  tracker.set('sendHitTask', function(model) {
    originalSendHitTask(model);
    var xhr = new XMLHttpRequest();
    xhr.open('POST', '/localhits', true);
    xhr.send(model.get('hitPayload'));
  });
});

ga('send', 'pageview');

Cancelamento do processamento de uma tarefa

Uma tarefa pode cancelar o processamento de tarefas subsequentes por meio do lançamento de uma exceção. Se a tarefa que gera a exceção for executada antes de sendHitTask, isso impedirá que a solicitação do Measurement Protocol seja enviada aos servidores do Google Analytics. No exemplo abaixo, cancelamos a solicitação sempre que o navegador do usuário tiver um cookie chamado "testing" com o valor "true".

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

ga(function(tracker) {
  var originalBuildHitTask = tracker.get('buildHitTask');
  tracker.set('buildHitTask', function(model) {
    if (document.cookie.match(/testing=true/)) {
      throw 'Aborted tracking for test user.';
    }
    originalBuildHitTask(model);
  });
});

ga('send', 'pageview');

Desativação de uma tarefa

Para desativar qualquer função de tarefa incorporada, substitua-a por "null".

ga('create', 'UA-XXXXX-Y', 'auto');
ga('set', 'checkProtocolTask', null); // Disables file protocol checking.
ga('send', 'pageview');