Update Google Analytics to gtag

[nemchik]

I checked that...

• ... the documentation does not mention anything about my idea
• ... to my best knowledge, my idea wouldn't break something for other users
• ... there are no open or closed issues that are related to my idea

Description

Google has been sending me emails that analytics.js is being replaced by gtag.js and has a new code snip to use it.

Possibly related (although I think they are talking about a different feature, unless Google combined these): #1914

Use Cases

Anyone receiving the emails to update would stop receiving the emails 😄

Apparently Google lists the selling points as:

• Future-proof conversion measurement: Benefit from the latest features and integrations as they become available so that you'll be better equipped to continue measuring conversions accurately if non-Google changes occur.
• Code-less tag management: Turn measurement features on and off within your Google Analytics account without having to manually change tags on your page.
• Faster and easier integration: Seamlessly implement and integrate with other Google products, such as Google Ads and Google Optimize.

Screenshots / Mockups

<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-#######-#"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());

  gtag('config', 'UA-#######-#');
</script>

[squidfunk]

We did this in 9d46c27, released as part of 3.3.0 and reverted it in 4.0.0. I can't really remember why we reverted, as it's been 1.5 years ago, but I think it was after a discussion with @coliff.

[coliff]

I just responded to a similar issue on the Hugo repo a few days ago. :-)

Basically, switching to gtag.js means approx 262% more code and extra HTTP requests.
REF: googleanalytics/autotrack#202 (comment)

One of the other reasons I preferred the analytics.js implementation was that it supports tasks and plugins - including Google's AutoTrack library- a really neat collection of plugins for tracking many things - but sadly it was recently discontinued. :-(

I realise that Google are starting to push gtag more, so maybe they will discontinue the analytics.js implementation in the future, but as of right now it is still supported and I think a more efficient way of tracking analytics. I don't mind if @squidfunk wants to switch the implementation to gtag now though - it doesn't really make a big difference performance wise and they both load async.

[squidfunk]

@coliff thanks for the quick analysis! 262% is quite a number. We won't switch until this number goes way down or analytics.js is completely discontinued. However, replacing the current implementation is fairly simple by overriding template blocks and providing your own implementation. The documentation explains how to do that.

Additionally, introducing gtag.js will increase the risk of missing data, as there are now two files being loaded:

• index.html → analytics.js (33.7k)
• index.html → gtag.js (54.5k) → analytics.js (33.7k)

Thus, it makes no sense to switch the default integration at this moment. Closing.

[nemchik]

Just for fun I did some testing.

In my testing:

• The new gtag.js code does not seem to load analytics.js (rather I believe it it meant to replace it).
• I used Google Chrome's DevTools -> Network tab to measure gtag.js as:
  18 requests
  250 kB transferred
  579 kB resources
  Finish: 1.05 s
  DOMContentLoaded: 576 ms
  Load: 919 ms
• I used Google Chrome's DevTools -> Network tab to measure analytics.js as:
  16 requests
  159 kB transferred
  375 kB resources
  Finish: 858 ms
  DOMContentLoaded: 615 ms
  Load: 805 ms

Not overly scientific. I just loaded and reloaded the page a few times with each version of the code and randomly stopped reloading and copied the results. I didn't record or average results. Just wanted to see after reloading (letting cache kick in) how it would perform.

