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');