Nesta página, descrevemos como usar os comandos da gtag.js para enviar dados do seu site ao Google Analytics.
Enviar dados com o comando event
Depois de adicionar o snippet global a uma página da Web, use o comando event para enviar dados ao Google Analytics. Por exemplo, use o comando event a seguir para indicar que um usuário fez login usando a Conta do Google:
gtag('event', 'login', {'method': 'Google'});
Saiba mais sobre o comando event na Referência da API.
Enviar dados para grupos e propriedades
É possível enviar um conjunto de informações de avaliação para um ou mais códigos de propriedade do Google Analytics, além de outro conjunto de informações para outros códigos. Você pode organizar as propriedades em grupos e encaminhar dados para eles.
O exemplo de código a seguir ilustra como enviar um evento sign_in para um grupo chamado "agency" que inclui duas propriedades do Google Analytics.
// Configure a target
gtag('config', 'GA_MEASUREMENT_ID_1');
gtag('config', 'GA_MEASUREMENT_ID_2', { 'groups': 'agency' });
gtag('config', 'GA_MEASUREMENT_ID_3', { 'groups': 'agency' });
// Route this sign_in event to Analytics IDs in the 'agency' group:
gtag('event', 'sign_in', { 'send_to': 'agency' });
Saiba mais sobre como agrupar e enviar dados.
Receber informações quando um evento é enviado
Em alguns casos, você precisa saber quando um evento foi enviado ao Google Analytics. Assim, é possível realizar a ação adequada logo depois do envio. Isso é comum quando você precisa registrar uma interação específica que tiraria o usuário da página atual. Muitos navegadores param de executar o JavaScript assim que a página seguinte começa a ser carregada. Nesses casos, é possível que seus comandos event da biblioteca gtag.js não sejam executados.
Por exemplo, 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 event seja executado.
A solução é interceptar o evento para interromper o carregamento da página seguinte e enviar o evento ao Google Analytics. Após realizar essa ação, envie o formulário de forma programática.
Implementar funções de callback do evento
Você pode implementar uma função de retorno do evento que seja chamada assim que o evento for enviado.
O exemplo a seguir mostra como cancelar a ação de envio padrão de um formulário, enviar um evento ao Google Analytics e, finalmente, reenviar o formulário usando a função de retorno de chamada:
// Get a reference to the form element, assuming
// it contains the ID attribute "signup-form".
var form = document.getElementById('signup-form');
// Add a listener for the "submit" event.
form.addEventListener('submit', function(event) {
// Prevent the browser from submitting the form
// and thus unloading the current page.
event.preventDefault();
// Send the event to Google Analytics and
// resubmit the form once the hit is done.
gtag('event', 'signup_form_complete', {
'event_callback': function() {
form.submit();
}
});
});
Controlar os tempos limites
Há uma desvantagem no exemplo acima: se, por qualquer motivo, houver uma falha no carregamento da biblioteca gtag.js, a função de callback do evento não vai ser executada, e os usuários não poderão enviar o formulário.
Ao inserir funcionalidades críticas do site na função de retorno de chamada do evento, você deve sempre usar uma função de tempo limite para gerenciar os casos em que houver falha no carregamento da biblioteca gtag.js.
O próximo exemplo melhora o código acima e usa um tempo limite. Se um segundo se passar depois que o usuário clicar no botão "Enviar" e a função de retorno de chamada 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);
// Monitors whether or not the form has been submitted.
// This prevents the form from being submitted twice in cases
// where the event callback function 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.
gtag('event', 'signup_form_complete', {
'event_callback': submitForm
});
});
Se você usar o padrão acima em todo o site, provavelmente será 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 padrão é de um segundo), ela limpará o tempo limite e chamará a função de entrada. Se a função retornada não for chamada antes desse período, a função de entrada será chamada 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 envolver todas as funções de retorno de chamada do evento com um tempo limite para garantir que seu site funcione conforme esperado, até mesmo quando os hits não forem enviados ou quando houver falha no carregamento da biblioteca gtag.js.
// 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.
gtag('event', 'signup_form', { 'event_callback': {
createFunctionWithTimeout(function() {
form.submit();
})
}});
});
Especificar mecanismos de transporte diferentes
Por padrão, a gtag.js escolhe o método HTTPS e o mecanismo de transporte usado para enviar hits de modo ideal. Estas são as três opções:
- 'image' (usando um objeto
Image) - 'xhr' (usando um objeto
XMLHttpRequest) - 'beacon' (usando o método
navigator.sendBeacon)
Os dois primeiros métodos compartilham o problema descrito na seção anterior, em que os hits não são enviados quando a página está sendo descarregada. O método navigator.sendBeacon resolve esse problema, transmitindo os hits de forma assíncrona ao servidor da Web sem precisar definir um retorno de hit.
O código a seguir define o mecanismo de transporte como 'beacon' nos navegadores compatíveis:
gtag('config', 'GA_MEASUREMENT_ID', { 'transport_type': 'beacon'});