feat(GST): Implement user timings (#329)

* Google Global Site Tag (GST) - implement user timings

* GST - cover 'user timings' with test

* User timings - remove required properties check

src/lib/providers/gst/gst-interfaces.ts

@@ -0,0 +1,11 @@
+/** @link https://developers.google.com/analytics/devguides/collection/gtagjs/user-timings */
+export interface UserTimingsGst {
+  /** A string to identify the variable being recorded (e.g. 'load'). */
+  name: string;
+  /** The number of milliseconds in elapsed time to report to Google Analytics (e.g. 20). */
+  value: number;
+  /** A string for categorizing all user timing variables into logical groups (e.g. 'JS Dependencies'). */
+  category?: string;
+  /** A string that can be used to add flexibility in visualizing user timings in the reports (e.g. 'Google CDN'). */
+  label?: string;
+}

src/lib/providers/gst/gst.spec.ts

@@ -114,4 +114,28 @@ describe('Angulartics2GoogleGlobalSiteTag', () => {
       },
     ),
   ));
+
+  it('should track user timings', fakeAsync(
+    inject([Angulartics2, Angulartics2GoogleGlobalSiteTag], (
+      angulartics2: Angulartics2,
+      angulartics2GoogleGlobalSiteTag: Angulartics2GoogleGlobalSiteTag,
+      ) => {
+        fixture = createRoot(RootCmp);
+        angulartics2GoogleGlobalSiteTag.startTracking();
+        angulartics2.userTimings.next({
+          timingVar: 'load',
+          timingValue: 33,
+          timingCategory: 'JS Dependencies',
+          timingLabel: 'Google CDN'
+        });
+        advance(fixture);
+        expect(gtag).toHaveBeenCalledWith('event', 'timing_complete', {
+          name: 'load',
+          value: 33,
+          event_category: 'JS Dependencies',
+          event_label: 'Google CDN'
+        });
+      },
+    ),
+  ));
 });

src/lib/providers/gst/gst.ts

@@ -1,6 +1,7 @@
 import { Injectable } from '@angular/core';
 
-import { Angulartics2, GoogleGlobalSiteTagSettings } from 'angulartics2';
+import {Angulartics2, GoogleGlobalSiteTagSettings, UserTimings} from 'angulartics2';
+import {UserTimingsGst} from './gst-interfaces';
 
 declare var gtag: any;
 declare var ga: any;
@@ -42,6 +43,9 @@ export class Angulartics2GoogleGlobalSiteTag {
     this.angulartics2.exceptionTrack
       .pipe(this.angulartics2.filterDeveloperMode())
       .subscribe((x: any) => this.exceptionTrack(x));
+    this.angulartics2.userTimings
+      .pipe(this.angulartics2.filterDeveloperMode())
+      .subscribe(x => this.userTimings(this.convertTimings(x)));
   }
 
   /**
@@ -75,15 +79,13 @@ export class Angulartics2GoogleGlobalSiteTag {
     // Set a default GST category
     properties = properties || {};
 
-    if (typeof gtag !== 'undefined' && gtag) {
-      gtag('event', action, {
-        event_category: properties.category || 'interaction',
-        event_label: properties.label,
-        value: properties.value,
-        non_interaction: properties.noninteraction,
-        ...properties.gstCustom
-      });
-    }
+    this.eventTrackInternal(action, {
+      event_category: properties.category || 'interaction',
+      event_label: properties.label,
+      value: properties.value,
+      non_interaction: properties.noninteraction,
+      ...properties.gstCustom
+    });
   }
 
   /**
@@ -112,4 +114,49 @@ export class Angulartics2GoogleGlobalSiteTag {
       }
     });
   }
+
+  /**
+   * User Timings Event in GST.
+   * @name userTimings
+   *
+   * @param properties Comprised of the mandatory fields:
+   *  - name (string)
+   *  - value (number - integer)
+   * Properties can also have the optional fields:
+   *  - category (string)
+   *  - label (string)
+   *
+   * @link https://developers.google.com/analytics/devguides/collection/gtagjs/user-timings
+   */
+  userTimings(properties: UserTimingsGst) {
+    if (!properties) {
+      console.error('User timings - "properties" parameter is required to be set.');
+      return;
+    }
+
+    this.eventTrackInternal('timing_complete', {
+      name: properties.name,
+      value: properties.value,
+      event_category: properties.category,
+      event_label: properties.label
+    });
+  }
+
+  private convertTimings(properties: UserTimings): UserTimingsGst {
+    return {
+      name: properties.timingVar,
+      value: properties.timingValue,
+      category: properties.timingCategory,
+      label: properties.timingLabel
+    };
+  }
+
+  private eventTrackInternal(action: string, properties: any) {
+    if (typeof gtag === 'undefined' || !gtag) {
+      return;
+    }
+
+    properties = properties || {};
+    gtag('event', action, properties);
+  }
 }