feat(tracker): automatically enable or disable initial page view trac…

…king

Initial page view tracking is `true` by default and automatically switched off if router feature is enabled.

BREAKING CHANGE: Configuration option `trackAppInitialLoad` is now `true` by default, unless router feature is enabled (it previously was always `false` by default).
For applications with router enabled, nothing changes. It can still be manually configured like before.
This should not affect most applications, because tracking initial page view is not recommended when router feature is enabled.

docs/configuration-reference.md

@@ -87,7 +87,7 @@ Main configuration options (for `NgxMatomoModule.forRoot` or `provideMatomo`) ar
 | trackers              | array of `{siteId: string, trackerUrl: string, trackerUrlSuffix?: string}` | <i>none</i>, required unless `siteId` and `trackerUrl` are set | A list of multiple Matomo servers. Note that tracking code will be downloaded from the FIRST tracker in the list (unless `scriptUrl` option is set). Mutually exclusive with the three previous options.                                               | no                         |
 | scriptUrl             | `string`                                                                   | tracker url suffixed with `matomo.js`                          | Url of Matomo tracker's script.                                                                                                                                                                                                                        | no                         |
 | disabled              | `boolean`                                                                  | `false`                                                        | If set to `true` then all tracking operations become no-op. Note that in this case, all getter methods will return rejected Promises.                                                                                                                  | yes                        |
-| trackAppInitialLoad   | `boolean`                                                                  | `false`                                                        | If set to `true`, will call trackPageView on application init. This should probably never be used on a routed single-page application.                                                                                                                 | yes                        |
+| trackAppInitialLoad   | `boolean`                                                                  | `false` if router is enabled, `true` otherwise                 | If set to `true`, will call trackPageView on application init. This should probably never be used on a routed single-page application.                                                                                                                 | yes                        |
 | enableLinkTracking    | `boolean` or `'enable-pseudo'`                                             | `true`                                                         | If set to `true` (the default), enable link tracking, excluding middle-clicks and contextmenu events.<br>If set to `enable-pseudo`, enable link tracking, including middle-clicks and contextmenu events.<br>If set to `false`, disable link tracking. | yes                        |
 | 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                        |

projects/ngx-matomo-client/src/lib/ngx-matomo-providers.spec.ts

@@ -15,7 +15,11 @@ import {
   MatomoRouteDataInterceptor,
 } from './router/interceptors/route-data-interceptor';
 import { MatomoRouter } from './router/matomo-router.service';
-import { MATOMO_CONFIGURATION, MatomoConfiguration } from './tracker/configuration';
+import {
+  MATOMO_CONFIGURATION,
+  MATOMO_ROUTER_ENABLED,
+  MatomoConfiguration,
+} from './tracker/configuration';
 import { MatomoInitializerService } from './tracker/matomo-initializer.service';
 import { MatomoTracker } from './tracker/matomo-tracker.service';
 import { createDefaultMatomoScriptElement } from './tracker/script-factory';
