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

pelo seguinte snippet da gtag.js:

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

  gtag('config', 'TAG_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 métricas de uma propriedade do Analytics. Já a biblioteca gtag.js envia as visualizações a uma propriedade identificada pelo valor TAG_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 enviar (send) as visualizações de página ao Google Analytics:

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

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

O código a seguir no snippet da gtag.js envia automaticamente uma visualização de página à propriedade do Analytics com um ID de tag TAG_ID:

gtag('config', 'TAG_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', 'TAG_ID', 'auto', 'trackerName');
ga('trackerName.send', 'pageview');

pelo seguinte comando event da gtag.js:

gtag('event', 'page_view', { 'send_to': 'TAG_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 TAG_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 enviar (send) os eventos ao Google Analytics:

ga('create', 'TAG_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', 'TAG_ID', 'auto');

// Uses the default tracker to send the event to the
// Google Analytics property with a tag ID of `TAG_ID`.
ga('send', 'event', 'Videos', 'play', 'Fall Campaign');

gtag.js:

// Sends the event to the Google Analytics property with a
// tag ID of `TAG_ID` set by the config command in
// the gtag.js 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', 'TAG_ID', 'auto', 'trackerName');
ga('trackerName.send', 'event', [eventCategory], [eventAction], [eventLabel], [eventValue], [fieldsObject]);

pelo seguinte comando event da gtag.js:

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

Exemplo:

analytics.js:

// Creates a tracker named <b>clientTracker</b>.
ga('create', 'TAG_ID', 'auto', 'clientTracker');

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

gtag.js:

// Send the event to the Google Analytics property
// with a tag ID of 'TAG_ID'.
gtag('event', 'play', {
  'send_to': 'TAG_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', 'TAG_ID', {
  'custom_map': {'dimension<Index>': 'dimension_name'}
});
gtag('event', 'any_event_name', {'dimension_name': 'dimension_value'});

Substitua TAG_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', 'TAG_ID', {
  'custom_map': {'metric<Index>': 'metric_name'}
});
gtag('event', 'any_event_name', {'metric_name': 'metric_value'});

Substitua TAG_ID pelo ID da sua tag.

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 de 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 de gtag.js
timingCategory event_category
timingLabel event_label
timingValue value
timingVar name

Avaliação de exceções

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

Dados de ação de e-commerce 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

Client-ID e User-ID

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