Debugging

This guide explains how to use the debug version of the analytics.js library to ensure your implementations are working correctly.

The debug version of the analytics.js library

Google Analytics provides a debug version of the analytics.js library that logs detailed messages to the Javascript console as its running. These messages include successfully executed commands as well as warnings and error messages that can tell you when your tag is set up incorrectly. It also provides a breakdown of each hit sent to Google Analytics, so you can see exactly what data is being captured.

You can enable the debug version of analytics.js by changing the URL in the JavaScript tag from https://www.google-analytics.com/analytics.js to https://www.google-analytics.com/analytics_debug.js:

(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_debug.js','ga');

ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');

Testing your implementation without sending hits

The debug version of analytics.js will send data to Google Analytics exactly like the non-debug version. This allows you to visit a website running analytics.js code and inspect the implementation without interfering with how data is captured.

If you do not want to send data to Google Analytics in certain cases (e.g. development or testing environments), you can disable the sendHitTask task and nothing will be sent.

When running on localhost, the following code will prevent any hits from being sent to Google Analytics:

(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_debug.js','ga');

ga('create', 'UA-XXXXX-Y', 'auto');

if (location.hostname == 'localhost') {
  ga('set', 'sendHitTask', null);
}

ga('send', 'pageview');

Trace debugging

Enabling trace debugging will output more verbose information to the console.

To enable trace debugging, load the debug version of analytics.js as described above and add the following line of JavaScript prior to any calls to the ga() command queue.

window.ga_debug = {trace: true};

The full tag with trace debugging enabled is as follows:

(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_debug.js','ga');

window.ga_debug = {trace: true};
ga('create', 'UA-XXXXX-Y', 'auto');
ga('send', 'pageview');

The Google Analytics Debugger Chrome extension

Google Analytics also provides a Chrome extension that can enable the debug version of analytics.js without requiring you to change your tag. This allows you to debug your own sites and also see how other sites have implemented Google Analytics with analytics.js.

Google Tag Assistant

Google Tag Assistant is a Chrome Extension that helps you validate the tag on your website and troubleshoot common problems. It's an ideal tool for debugging and testing your analytics.js implementations locally and ensuring everything is correct before deploying your code to production.

Tag Assistant works by letting you record a typical user flow. It collects all the hits you send, checks them for any problems, and gives you a full report of the interactions. If it detects any issues or potential improvements, it will let you know.

To learn more, visit the help center and read About Tag Assistant and About Tag Assistant Recordings. You can also watch this demo video that shows Tag Assistant being used to catch errors and check the validity of advanced implementations such as cross-domain measurement.