@@ -91,6 +95,7 @@ describe('providers', () => {
     expect(TestBed.inject(MatomoTracker)).toEqual(jasmine.any(MatomoTracker));
     expect(TestBed.inject(MatomoRouter)).toEqual(jasmine.any(MatomoRouter));
     expect(TestBed.inject(MATOMO_ROUTER_CONFIGURATION)).toEqual({ delay: 42 });
+    expect(TestBed.inject(MATOMO_ROUTER_ENABLED)).toEqual(true);
   });
 
   it('should provide basic Matomo providers with router feature and additional interceptor', async () => {

projects/ngx-matomo-client/src/lib/ngx-matomo-providers.ts

@@ -2,6 +2,7 @@ import {
   ENVIRONMENT_INITIALIZER,
   EnvironmentProviders,
   inject,
+  InjectionToken,
   makeEnvironmentProviders,
   Provider,
   Type,
@@ -17,7 +18,11 @@ import {
   MatomoRouteDataInterceptor,
 } from './router/interceptors/route-data-interceptor';
 import { MatomoRouter } from './router/matomo-router.service';
-import { MATOMO_CONFIGURATION, MatomoConfiguration } from './tracker/configuration';
+import {
+  MATOMO_CONFIGURATION,
+  MATOMO_ROUTER_ENABLED,
+  MatomoConfiguration,
+} from './tracker/configuration';
 import { MatomoInitializerService } from './tracker/matomo-initializer.service';
 import { MATOMO_SCRIPT_FACTORY, MatomoScriptFactory } from './tracker/script-factory';
 
@@ -143,6 +148,7 @@ export function withRouter(config?: MatomoRouterConfiguration): MatomoFeature {
 
 export function provideRouterInternal(config?: MatomoRouterConfiguration): Provider[] {
   return [
+    { provide: MATOMO_ROUTER_ENABLED, useValue: true },
     { provide: MATOMO_ROUTER_CONFIGURATION, useValue: config },
     {
       provide: ENVIRONMENT_INITIALIZER,

projects/ngx-matomo-client/src/lib/tracker/configuration.ts

@@ -4,6 +4,13 @@ import { requireNonNull } from '../utils/coercion';
 const CONFIG_NOT_FOUND =
   'No Matomo configuration found! Have you included Matomo module using NgxMatomoTrackerModule.forRoot() ?';
 
+/** Internal marker token to detect that router has been enabled */
+export const MATOMO_ROUTER_ENABLED = new InjectionToken<boolean>('MATOMO_ROUTER_ENABLED', {
+  factory() {
+    return false;
+  },
+});
+
 /** Injection token for {@link MatomoConfiguration} */
 export const MATOMO_CONFIGURATION = new InjectionToken<MatomoConfiguration>('MATOMO_CONFIGURATION');
 
@@ -18,7 +25,7 @@ export const INTERNAL_MATOMO_CONFIGURATION = new InjectionToken<InternalMatomoCo
       ({
         disabled: false,
         enableLinkTracking: true,
-        trackAppInitialLoad: false,
+        trackAppInitialLoad: !inject(MATOMO_ROUTER_ENABLED),
         requireConsent: MatomoConsentMode.NONE,
         enableJSErrorTracking: false,
         runOutsideAngularZone: false,

projects/ngx-matomo-client/src/lib/tracker/matomo-initializer.service.spec.ts

@@ -4,6 +4,7 @@ import { MatomoHolder } from '../holder';
 import { provideMatomo, withScriptFactory } from '../ngx-matomo-providers';
 import {
   MATOMO_CONFIGURATION,
+  MATOMO_ROUTER_ENABLED,
   MatomoConfiguration,
   MatomoConsentMode,
   MatomoInitializationMode,
@@ -68,11 +69,10 @@ describe('MatomoInitializerService', () => {
       });
   });
 
-  it('should track initial page view with manual configuration', () => {
+  it('should track initial page view by default', () => {
     // Given
     const service = instantiate({
       mode: MatomoInitializationMode.MANUAL,
-      trackAppInitialLoad: true,
       enableLinkTracking: false,
     });
     const tracker = TestBed.inject(MatomoTracker);
@@ -86,6 +86,65 @@ describe('MatomoInitializerService', () => {
     expect(tracker.trackPageView).toHaveBeenCalledOnceWith();
   });
 
+  it('should not track initial page view by default if router is enabled', () => {
+    // Given
+    const service = instantiate(
+      {
+        mode: MatomoInitializationMode.MANUAL,
+        enableLinkTracking: false,
+      },
+      [{ provide: MATOMO_ROUTER_ENABLED, useValue: true }]
+    );
+    const tracker = TestBed.inject(MatomoTracker);
+
+    spyOn(tracker, 'trackPageView');
+
+    // When
+    service.initialize();
+
+    // Then
+    expect(tracker.trackPageView).not.toHaveBeenCalled();
+  });
+
+  it('should manually force track initial page view no matter router is enabled', () => {
+    // Given
+    const service = instantiate(
+      {
+        mode: MatomoInitializationMode.MANUAL,
+        trackAppInitialLoad: true,
+        enableLinkTracking: false,
+      },
+      [{ provide: MATOMO_ROUTER_ENABLED, useValue: true }]
+    );
+    const tracker = TestBed.inject(MatomoTracker);
+
+    spyOn(tracker, 'trackPageView');
+
+    // When
+    service.initialize();
+
+    // Then
+    expect(tracker.trackPageView).toHaveBeenCalledOnceWith();
+  });
+
+  it('should not track initial page view with manual configuration, no matter router enabled', () => {
+    // Given
+    const service = instantiate({
+      mode: MatomoInitializationMode.MANUAL,
+      enableLinkTracking: false,
+      trackAppInitialLoad: false,
+    });
+    const tracker = TestBed.inject(MatomoTracker);
+
+    spyOn(tracker, 'trackPageView');
+
+    // When
+    service.initialize();
+
+    // Then
+    expect(tracker.trackPageView).not.toHaveBeenCalled();
+  });
+
   it('should enable link tracking with manual configuration', () => {
     // Given
     const service = instantiate({