From 9bccf07faab575f9d26dce3b4d4c8c8c2c4c9f8d Mon Sep 17 00:00:00 2001
From: Michelle Blanchette
 <33374343+MichelleBlanchette@users.noreply.github.com>
Date: Sun, 18 Dec 2022 02:43:55 -0500
Subject: [PATCH] analytics: support multiple tracking IDs, document UA -> GA4
 switch (#1029)

* Issue #1023 - note that GA4 properties are supported

* Issue #1023 - parameterize Google Analytics property script

* Issue #1023 - support a list of multiple Google Analytics tracking IDs in config

* Issue #1023 - update Google Analytics configuration doc

* Fix configuration of multiple Google Analytics properties and simplify type checking

* simplify unnecessary code repetition

* tweak Google Analytics config documentation wording
---
 _config.yml           |  2 +-
 _includes/head.html   |  8 +++++---
 docs/configuration.md | 17 ++++++++++++++---
 3 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/_config.yml b/_config.yml
index a032c41..86706fb 100644
--- a/_config.yml
+++ b/_config.yml
@@ -147,7 +147,7 @@ callouts:
     color: red
 
 # Google Analytics Tracking (optional)
-# e.g, UA-1234567-89
+# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
 ga_tracking: UA-2709176-10
 ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
 
diff --git a/_includes/head.html b/_includes/head.html
index 0added6..f71e7ea 100644
--- a/_includes/head.html
+++ b/_includes/head.html
@@ -5,15 +5,17 @@
   <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}">
 
   {% if site.ga_tracking != nil %}
-    <script async src="https://www.googletagmanager.com/gtag/js?id={{ site.ga_tracking }}"></script>
+    {% assign ga_tracking_ids = site.ga_tracking | split: "," %}
+    <script async src="https://www.googletagmanager.com/gtag/js?id={{ ga_tracking_ids.first }}"></script>
     <script>
       window.dataLayer = window.dataLayer || [];
       function gtag(){dataLayer.push(arguments);}
       gtag('js', new Date());
 
-      gtag('config', '{{ site.ga_tracking }}'{% unless site.ga_tracking_anonymize_ip == nil %}, { 'anonymize_ip': true }{% endunless %});
+      {% for ga_property in ga_tracking_ids %}
+        gtag('config', '{{ ga_property }}'{% unless site.ga_tracking_anonymize_ip == nil %}, { 'anonymize_ip': true }{% endunless %});
+      {% endfor %}
     </script>
-
   {% endif %}
 
   {% if site.search_enabled != false %}
diff --git a/docs/configuration.md b/docs/configuration.md
index 78f609e..c5c35ae 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -210,11 +210,22 @@ See [Callouts]({{ site.baseurl }}{% link docs/ui-components/callouts.md %}) for
 
 ## Google Analytics
 
+{: .warning }
+> [Google Analytics 4 will replace Universal Analytics](https://support.google.com/analytics/answer/11583528). On **July 1, 2023**, standard Universal Analytics properties will stop processing new hits. The earlier you migrate, the more historical data and insights you will have in Google Analytics 4.
+
+Universal Analytics (UA) and Google Analytics 4 (GA4) properties are supported.
+
 ```yaml
 # Google Analytics Tracking (optional)
-# e.g, UA-1234567-89
-ga_tracking: UA-5555555-55
-ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default)
+# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
+ga_tracking: UA-2709176-10
+ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
+```
+
+This theme supports multiple comma-separated tracking IDs. This helps seamlessly transition UA properties to GA4 properties by tracking both for a while.
+
+```yaml
+ga_tracking: "UA-1234567-89,G-1AB234CDE5"
 ```
 
 ## Document collections