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.

Ao contrário da analytics.js, a biblioteca gtag.js não usa rastreadores para enviar dados ao Google Analytics. Ela envia dados para as propriedades do Google Analytics identificadas pelos IDs de acompanhamento que são definidos pelo 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 de analytics.js para gtag.js, siga estas etapas para cada página do seu site:

Como substituir o snippet de acompanhamento de analytics.js pelo snippet global de gtag.js

Este é snippet de acompanhamento de analytics.js da sua página da Web que deve ser substituído:

<!-- 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_TRACKING_ID', 'auto');
ga('send', 'pageview');
</script>
<!-- End Google Analytics -->

Substitua-o pelo seguinte snippet global de gtag.js:

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

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

Substitua o valor GA_TRACKING_ID pelo seu próprio ID de acompanhamento.

Como acompanhar as exibições de página

A biblioteca analytics.js usa rastreadores para enviar as exibições de página ao Google Analytics. O rastreador contém o ID de acompanhamento de uma propriedade do Google Analytics. Já a biblioteca gtag.js envia as exibições de página para uma propriedade do Google Analytics identificada pelo valor GA_TRACKING_ID que é especificado por um comando config.

Acompanhar as exibições de página com o rastreador padrão

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

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

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

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

gtag('config', 'GA_TRACKING_ID');

Acompanhar as exibições de página com rastreadores específicos

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

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

Substitua-o pelo seguinte comando gtag.js event:

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

Como acompanhar eventos

Como mencionado anteriormente, a analytics.js usa rastreadores para enviar eventos ao Google Analytics. O rastreador possui o ID de rastreamento de uma propriedade do Google Analytics. Já a biblioteca gtag.js envia os eventos para uma propriedade do Google Analytics identificada pelo valor GA_TRACKING_ID especificado por um comando config.

Acompanhar eventos com o rastreador padrão

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

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

Substitua-o pelo seguinte comando gtag.js event:

gtag('event', eventName, eventParameters);

Nessa estrutura, eventName deve ser o nome do evento que você quer registrar.

Exemplo:

analytic.js:

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

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

gtag.js:

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

Acompanhar eventos com rastreadores específicos

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

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

Substitua-o pelo seguinte comando gtag.js event:

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

Exemplo:

analytics.js:

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

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

gtag.js:

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

Como enviar dimensões e métricas personalizadas

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

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

Substitua-os pelo seguinte código de gtag.js:

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

Substitua o valor GA_TRACKING_ID pelo seu próprio ID de acompanhamento.

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

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

Substitua-os pelo seguinte código de gtag.js:

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

Substitua o valor GA_TRACKING_ID pelo seu próprio ID de acompanhamento.

Como acompanhar a velocidade do usuário

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

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

Substitua-o pelo seguinte comando gtag.js event:

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

Como acompanhar exceções

Substitua os comandos send de 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
});

Substitua-o pelo seguinte comando gtag.js event:

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

Como fazer a correspondência entre os campos de analytics.js e os parâmetros de gtag.js

As tabelas a seguir fazem a correspondência entre os campos de analytics.js e os respectivos parâmetros de 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 de gtag.js
timingCategory event_category
timingLabel event_label
timingValue value
timingVar name

Acompanhamento de exceções

Campo de 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 de gtag.js
clientId client_id
userId user_id