Google Analytics 4

[slorber]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

Google introduced Google Analytics 4 and is going to sunset its former analytics system in July 2023

https://blog.google/products/marketingplatform/analytics/prepare-for-future-with-google-analytics-4/

Analytics data will not be migrated to the new system

For sites that want to migrate to Analytics 4 and keep historical data, they can run both analytics side-by-side so when the former analytics system is shut down, they have enough historical data

For these reasons, we should not wait until the final deadline to support Google Analytics 4 in Docusaurus, and allow sites to seamlessly/incrementally migrate to Analytics 4.

Self-service

• I'd be willing to do some initial work on this proposal myself.

[Josh-Cena]

I've been constantly confused by the Google Analytics system. I think I've asked in multiple places what it takes to support GA4, but to this day I don't know what it would be like 😅

[johnnyreilly]

I'm already using GA 4 with Docusaurus.... (Alongside old GA) Does anything actually need to be done here?

https://github.com/johnnyreilly/blog.johnnyreilly.com/blob/4e824dc2172efca72c075f1dbc3a39a92fd22064/blog-website/docusaurus.config.js#L35

[slorber]

@johnnyreilly you probably know better than us 😅 I didn't read the GA4 doc much.

We should probably document that anyway so that users can migrate incrementally and know what to do

[Josh-Cena]

Ah yes, last time John sent a PR to update our docs to not use the legacy GA tracking ID format. I still have little idea what's going on though...

[johnnyreilly]

Yeah in fact that PR could use a tweak - I provided the wrong format I think. Will check

[johnnyreilly]

Yeah - this one: https://github.com/facebook/docusaurus/pull/6184/files

It's slightly misleading - will correct

[johnnyreilly]

Follow up PR to correct: #7252

[slorber]

So what I understand is that for GA4, we should simply keep using the gtag plugin but only update the trackingId to use a new one?

Will the Docusaurus google-analytics plugin remain useful in 1 year?

What happens if a Docusaurus user was already using gtag plugin with another tracking id (unlike you @johnnyreilly?), and wants a seamless transition

---

IE how will those sites be able to upgrade incrementally without losing the ability to check analytics this year?

https://github.com/facebook/jest/blob/main/website/docusaurus.config.js#L77 (using gtag)
https://github.com/facebook/react-native-website/blob/main/website/docusaurus.config.js#L95 (looks duplicate/weird 🤷‍♂️ )

---

Atm I'm not sure it's possible to run 2 instances of the gtag plugin for example

---

IMHO we should write doc to help users do this transition:

• sites already using gtag plugin
• sites already using google-analytics plugin
• sites that want to setup analytics for the first time

[johnnyreilly]

So I'm no expert but I'll share my experience. Consider my config:

{
        googleAnalytics: {
          trackingID: 'UA-51754530-2',
          anonymizeIP: true,
        },
        gtag: {
          trackingID: 'G-226F0LR9KE',
          anonymizeIP: true,
        }
}

https://github.com/johnnyreilly/blog.johnnyreilly.com/blob/4e824dc2172efca72c075f1dbc3a39a92fd22064/blog-website/docusaurus.config.js#L30

I have googleAnalytics and gtag running side by side. Both are sending traffic. One to a Google analytics instance. One to a GA4 instance. To my knowledge, Google analytics instances will not be migrated to GA4, you have to create a new instance.

My expectation would be that people do what I've done, which is:

• set up a GA4 instance
• start sending traffic to it alongside the existing Google analytics instance if you have one
• know that Google analytics instances will stop working in future

Will the Docusaurus google-analytics plugin remain useful in 1 year?

I would think no

What happens if a Docusaurus user was already using gtag plugin with another tracking id (unlike you @johnnyreilly?), and wants a seamless transition

Is this a real scenario? Also, from Google's language, I'm not sure they're aiming to support seemless transitions

[slorber]

Is this a real scenario?

Jest:

        gtag: {
          trackingID: 'UA-44373548-17',
        },

How does it start sending data to GA4 asap, but also keep sending data to the current instance so that it remains possible to use analytics in the year to come?

[johnnyreilly]

So my own scenario was that I thought I was sending data to GA4 for ages. I just thought it hadn't started showing up yet (they advise the first can take a couple of days to show)

Only later I discovered my config was wrong and it didn't work. But that's my own story - could be worth asking the Jest team if they're getting GA4 data using this approach - they may have more information to share!

[slorber]

I will have to check with @SimenB or Meta, not sure who manage Google Analytics access for Jest 🤪

[SimenB]

No clue. @rickhanlonii maybe knows?

[nikitavoloboev]

I can confirm that using plugin-google-gtag plugin (following instructions there) and putting this web stream starting from G-.. as id works well.

[slorber]

In #8470

I'm deprecating the google-analytics plugin.
Indeed it should become useless in July 2023

Migration instructions from Google: https://developers.google.com/analytics/devguides/migration/ua/analyticsjs-to-gtagjs

Note we are also adding a google-tag-manager plugin.

Both gtag and google-tag-manager have their specific use-cases. It would be hard to document this in-depth and I'm not an expert but:

• Use gtag: if you are looking for a simple replacement for google-analytics
• Use GTM: if you need more advanced things, and particularly give the ability to marketers the autonomy to deploy their own first/third-party trackers through a web interface (careful: marketers can then slow down the site by installing too many things or custom code with perf/security issues)
• It is also possible to use both at the same time afaik

Refer to Google documentation to understand which tag system is for you:
https://developers.google.com/tag-platform
https://support.google.com/tagmanager/answer/7582054?hl=en
(I can agree it's not always easy to figure out)

[slorber]

We deprecated our google-analytics plugin in Docusaurus v2.3: https://docusaurus.io/blog/releases/2.3

The most straightforward replacement is the gtag plugin.

Google says here that the "analytics" (used by our deprecated plugin) is a deprecated library:
https://developers.google.com/analytics/devguides/collection/analyticsjs

By default the Docusaurus plugins only record page view events. We did the analytics => gtag code conversion a long time ago already and provide the gtag plugin.

// old analytics.js code
window.ga('set', 'page',location.pathname + location.search + location.hash);
window.ga('send', 'pageview');

// new gtag.js code
window.gtag('set', 'page_path', location.pathname + location.search + location.hash);
window.gtag('event', 'page_view');

Unless you are window.ga() function yourself, the migration should be straightforward: you should just replace one plugin with another and keep the same tracking id (note: you should now use a GA4 id!).

If you use custom window.ga() calls on your site, make sure to migrate that code to the new gtag API following Google documentation: https://developers.google.com/analytics/devguides/migration/ua/analyticsjs-to-gtagjs

[slorber]

As part of the UA => GA4 transitions, our gtag plugin will now support multiple tracking ids.

This permits you to add your new GA4 property without stopping collecting analytics to your old UA property.

{
  trackingID: ['G-E5CR2Q1XYZ', 'UA-141789XYZ-1'],
}

(the order of ids shouldn't matter)

This should be released in Docusaurus v2.4 a bit later

PR: #8620

[slorber]

Just a reminder that you can now remove your Universal Analytics tracking id, as it's now useless.

We removed it from the Docusaurus site in #9384, and now we have one less 404 request + console error