Use gtag.js analytics library for all site tags

CHANGELOG.md

@@ -1,5 +1,5 @@
 <!--
-  cSpell:ignore docsy
+  cSpell:ignore deining docsy gtag
 -->
 
 # Changelog
@@ -33,9 +33,16 @@ notes][0.5.0]. **BREAKING CHANGES** are documented below.
   upgrade. You might notice other width changes of elements using FA icons and
   the FA font.
 
+**Other changes**:
+
+- By default, Docsy now uses the [gtag.js][] analytics library for all site
+  tags. For details, see [Adding Analytics > Setup][].
+
+[Adding Analytics > Setup]: https://www.docsy.dev/docs/adding-content/feedback/#setup
 [v4.6.2 release notes]: https://github.com/twbs/bootstrap/releases/tag/v4.6.2
 [docsy as an npm package]:
   https://www.docsy.dev/docs/get-started/other-options/#option-3-docsy-as-an-npm-package
+[gtag.js]: https://support.google.com/analytics/answer/10220869
 [upgraded fontawesome]: https://fontawesome.com/docs/web/setup/upgrade/
 [what's changed]: https://fontawesome.com/docs/web/setup/upgrade/whats-changed
 

layouts/_internal/google_analytics_gtag.html

@@ -0,0 +1,42 @@
+{{/*
+
+  This is a modified copy of
+
+  https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/google_analytics.html,
+
+  specifically this version:
+
+  https://github.com/gohugoio/hugo/blob/f7e00c039ff3cea5f991b05c1e325666004cf129/tpl/tplimpl/embedded/templates/google_analytics.html
+
+  The only differences between this copy and the original are that we've dropped:
+
+  - The `{{ if hasPrefix . "G-"}}` condition
+  - The `{{ else }}` block
+  - The `anonymize_ip` argument to the `gtag()` call, since it is superfluous.
+    For details, see https://github.com/gohugoio/hugo/issues/10093.
+
+*/}}
+
+{{- $pc := .Site.Config.Privacy.GoogleAnalytics -}}
+{{- if not $pc.Disable }}{{ with .Site.GoogleAnalytics -}}
+<script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
+<script>
+{{ template "__ga_js_set_doNotTrack" $ }}
+if (!doNotTrack) {
+	window.dataLayer = window.dataLayer || [];
+	function gtag(){dataLayer.push(arguments);}
+	gtag('js', new Date());
+	gtag('config', '{{ . }}');
+}
+</script>
+{{- end }}{{ end -}}
+
+{{- define "__ga_js_set_doNotTrack" -}}{{/* This is also used in the async version. */}}
+{{- $pc := .Site.Config.Privacy.GoogleAnalytics -}}
+{{- if not $pc.RespectDoNotTrack -}}
+var doNotTrack = false;
+{{- else -}}
+var dnt = (navigator.doNotTrack || window.doNotTrack || navigator.msDoNotTrack);
+var doNotTrack = (dnt == "1" || dnt == "yes");
+{{- end -}}
+{{- end -}}

layouts/partials/head.html

@@ -45,8 +45,9 @@
 
 {{/* To comply with GDPR, cookie consent scripts places in head-end must execute before Google Analytics is enabled */ -}}
 {{ if hugo.IsProduction -}}
-  {{ if hasPrefix .Site.GoogleAnalytics "G-" -}}
-    {{ template "_internal/google_analytics.html" . -}}
+  {{ $enableGtagForUniversalAnalytics := not .Site.Params.disableGtagForUniversalAnalytics -}}
+  {{ if (or $enableGtagForUniversalAnalytics (hasPrefix .Site.GoogleAnalytics "G-")) -}}
+    {{ template "_internal/google_analytics_gtag.html" . -}}
   {{ else -}}
     {{ template "_internal/google_analytics_async.html" . -}}
   {{ end -}}

userguide/content/en/docs/adding-content/feedback.md

@@ -33,6 +33,11 @@ started** section of [Introducing Google Analytics 4 (GA4)][ga4-intro].
 Enable Google Analytics by adding your project's analytics ID to the site
 configuration file. For details, see [Configure Google Analytics][].
 
+By default, Docsy uses the [gtag.js][] analytics library for both GA4 (which
+_requires_ `gtag.js`) and Universal Analytics (UA) site tags. If you prefer using
+the older `analytics.js` library for your UA site tag, then set
+`params.disableGtagForUniversalAnalytics` to true in your project's config.
+
 {{% alert title="Warning" color="warning" %}}
   <!-- Remove this warning once the Hugo docs have been updated to include it. -->
 
@@ -289,6 +294,7 @@ partial. For details, see [Customizing templates]({{< ref "lookandfeel#customizi
 [Configure Google Analytics]: https://gohugo.io/templates/internal/#configure-google-analytics
 [ga4-intro]: https://support.google.com/analytics/answer/1042508
 [Google Analytics]: https://analytics.google.com/analytics/web/
+[gtag.js]: https://support.google.com/analytics/answer/10220869
 [hugo-ga]: https://gohugo.io/templates/internal/#google-analytics
 [internal templates]: https://gohugo.io/templates/internal/
 [layouts/partials/page-description.html]: https://github.com/google/docsy/blob/main/layouts/partials/page-description.html