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

Sempre que o comando send é chamado, a analytics.js executa uma sequência de tarefas para validar, criar e enviar uma solicitação do Protocolo de avaliação 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 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 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 fornece acesso a qualquer um dos campos definidos na Referência de campos do Analytics.jsnce.

É possível acessar ou substituir as tarefas por meio dos 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.

Substituiçã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 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');