I can absolutely see the difference in size and the extra few requests with the new code, but looking at the big picture the new code is roughly 1/10th of a second slower to load and around 200kB bigger (although a direct comparison of the file sizes of the individual js files doesn't reflect exactly the difference in what is loaded by the browser: gtag.js is 98,304 bytes and analytics.js is 49,152 bytes). Those are honestly not the kind of numbers I would expect to break anyone's heart, and I'm sure Google has a similar mindset.

I agree with what seems to be a removed comment someone else made that I am copying from the email notification and reposting:

coliff is referencing a comment from 3 years ago. If Google's advice is to use gtag (and they are sending out emails to prompt web site owners to upgrade), I don't understand why that isn't the default. If there is merit to offer both, then why not provide both -- and it would be great if it could assert if the developer is doing something wrong, like loading both.

Personally I don't care about both being offered. I imagine anyone who wants to enable Google Analytics is looking to do so by using the code Google provides/recommends. I would think that with Google sending out nag emails for people to switch that it makes more sense to include the new code and provide the template override instructions to anyone who comes asking "how do I switch back". I imagine the number of people who come asking that would probably be less than the number coming to mention they are getting nag emails. 🤷

That's just my 2c though.

[squidfunk]

First, thanks for taking the time to investigate. Actual measuring is always better than guessing, and I'm a huge fan of generating some data to come to an informed decision.

Here's the data you generated again side-by-side for better comparison:

Metric	gtag.js	Delta	analytics.js
Requests	18	2	16
Transferred	250 kB	+91 kB	159 kB
Assets	579 kB	+204 kB	375 kB
DOMContentLoaded	576 ms	-39 ms	615 ms
Load	919 ms	+114 ms	805 ms
Finish	1.05 s	+192 ms	858 ms

Most numbers have increased by a significant amount. DOMContentLoaded dropped, which seems counter-intuitive given that all other times increased - might be a measuring error.

I can absolutely see the difference in size and the extra few requests with the new code, but looking at the big picture, the new code is roughly 1/10th of a second slower to load and around 200kB bigger (although a direct comparison of the file sizes of the individual js files doesn't reflect exactly the difference in what is loaded by the browser: gtag.js is 98,304 bytes and analytics.js is 49,152 bytes). Those are honestly not the kind of numbers I would expect to break anyone's heart, and I'm sure Google has a similar mindset.

It seems you measured without setting network conditions (i.e., throttling). It's always good to measure using "Fast 3G" and "Slow 3G" to estimate how the site behaves on slower mobile connections (e.g., in emerging markets or Germany - the mobile Internet sucks here!). I'd guess that Load and Finish times will be way, way higher on slower connections if you measure with network throttling.

An increase of 200 kB is extremely substantial. With the release of 6.0.1, I was able to decrease the overall JavaScript payload of Material from 176 kB to 124 kB (see this tweet for a detailed explanation) – so the whole of Material for MkDocs weighs 124 kB. This includes the RxJS code, ClipboardJS, a ResizeObserver polyfill, etc. Adding 200 kB, which would be 160% of the theme's payload, seems not a good idea to me. If I've learned one thing from the last 4 1/2 years maintaining this project, it's that people are very, very sensitive to changes. It's very hard to estimate what will trip up the users. A change of this magnitude for literally no upside, only downsides through increased load times and worse Lighthouse benchmarks (another thing people are taking very seriously) doesn't sound great to me.

coliff is referencing a comment from 3 years ago. If Google's advice is to use gtag (and they are sending out emails to prompt web site owners to upgrade), I don't understand why that isn't the default. If there is merit to offer both, then why not provide both -- and it would be great if it could assert if the developer is doing something wrong, like loading both.

I was also wondering about the removed comment. I also got that email. Yes, Google's advice is to use gtag, but it's so much worse than analytics.js, so it seems like a bait-and-switch. Google has a long history of deprecating stuff that people use for potentially worse alternatives.

Personally I don't care about both being offered. I imagine anyone who wants to enable Google Analytics is looking to do so by using the code Google provides/recommends. I would think that with Google sending out nag emails for people to switch that it makes more sense to include the new code and provide the template override instructions to anyone who comes asking "how do I switch back".

I care about both being offered because I'm the one who has to maintain it after all. Google Analytics is only integrated natively because MkDocs offered it from version 0.x as part of the mkdocs.yml. People already asked about alternative Analytics providers like Piwik. As I already noted, it's very easy to "bring your own" as the theme is very hackable and extendable, which is why I've invested a lot of time in detailing possibilities for customization in the documentation.

I imagine the number of people who come asking that would probably be less than the number coming to mention they are getting nag emails. 🤷

You're the first one. I'm running Google Analytics on some sites and haven't noticed so far.

[nemchik]

@squidfunk sorry to necro this, but I am attempting to help a friend setup an mkdocs deployment with google analytics and it appears he is not able to setup anything except Google Analytics V4 which no longer provides a UA-##### and instead seems to require the use of gtags. since new GA users are forced to GA4 and existing users (myself included) are being sent emails from google urging them to upgrade it's probably a good idea to reconsider this.

P.S. I upgraded one of my less important GA properties to GA4 and it no longer has a UA-##### and now only has the option to use gtags, which seem to give a measurement ID in the format G-ABC123.

[nemchik]

For those who find this, I've opened an issue upstream mkdocs/mkdocs#2252 requesting support for ga4 in mkdocs.

[squidfunk]

gtag.js support just landed in master and will be released soon. Feedback appreciated. Now, both formats are supported.

Google Analytics

extra:
  analytics:
    provider: google
    property: UA-XXXXXXXX-X

Google Analytics 4 (via gtag.js)

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX