Migrate from analytics.js to gtag.js

If you're experienced with analytics.js, you will find it helpful to understand some of the differences between analytics.js and gtag.js. This guide gives an overview of some of those key differences and provides tips on how to migrate from analytics.js to gtag.js.

Overview

analytics.js uses (1) trackers to send data to Google Analytics and (2) hit types to specify the types of the data.

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 tracking 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:

Replacing the analytics.js tracking snippet with the gtag.js global snippet

Replace the analytics.js tracking 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', 'GA_TRACKING_ID', 'auto');
ga('send', 'pageview');
</script>
<!-- End Google Analytics -->

with the following gtag.js global snippet:

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

Replace GA_TRACKING_ID with your own tracking ID.

Tracking pageviews

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

Track 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', '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');

The following code in the gtag.js global tracking snippet automatically sends a pageview to the Google Analytics property with tracking ID GA_TRACKING_ID:

gtag('config', 'GA_TRACKING_ID');

Track pageviews with specified trackers

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

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

with the following gtag.js event command:

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

Tracking 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 GA_TRACKING_ID specified in a config command.

Track events with the default tracker

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

ga('create', 'GA_TRACKING_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:

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

Track events with specified trackers

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

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

with the following gtag.js event command:

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

Example:

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

Sending 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<Index>':  'dimension_value'});

with the following gtag.js code:

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

Replace GA_TRACKING_ID with your own tracking 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', 'GA_TRACKING_ID', {
  'custom_map': {'metric<Index>': 'metric_name'}
});
gtag('event', 'any_event_name', {'metric_name': 'metric_value'});

Replace GA_TRACKING_ID with your own tracking ID.

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

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

Mapping 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 tracking

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

Production and promotion actions

analytics.js field gtag.js eventName
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