Google Analytics – Analytics.js script translation helper

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 does not 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 implementation of your external scripts.

1. Replace the analytics.js script with the gtag.js script.

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

Replace the analytics.js script in your external scripts administration.
with the following gtag.js script:

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

‘TAG_ID’ means the MEASUREMENT ID of your GA4 property.

2. Replace analytics.js code with equivalent gtag.js code to:

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

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 as written above.

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 script 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.

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

// 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 following gtag.js event command:

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

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

// 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 external script 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 any analytics.js send command in your external scripts that sends 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'});

Measure user timings

Replace any analytics.js send command in your external scripts that tracks user timings:

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

with 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 external scripts 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

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