fix(tracker): add the option to run tracking outside of angular zone

Cherry-picked from 6d26eac

fixes #60

Author: Arrakis-Lux

docs/configuration-reference.md

@@ -44,6 +44,7 @@ Available options :
 | enableJSErrorTracking | `boolean`                                                                  | `false`                                                        | If set to `true`, enable JS errors tracking.                                                                                                                                                             | yes                        |
 | acceptDoNotTrack      | `boolean`                                                                  | `false`                                                        | Set whether to not track users who opt out of tracking using <i>Do Not Track</i> setting                                                                                                                 | yes                        |
 | requireConsent        | `MatomoConsentMode`                                                        | `MatomoConsentMode.NONE`                                       | Configure user consent requirement.                                                                                                                                                                      | yes                        |
+| runOutsideAngularZone | `boolean`                                                                  | `false`                                                        | If set to `true`, will run matomo calls outside of angular's NgZone. This may help if the call causes the app to freeze.                                                                                 | yes                        |
 
 ### NgxMatomoRouterModule
 

projects/tracker/src/lib/configuration.ts

@@ -21,6 +21,7 @@ export const INTERNAL_MATOMO_CONFIGURATION = new InjectionToken<InternalMatomoCo
         trackAppInitialLoad: false,
         requireConsent: MatomoConsentMode.NONE,
         enableJSErrorTracking: false,
+        runOutsideAngularZone: false,
         ...requireNonNull(inject(MATOMO_CONFIGURATION, InjectFlags.Optional), CONFIG_NOT_FOUND),
       } as InternalMatomoConfiguration),
   }
@@ -109,6 +110,9 @@ export interface BaseMatomoConfiguration {
 
   /** Set to `true` to enable Javascript errors tracking as <i>events</i> (with category <i>JavaScript Errors</i>) */
   enableJSErrorTracking?: boolean;
+
+  /** Set to `true` to run matomo calls outside of angular NgZone. This may fix angular freezes. */
+  runOutsideAngularZone?: boolean;
 }
 
 export interface BaseAutoMatomoConfiguration<

projects/tracker/src/lib/matomo-tracker.service.spec.ts

@@ -1,3 +1,4 @@
+import { NgZone } from '@angular/core';
 import { InternalMatomoConfiguration } from './configuration';
 import { MatomoHolder } from './holder';
 import {
@@ -15,8 +16,16 @@ const PLATFORM_BROWSER_ID = 'browser';
 const PLATFORM_SERVER_ID = 'server';
 
 describe('MatomoTracker', () => {
-  function createTracker(disabled = false, platform: Object = PLATFORM_BROWSER_ID): MatomoTracker {
-    return createMatomoTracker({ disabled } as InternalMatomoConfiguration, platform);
+  function createMockZone(): jasmine.SpyObj<NgZone> {
+    return jasmine.createSpyObj<NgZone>(['runOutsideAngular']);
+  }
+
+  function createTracker(
+    config: Partial<InternalMatomoConfiguration> = { disabled: false },
+    platform: Object = PLATFORM_BROWSER_ID,
+    ngZone: NgZone = createMockZone()
+  ): MatomoTracker {
+    return createMatomoTracker(config as InternalMatomoConfiguration, platform, ngZone);
   }
 
   beforeEach(() => {
@@ -632,7 +641,7 @@ describe('MatomoTracker', () => {
 
   it('should ignore calls when disabled', () => {
     // Given
-    const tracker = createTracker(true);
+    const tracker = createTracker({ disabled: true });
     (window as any)._paq = undefined;
 
     // Then
@@ -642,7 +651,7 @@ describe('MatomoTracker', () => {
 
   it('should reject all promises when disabled', done => {
     // Given
-    const tracker = createTracker(true);
+    const tracker = createTracker({ disabled: true });
 
     // Then
     tracker
@@ -656,7 +665,7 @@ describe('MatomoTracker', () => {
 
   it('should ignore calls when platform is not browser', () => {
     // Given
-    const tracker = createTracker(false, PLATFORM_SERVER_ID);
+    const tracker = createTracker({ disabled: false }, PLATFORM_SERVER_ID);
     (window as any)._paq = undefined;
 
     // Then
@@ -666,7 +675,7 @@ describe('MatomoTracker', () => {
 
   it('should reject all promises when platform is not browser', done => {
     // Given
-    const tracker = createTracker(false, PLATFORM_SERVER_ID);
+    const tracker = createTracker({ disabled: false }, PLATFORM_SERVER_ID);
 
     // Then
     tracker
@@ -677,4 +686,23 @@ describe('MatomoTracker', () => {
         done();
       });
   });
+
+  it('should run commands outside Angular Zone', () => {
+    // Given
+    const zone = createMockZone();
+    const tracker = createTracker({ runOutsideAngularZone: true }, PLATFORM_BROWSER_ID, zone);
+    let runOutside = false;
+
+    zone.runOutsideAngular.and.callFake(fn => {
+      runOutside = true;
+      return fn();
+    });
+
+    // When
+    tracker.ping();
+
+    // Then
+    expect(runOutside).toBeTrue();
+    expect(window._paq).toEqual([['ping']]);
+  });
 });

projects/tracker/src/lib/matomo-tracker.service.ts

@@ -1,5 +1,5 @@
 import { isPlatformBrowser } from '@angular/common';
-import { Injectable, PLATFORM_ID } from '@angular/core';
+import { Injectable, NgZone, PLATFORM_ID } from '@angular/core';
 import { INTERNAL_MATOMO_CONFIGURATION, InternalMatomoConfiguration } from './configuration';
 import { initializeMatomoHolder, MatomoHolder } from './holder';
 import { Getters, RequireAtLeastOne } from './types';
@@ -103,17 +103,18 @@ export interface MatomoInstance {
 
 export function createMatomoTracker(
   config: InternalMatomoConfiguration,
-  platformId: Object
+  platformId: Object,
+  ngZone: NgZone
 ): MatomoTracker {
   return config.disabled || !isPlatformBrowser(platformId)
     ? new NoopMatomoTracker()
-    : new StandardMatomoTracker();
+    : new StandardMatomoTracker(ngZone, config);
 }
 
 @Injectable({
   providedIn: 'root',
   useFactory: createMatomoTracker,
-  deps: [INTERNAL_MATOMO_CONFIGURATION, PLATFORM_ID],
+  deps: [INTERNAL_MATOMO_CONFIGURATION, PLATFORM_ID, NgZone],
 })
 export abstract class MatomoTracker {
   /**
@@ -1354,7 +1355,10 @@ export abstract class MatomoTracker {
 }
 
 export class StandardMatomoTracker extends MatomoTracker {
-  constructor() {
+  constructor(
+    private readonly ngZone: NgZone,
+    private readonly config: InternalMatomoConfiguration
+  ) {
     super();
     initializeMatomoHolder();
   }
@@ -1370,7 +1374,13 @@ export class StandardMatomoTracker extends MatomoTracker {
   }
 
   protected push(args: unknown[]): void {
-    window._paq.push(trimTrailingUndefinedElements(args));
+    if (this.config.runOutsideAngularZone) {
+      this.ngZone.runOutsideAngular(() => {
+        window._paq.push(trimTrailingUndefinedElements(args));
+      });
+    } else {
+      window._paq.push(trimTrailingUndefinedElements(args));
+    }
   }
 }