Tarefas

Este guia descreve as tarefas, um recurso avançado usado para personalizar a forma com que o "analytics.js" valida, cria e envia solicitações do Protocolo de avaliação.

Visão geral

Toda vez que o comando send é chamado, o analytics.js executa uma sequência de tarefas para validar, construir e enviar uma solicitação do Protocolo de avaliação do navegador do usuário aos servidores do Google Analytics. A tabela a seguir descreve cada uma dessas tarefas, na ordem em que são executadas:

Nome da tarefa Descrição
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 ausentes 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 sampleRate do rastreador.
buildHitTask Cria uma string de solicitação do Protocolo de avaliação e a armazena no campo hitPayload.
sendHitTask Transmite a solicitação do Protocolo de avaliação armazenada no campo hitPayload dos servidores do Google Analytics.
timingTask Gera automaticamente um hit de velocidade do site com base na configuração de siteSpeedSampleRate para o 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 exibição (_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 fornece acesso a qualquer um dos campos definidos na Referência de campos do Analytics.js.

É possível acessar ou substituir tarefas por meio do rastreador padrão e os métodos [get](/analytics/devguides/collection/analyticsjs/method-reference#get) e [set](/analytics/devguides/collection/analyticsjs/method-reference#set). 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.

Substituição de uma tarefa

Para substituir uma tarefa, você pode usar set para definir o valor dela como uma função que faz algo diferente. Um motivo comum para substituir tarefas é fazer um esboço do método da funcionalidade ao testar suas implementações do analytics.js.

O código a seguir substitui o sendHitTask por uma função que registra a carga útil 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, sendHitTask é substituído por uma função de tarefa personalizada que primeiro chama a função sendHitTask original para enviar o beacon da solicitação normal a google-analytics.com/collection e, em seguida, executa o código personalizado para enviar uma cópia da solicitação do Protocolo de avaliação 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');

Como abortar o processamento de uma tarefa

Uma tarefa pode abortar o processamento de tarefas subsequentes por meio do lançamento de uma exceção. Se a tarefa que lançar a exceção for executada antes de sendHitTask, a solicitação do Protocolo de avaliação não será enviada aos servidores do Google Analytics. No exemplo abaixo, abortamos 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');