Migrate from analytics.js to gtag.js (Universal Analytics)

This guide walks you through the process of migrating an existing analytics.js Universal Analytics implementation to use gtag.js.

Overview

analytics.js has two main mechanisms for sending data to Google Analytics:

  1. trackers

    Trackers specify which property you are measuring.

  2. hit types

    Hit types specify what type of interaction you are measuring.

In gtag.js properties are specified through the config command, or as a parameter to a command.

Unlike analytics.js, gtag.js doesn't use trackers to send data to Google Analytics. It sends data to Google Analytics properties identified by their IDs set by the config command. The event names supplied to gtag.js specify the types of data being sent to Google Analytics.

To migrate from analytics.js to gtag.js, do the following for every web page of your site:

Replace the analytics.js snippet with the gtag.js snippet

Replace the analytics.js snippet in your web page:

<!-- 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 -->

with the following gtag.js snippet:

<!-- 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>

Measure pageviews

analytics.js uses trackers to send pageviews to Google Analytics. A tracker has the Measurement ID of a Google Analytics property. gtag.js sends pageviews to a Google Analytics property identified by the TAG_ID specified in a config command.

Measure pageviews with the default tracker

Remove the following analytics.js code that uses the default tracker to send pageviews to 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');

The following code in the gtag.js snippet automatically sends a pageview to the Google Analytics property with a tag ID of TAG_ID:

gtag('config', 'TAG_ID');

Measure pageviews with specified trackers

Replace the following analytics.js code that uses the specified tracker to send pageviews to Google Analytics:

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

with the following gtag.js event command:

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

Measure events

As mentioned earlier, analytics.js uses trackers to send events to Google Analytics. A tracker has the tracking ID of a Google Analytics property. By contrast, gtag.js sends events to a Google Analytics property identified by the TAG_ID specified in a config command.

Measure events with the default tracker

Replace the following analytics.js code that uses the default tracker to send events to Google Analytics:

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

with the following gtag.js event command:

gtag('event', eventName, eventParameters);

where eventName is the name of the event you want to log.

Example:

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

Measure events with specified trackers

Replace the following analytics.js code that uses the specified tracker to send events to Google Analytics:

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

with the following gtag.js event command:

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

Example:

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

Send custom dimensions and metrics

Replace any analytics.js send command in your web pages that sends custom dimensions to Google Analytics:

ga('send', 'hitType', { 'dimension&lt;Index&gt;':  'dimension_value'});

with the following gtag.js code:

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

Replace TAG_ID with your own Analytics ID.

Replace any analytics.js send command in your web pages that send custom metrics to Google Analytics:

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

with the following gtag.js code:

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

Replace TAG_ID with your tag ID.

Measure user timings

Replace any analytics.js send command in your web pages that tracks user timings:

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

with the following gtag.js event command:

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

Measure exceptions

Replace any analytics.js send command in your web pages that tracks exceptions:

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

with the following gtag.js event command:

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

Map analytics.js fields to gtag.js parameters

The following tables map analytics.js fields to the corresponding gtag.js parameters.

Events

analytics.js field gtag.js parameter
eventAction event_action
eventCategory event_category
eventLabel event_label
eventValue value

Custom dimensions and metrics

analytics.js field gtag.js parameter
dimension<Index> dimension<Index>
metric<Index> metric<Index>

where <Index> is a non-negative integer representing the index of the custom dimension or metric.

User timings

analytics.js field gtag.js parameter
timingCategory event_category
timingLabel event_label
timingValue value
timingVar name

Exception measurement

analytics.js field gtag.js parameter
exDescription description
exFatal fatal

Enhanced ecommerce action data

analytics.js field gtag.js parameter
id transaction_id
affiliation affiliation
revenue value
tax tax
shipping shipping
coupon coupon
list list_name
step checkout_step
option checkout_option

Promotion data

analytics.js field gtag.js parameter
creative creative_name
position (impression, product) list_position
position (promotion) creative_slot

Product and promotion actions

analytics.js field gtag.js event
add add_to_cart
checkout (first step) begin_checkout
checkout (any subsequent step) checkout_progress
checkout_option set_checkout_option
click select_content (without promotions)
detail view_item
promo_click select_content (with promotions)
purchase purchase
refund refund
remove remove_from_cart

Client ID and user ID

analytics.js field gtag.js parameter
clientId client_id
userId user_id