Migrar de analytics.js para gtag.js

Se você já conhece a biblioteca analytics.js, é recomendável entender algumas diferenças entre analytics.js e gtag.js. Esta página fornece uma visão geral de algumas das principais diferenças e apresenta dicas sobre como migrar de analytics.js para gtag.js.

Visão geral

A biblioteca analytics.js usa rastreadores para enviar dados ao Google Analytics e tipos de hits para especificar os tipos desses dados.

Diferente da analytics.js, a biblioteca gtag.js não usa rastreadores para enviar dados ao Google Analytics. Ela envia dados para as propriedades identificadas pelos códigos definidos por meio do comando config. Os nomes de eventos fornecidos para a gtag.js especificam os tipos de dados que são enviados ao Google Analytics.

Para migrar da analytics.js para a gtag.js, siga estas etapas em cada página do seu site:

Substituir o snippet da analytics.js pelo snippet da gtag.js

Substitua o snippet da analytics.js a seguir da sua página da Web:

<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

ga('create', 'GA_MEASUREMENT_ID', 'auto');
ga('send', 'pageview');
</script>
<!-- End Google Analytics -->

pelo seguinte snippet da gtag.js:

<!-- Global Site Tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'GA_MEASUREMENT_ID');
</script>

Substitua GA_MEASUREMENT_ID pelo seu próprio código do Google Analytics.

Avaliar as visualizações de página

A biblioteca analytics.js usa rastreadores para enviar as visualizações de página ao Google Analytics. O rastreador contém o código de avaliação de uma propriedade do Google Analytics. Já a gtag.js envia as visualizações para uma propriedade do Google Analytics identificada pelo GA_MEASUREMENT_ID, que é especificado por um comando config.

Avaliar as visualizações de página com o rastreador padrão

Remova o código da analytics.js a seguir que usa o rastreador padrão para enviar (send) as visualizações de página ao Google Analytics:

// Creates the default tracker.
ga('create', 'GA_MEASUREMENT_ID', 'auto');

// Uses the default tracker to send a pageview to the
// Google Analytics property with tracking ID GA_MEASUREMENT_ID.
ga('send', 'pageview');

O código a seguir contido no snippet de acompanhamento global da gtag.js envia automaticamente uma visualização de página para a propriedade do Google Analytics com o código GA_MEASUREMENT_ID:

gtag('config', 'GA_MEASUREMENT_ID');

Avaliar as visualizações de página com rastreadores específicos

Substitua o código da analytics.js a seguir que usa o rastreador específico para enviar as visualizações de página ao Google Analytics:

ga('create', 'GA_MEASUREMENT_ID', 'auto', 'trackerName');
ga('trackerName.send', 'pageview');

pelo seguinte comando event da gtag.js:

gtag('event', 'page_view', { 'send_to': 'GA_MEASUREMENT_ID' });

Avaliar os eventos

Como mencionado anteriormente, a analytics.js usa rastreadores para enviar eventos ao Google Analytics. O rastreador contém o ID de acompanhamento de uma propriedade do Google Analytics. Já a biblioteca gtag.js envia os eventos para uma propriedade do Google Analytics identificada pelo GA_MEASUREMENT_ID, que é especificado por um comando config.

Avaliar os eventos com o rastreador padrão

Substitua o código da analytics.js a seguir que usa o rastreador padrão para enviar (send) os eventos ao Google Analytics:

ga('create', 'GA_MEASUREMENT_ID', 'auto');
ga('send', 'event', [eventCategory], [eventAction], [eventLabel], [eventValue], [fieldsObject]);

pelo seguinte comando event da gtag.js:

gtag('event', eventName, eventParameters);

em que eventName é o nome do evento que você quer registrar.

Exemplo:

analytic.js:

// Creates the default tracker.
ga('create', 'GA_MEASUREMENT_ID', 'auto');

// Uses the default tracker to send the event to the
// Google Analytics property with tracking ID GA_MEASUREMENT_ID.
ga('send', 'event', 'Videos', 'play', 'Fall Campaign');

gtag.js:

// Sends the event to the Google Analytics property with
// tracking ID GA_MEASUREMENT_ID set by the config command in
// the global tracking snippet.
gtag('event', 'play', {
  'event_category': 'Videos',
  'event_label': 'Fall Campaign'
});

Avaliar os eventos com rastreadores específicos

Substitua o código da analytics.js a seguir que usa o rastreador específico para enviar os eventos ao Google Analytics:

ga('create', 'GA_MEASUREMENT_ID', 'auto', 'trackerName');
ga('trackerName.send', 'event', [eventCategory], [eventAction], [eventLabel], [eventValue], [fieldsObject]);

