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 analytics.js code with equivalent gtag.js code to:

  • Measure pageviews
  • Measure events
  • Send custom dimensions and metrics
  • Measure user timings
  • Measure exceptions

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<Index>':  '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

Custom dimensions and metrics

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

User timings

Exception measurement

Enhanced ecommerce action data

Promotion data

Product and promotion actions

Client ID and user ID