Migrar da analytics.js para a gtag.js (Universal Analytics)

Este guia explica o processo de migração de uma implementação atual da tag analytics.js do Universal Analytics para usar a gtag.js.

Visão geral

A analytics.js tem dois mecanismos principais para enviar dados ao Google Analytics:

  1. Rastreadores

    Os rastreadores especificam a propriedade que você está medindo.

  2. Tipos de hit

    Os tipos de hit especificam o tipo de interação que você está medindo.

Na gtag.js, as propriedades são especificadas pelo comando config ou como um parâmetro de um comando.

Diferente da analytics.js, a biblioteca gtag.js não usa rastreadores para enviar dados ao Google Analytics. Ela envia informações às propriedades identificadas pelos IDs definidos pelo comando config. Os nomes de eventos informados à 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 na 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>

Medir 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 ID de acompanhamento de uma propriedade do Analytics. Já a biblioteca gtag.js envia as exibições de página a uma propriedade do Analytics identificada pelo valor GA_MEASUREMENT_ID, que é especificado por um comando config.

Medir 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 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 global da gtag.js envia automaticamente uma exibição de página à propriedade do Analytics com o ID de acompanhamento GA_MEASUREMENT_ID:

gtag('config', 'GA_MEASUREMENT_ID');

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

Substitua o código da analytics.js a seguir que usa o rastreador especificado 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' });

Medir os eventos

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

Medir os eventos com o rastreador padrão

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

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

pelo seguinte comando da gtag.jsevent:

gtag('event', eventName, eventParameters);

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

Exemplo:

analytics.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'
});

Medir os eventos com rastreadores específicos

Substitua o código da analytics.js a seguir que usa o rastreador especificado 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 <b>clientTracker</b>.
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&lt;Index&gt;':  '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 ID do Google Analytics.

Substitua os comandos send da analytics.js nas suas páginas da Web que enviam métricas personalizadas 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 ID do Google Analytics.

Medir a velocidade do usuário

Substitua os comandos send da analytics.js nas suas páginas da Web que rastreiam 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'
});

Medir as exceções

Substitua os comandos send da analytics.js nas suas páginas da Web que rastreiam exceções:

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

pelo seguinte comando da gtag.jsevent:

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 da gtag.js
dimension<Index> dimension<Index>
metric<Index> metric<Index>

em que <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 da 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