pelo seguinte comando event da gtag.js:

gtag('event', eventName, {
  'send_to': 'GA_MEASUREMENT_ID',
  'parameter1': 'value1',
  'parameter2': 'value2',
  // ...
});

Exemplo:

analytics.js:

// Creates a tracker named clientTracker.
ga('create', 'GA_MEASUREMENT_ID', 'auto', 'clientTracker');

// Uses tracker clientTracker to send the event to the
// Google Analytics property with tracking ID GA_MEASUREMENT_ID.
ga('clientTracker.send', 'event', 'Videos', 'play', 'Fall Campaign');

gtag.js:

// Send the event to the Google Analytics property
// with tracking ID GA_MEASUREMENT_ID.
gtag('event', 'play', {
  'send_to': 'GA_MEASUREMENT_ID',
  'event_category': 'Videos',
  'event_label': 'Fall Campaign'
});

Enviar dimensões e métricas personalizadas

Substitua os comandos send da analytics.js nas suas páginas da Web que enviam dimensões personalizadas ao Google Analytics:

ga('send', 'hitType', { 'dimension<Index>':  'dimension_value'});

pelo seguinte código da gtag.js:

gtag('config', 'GA_MEASUREMENT_ID', {
  'custom_map': {'dimension<Index>': 'dimension_name'}
});
gtag('event', 'any_event_name', {'dimension_name': 'dimension_value'});

Substitua GA_MEASUREMENT_ID pelo seu próprio código do Google Analytics.

Substitua os comandos send da analytics.js das suas páginas da Web que enviam eventos personalizados ao Google Analytics:

ga('send', 'hitType', { 'metric<Index>':  'metric_value'});

pelo seguinte código da gtag.js:

gtag('config', 'GA_MEASUREMENT_ID', {
  'custom_map': {'metric<Index>': 'metric_name'}
});
gtag('event', 'any_event_name', {'metric_name': 'metric_value'});

Substitua GA_MEASUREMENT_ID pelo seu próprio código do Google Analytics.

Avaliar a velocidade do usuário

Substitua os comandos send da analytics.js das suas páginas da Web que acompanham a velocidade do usuário:

ga('send', 'timing', 'timingCategory', 'timingVar', timingValue, 'timingLabel');

pelo seguinte comando gtag.js event:

gtag('event', 'timing_complete', {
  'name': 'timingVar',
  'value': timingValue,
  'event_category': 'timingCategory',
  'event_label': 'timingLabel'
});

Avaliar as exceções

Substitua os comandos send da analytics.js das suas páginas da Web que acompanham as exceções:

ga('send', 'exception', {
  'exDescription': 'error_message',
  'exFatal': false  // set to true if the exception is fatal
});

pelo seguinte comando event da gtag.js:

gtag('event', 'exception', {
  'description': 'error_message',
  'fatal': false  // set to true if the exception is fatal
});

Fazer a correspondência entre os campos da analytics.js e os parâmetros da gtag.js

As tabelas a seguir fazem a correspondência entre os campos da analytics.js e os respectivos parâmetros da gtag.js.

Eventos

Campo de analytics.js Parâmetro de gtag.js
eventAction event_action
eventCategory event_category
eventLabel event_label
eventValue value

Dimensões e métricas personalizadas

Campo de analytics.js Parâmetro de gtag.js
dimension<Index> dimension<Index>
metric<Index> metric<Index>

Nesse exemplo, <Index> é um número inteiro não negativo que representa o índice da dimensão ou métrica personalizada.

Velocidade do usuário

Campo de analytics.js Parâmetro da gtag.js
timingCategory event_category
timingLabel event_label
timingValue value
timingVar name

Avaliação de exceções

Campo da analytics.js Parâmetro de gtag.js
exDescription description
exFatal fatal

Dados de ação de comércio eletrônico avançado

Campo de analytics.js Parâmetro de gtag.js
id transaction_id
affiliation affiliation
revenue value
tax tax
shipping shipping
coupon coupon
list list_name
step checkout_step
option checkout_option

Dados da promoção

Campo de analytics.js Parâmetro de gtag.js
creative creative_name
position (impressão, produto) list_position
position (promoção) creative_slot

Ações do produto e da promoção

Campo de analytics.js Evento de gtag.js
add add_to_cart
checkout (primeira etapa) begin_checkout
checkout (qualquer etapa subsequente) checkout_progress
checkout_option set_checkout_option
click select_content (sem promoções)
detail view_item
promo_click select_content (com promoções)
purchase purchase
refund refund
remove remove_from_cart

Código do cliente e User ID

Campo de analytics.js Parâmetro da gtag.js
clientId client_id
userId user_id