feat(docs-infra): set up Google Analytics 4 along with keeping legacy Universal Analytics

We currently use Universal Analytics. This is deprecated in favor of
Google Analytics 4 and UA will stop processing hits in October 2023.

This change intends to prepare us for this migration, and to already
pre-populate our GA4 property (there is no way to migrate existing data
/properties into a GA4 property -- a new one needs to be created).

This will help us minimize the data gap so that we can:

* Continue to look at the UA property with the full time span until
  October 2023
* Can start using the GA4 property long-term in the future, starting
  with data even before Universal Analytics stops processing new data.

We need to keep the existing `analytics.js` setup. Initially we have
considered using `gtag.js` for both the UA and GA4 properties, as it
supports that, but that doesn't work with our strict trusted types
enforcement because it results in multiple `gtag.js` scripts (specific
versions for UA or GA4) that recreate the same trusted type policies.
This causes runtime errors and breaks the setup.

Instead, with continued use of `analytics.js` we have the benefit of
a good separation of trusted types + events and configuration. There is
some problematic with translation of Universal Analytics Events to GA4,
or the other way around (even though we don't use custom events
currently)

We also do not need to send page views for our GA4 property because GA4
with gtag supports this automatically (respecting the history state --
using the `Enhanced measurement events` setting in the UI).
For our UA legacy instance we continue to dispatch events manually. This
logic can be removed in the future.

More details can be found here:
https://docs.google.com/document/d/1aK8u4ZlXbqQ2wMqmgSX7Ces8iLgamC13oCoG6VeBruA/edit?usp=sharing&resourcekey=0-EVe-Rhnme3bj_pkz2RcOmw.

Author: devversion

angular.json

@@ -14,6 +14,7 @@
             "index": "src/index.html",
             "main": "src/main.ts",
             "tsConfig": "src/tsconfig.app.json",
+            "optimization": false,
             "polyfills": "src/polyfills.ts",
             "assets": [
               {
@@ -27,9 +28,7 @@
                 "output": "/"
               }
             ],
-            "styles": [
-              "src/styles.css"
-            ],
+            "styles": ["src/styles.css"],
             "scripts": []
           },
           "configurations": {
@@ -82,9 +81,7 @@
             "polyfills": "src/polyfills.ts",
             "tsConfig": "src/tsconfig.spec.json",
             "scripts": [],
-            "styles": [
-              "src/styles.css"
-            ],
+            "styles": ["src/styles.css"],
             "assets": [
               {
                 "glob": "**/*",
@@ -102,10 +99,7 @@
         "lint": {
           "builder": "@angular-devkit/build-angular:tslint",
           "options": {
-            "tsConfig": [
-              "src/tsconfig.app.json",
-              "src/tsconfig.spec.json"
-            ],
+            "tsConfig": ["src/tsconfig.app.json", "src/tsconfig.spec.json"],
             "exclude": []
           }
         },
@@ -129,4 +123,4 @@
       "prefix": "app"
     }
   }
-}
+}

src/app/analytics.service.ts

@@ -1,15 +1,70 @@
-import { Injectable } from '@angular/core';
+import { Inject, Injectable } from '@angular/core';
 
-declare var ga: any;
+import { environment } from '../environments/environment';
 
-@Injectable({
-  providedIn: 'root'
-})
+/** Extension of `Window` with potential Google Analytics fields. */
+declare global {
+  interface Window {
+    dataLayer?: any[];
+    gtag?(...args: any[]): void;
+    /** Legacy Universal Analytics `analytics.js` field. */
+    ga?(...args: any[]): void;
+  }
+}
+
+@Injectable({ providedIn: 'root' })
+/**
+ * Google Analytics Service - captures app behaviors and sends them to Google Analytics.
+ *
+ * Note: Presupposes that the legacy `analytics.js` script has been loaded on the
+ * host web page.
+ *
+ * Associates data with properties determined from the environment configurations:
+ *   - Data is uploaded to a legacy Universal Analytics property
+ *   - Data is uploaded to our main Google Analytics 4+ property.
+ */
 export class AnalyticsService {
+  constructor() {
+    this._installGlobalSiteTag();
+  }
+
+  send(name: string, value: string | boolean | number) {
+    this._legacyGa('send', 'event', name, value);
+    this._gtag('event', name, { value });
+  }
 
-  constructor() { }
-  send(category: string, action: string) {
-    ga('send', 'event', category, action);
+  private _gtag(...args: any[]) {
+    if (window.gtag) {
+      window.gtag(...args);
+    }
   }
 
+  private _legacyGa(...args: any[]) {
+    if (window.ga) {
+      window.ga(...args);
+    }
+  }
+
+  private _installGlobalSiteTag() {
+    const url = `https://www.googletagmanager.com/gtag/js?id=${environment.googleAnalyticsId}`;
+
+    // Note: This cannot be an arrow function as `gtag.js` expects an actual `Arguments`
+    // instance with e.g. `callee` to be set. Do not attempt to change this and keep this
+    // as much as possible in sync with the tracking code snippet suggested by the Google
+    // Analytics 4 web UI under `Data Streams`.
+    window.dataLayer = window.dataLayer || [];
+    window.gtag = function () {
+      window.dataLayer?.push(arguments);
+    };
+    window.gtag('js', new Date());
+
+    // Configure properties before loading the script. This is necessary to avoid
+    // loading multiple instances of the gtag JS scripts.
+    window.gtag('config', environment.googleAnalyticsId, { debug_mode: true });
+
+    const el = window.document.createElement('script');
+    el.async = true;
+    el.src = url;
+    window.document.head.appendChild(el);
+  }
 }

src/environments/environment.prod.ts

@@ -1,3 +1,4 @@
 export const environment = {
-  production: true
+  googleAnalyticsId: 'G-BVV0RDSG7F',
+  production: true,
 };

src/environments/environment.ts

@@ -4,5 +4,6 @@
 // The list of which env maps to which file can be found in `.angular-cli.json`.
 
 export const environment = {
-  production: false
+  googleAnalyticsId: 'G-Q8PB6PJ5CC',
+  production: false,
 };

src/index.html

@@ -21,6 +21,7 @@
     })(window, document, 'script', 'https://www.google-analytics.com/analytics.js', 'ga');
 
     ga('create', 'UA-8594346-15', 'auto');
+    ga('set', 'anonymizeIp', true);
     ga('send', 'pageview');
 
   </script>