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

src/app/material-docs-app.ts

@@ -1,6 +1,6 @@
 import {Component, OnDestroy, ViewEncapsulation} from '@angular/core';
 
-import {GaService} from './shared/ga/ga';
+import {AnalyticsService} from './shared/analytics/analytics';
 import {NavigationFocusService} from './shared/navigation-focus/navigation-focus.service';
 import {Subscription} from 'rxjs';
 import {map, pairwise, startWith} from 'rxjs/operators';
@@ -14,19 +14,23 @@ import {map, pairwise, startWith} from 'rxjs/operators';
 export class MaterialDocsApp implements OnDestroy {
   private subscriptions = new Subscription();
 
-  constructor(ga: GaService, navigationFocusService: NavigationFocusService) {
-    this.subscriptions.add(navigationFocusService.navigationEndEvents.pipe(
-      map(e => e.urlAfterRedirects),
-      startWith(''),
-      pairwise()
-    ).subscribe(([fromUrl, toUrl]) => {
-      // We want to reset the scroll position on navigation except when navigating within
-      // the documentation for a single component.
-      if (!navigationFocusService.isNavigationWithinComponentView(fromUrl, toUrl)) {
-        resetScrollPosition();
-      }
-      ga.locationChanged(toUrl);
-    }));
+  constructor(analytics: AnalyticsService, navigationFocusService: NavigationFocusService) {
+    this.subscriptions.add(
+      navigationFocusService.navigationEndEvents
+        .pipe(
+          map(e => e.urlAfterRedirects),
+          startWith(''),
+          pairwise()
+        )
+        .subscribe(([fromUrl, toUrl]) => {
+          // We want to reset the scroll position on navigation except when navigating within
+          // the documentation for a single component.
+          if (!navigationFocusService.isNavigationWithinComponentView(fromUrl, toUrl)) {
+            resetScrollPosition();
+          }
+          analytics.locationChanged(toUrl);
+        })
+    );
   }
 
   ngOnDestroy() {

src/app/shared/analytics/analytics.ts

@@ -0,0 +1,88 @@
+import {Injectable} from '@angular/core';
+
+import {environment} from '../../../environments/environment';
+
+/** 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;
+  }
+}
+
+/**
+ * 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.
+ */
+@Injectable({providedIn: 'root'})
+export class AnalyticsService {
+  private previousUrl: string | undefined;
+
+  constructor() {
+    this._installGlobalSiteTag();
+
+    // TODO: Remove this when we fully switch to Google Analytics 4+.
+    this._legacyGa('create', environment.legacyUniversalAnalyticsMaterialId, 'auto', 'mat');
+    this._legacyGa('create', environment.legacyUniversalAnalyticsMainId, 'auto', 'ng');
+  }
+
+  locationChanged(url: string) {
+    this._sendPage(url);
+  }
+
+  private _sendPage(url: string) {
+    // Won't re-send if the url hasn't changed.
+    if (url === this.previousUrl) {
+      return;
+    }
+    this.previousUrl = url;
+    this._legacyGa('mat.set', 'page', url);
+    this._legacyGa('ng.set', 'page', url);
+    this._legacyGa('mat.send', 'pageview');
+    this._legacyGa('ng.send', 'pageview');
+  }
+
+  private _legacyGa(...args: any[]) {
+    if (window.ga) {
+      window.ga(...args);
+    }
+  }
+
+  private _installGlobalSiteTag() {
+    const url =
+      `https://www.googletagmanager.com/gtag/js?id=${environment.googleAnalyticsMaterialId}`;
+
+    // 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.googleAnalyticsOverallDomainId);
+    window.gtag('config', environment.googleAnalyticsMaterialId);
+
+    // skip `gtag` for Protractor e2e tests.
+    if (window.name.includes('NG_DEFER_BOOTSTRAP')) {
+      return;
+    }
+
+    const el = window.document.createElement('script');
+    el.async = true;
+    el.src = url;
+    window.document.head.appendChild(el);
+  }
+}

src/app/shared/carousel/carousel.ts

@@ -16,7 +16,6 @@ import {FocusableOption, FocusKeyManager} from '@angular/cdk/a11y';
 import {LEFT_ARROW, RIGHT_ARROW, TAB} from '@angular/cdk/keycodes';
 import {ANIMATION_MODULE_TYPE} from '@angular/platform-browser/animations';
 
-
 @Directive({
   selector: '[carousel-item]',
 })
@@ -35,7 +34,7 @@ export class CarouselItem implements FocusableOption {
   selector: 'app-carousel',
   templateUrl: './carousel.html',
   styleUrls: ['./carousel.scss'],
-  encapsulation: ViewEncapsulation.None
+  encapsulation: ViewEncapsulation.None,
 })
 export class Carousel implements AfterContentInit {
   @Input('aria-label') ariaLabel: string | undefined;
@@ -145,7 +144,9 @@ export class Carousel implements AfterContentInit {
       return true;
     }
 
-    return (!side || side === 'end') &&
-           (offsetWidth + offsetLeft - this.position) > this.list.nativeElement.clientWidth;
+    return (
+      (!side || side === 'end') &&
+      offsetWidth + offsetLeft - this.position > this.list.nativeElement.clientWidth
+    );
   }
 }

src/app/shared/ga/ga.ts

@@ -1,5 +1,9 @@
 export const environment = {
-  matGaId: 'UA-8594346-24', // Production id
-  ngGaId: 'UA-8594346-15', // Production id
+  googleAnalyticsOverallDomainId: 'G-BVV0RDSG7F', // Production framework property id.
+  googleAnalyticsMaterialId: 'G-XXPDW812XH', // Production Material id
+
+  legacyUniversalAnalyticsMainId: 'UA-8594346-15', // Legacy production id
+  legacyUniversalAnalyticsMaterialId: 'UA-8594346-24', // Legacy production id
+
   production: true,
 };

src/environments/environment.prod.ts

@@ -4,8 +4,12 @@
 // The list of which env maps to which file can be found in `angular-cli.json`.
 
 export const environment = {
-  matGaId: '', // No development id for Material
-  ngGaId: 'UA-8594346-26', // Development id
+  googleAnalyticsOverallDomainId: 'G-Q8PB6PJ5CC', // Development framework property id.
+  googleAnalyticsMaterialId: 'G-8DL3XGKYMC', // Development Material id
+
+  legacyUniversalAnalyticsMainId: 'UA-8594346-26', // Legacy development id
+  legacyUniversalAnalyticsMaterialId: '', // No legacy development id for Material
+
   production: false,
 };