Added enhanced identity-aware tracking

Signed-off-by: Adrian Heidenreich <[email protected]>

Author: Adrian Heidenreich

workspaces/analytics/.changeset/yellow-seahorses-appear.md

@@ -0,0 +1,5 @@
+---
+'@backstage-community/plugin-analytics-module-matomo': minor
+---
+
+Added enhanced identity-aware tracking so Matomo records page views only after a userId is available, fixing the issue where navigate events fired anonymously despite `identity` being enabled

workspaces/analytics/plugins/analytics-module-matomo/README.md

@@ -64,10 +64,19 @@ app:
     matomo:
       host: ${ANALYTICS_MATOMO_INSTANCE_URL}
       siteId: ${ANALYTICS_MATOMO_SITE_ID}
-      identity: optional # (optional) to enable user tracking. Is disabled by default
-      sendPlainUserId: optional # (optional) to not hash User ID when user tracking is enabled. User ID is hashed by default.
+      identity: optional # disabled|optional|required; enables user tracking (disabled by default)
+      sendPlainUserId: optional # if set, do not hash User ID when user tracking is enabled (hashed by default)
+      enhancedTracking: true # enables extended tracking (navigate events buffering, identity gating)
+      deferInitialPageView: true # only if enhancedTracking=true; defers first PV until identity resolved
 ```
 
+Additional optional properties:
+
+- identity: "disabled" | "optional" | "required" (default: disabled)
+- sendPlainUserId: boolean; if true, raw userEntityRef sent (privacy: consider hashing)
+- enhancedTracking: boolean; adds buffering before identity ready & explicit page view handling
+- deferInitialPageView: boolean; when enhancedTracking=true, delays initial page view until identity is available
+
 4. Update CSP in your `app-config.yaml`:(optional)
 
 The following is the minimal content security policy required to load scripts from your Matomo Instance.

workspaces/analytics/plugins/analytics-module-matomo/config.d.ts

@@ -37,11 +37,25 @@ export interface Config {
         identity?: 'disabled' | 'optional' | 'required';
 
         /**
-         * Controls if the hashing of userId should be disabled
+         * Sends the identity as plain userId instead of hashing it
          *
          * @visibility frontend
          */
         sendPlainUserId?: boolean;
+
+        /**
+         * Enables extended tracking capabilities (navigate events, buffering,…)
+         *
+         * @visibility frontend
+         */
+        enhancedTracking?: boolean;
+
+        /**
+         * Defers the initial page view until identity is available
+         *
+         * @visibility frontend
+         */
+        deferInitialPageView?: boolean;
       };
     };
   };

workspaces/analytics/plugins/analytics-module-matomo/src/api/Matomo.ts

@@ -26,31 +26,65 @@ import {
 
 import { loadMatomo } from './loadMatomo';
 
+export type PaqArg = string | number | undefined;
+export type PaqCommand = PaqArg[];
 declare const window: Window &
   typeof globalThis & {
-    _paq: any[];
+    _paq: PaqCommand[];
+    __MATOMO_INITIAL_PV_SENT?: boolean;
+    __MATOMO_INITIAL_PV_TS?: number;
   };
+const pushPaq = (...args: PaqArg[]) => window._paq.push(args);
+
+type NormalizedMatomoEvent = {
+  action: string;
+  subject?: string;
+  value?: number;
+  context: {
+    extension?: string;
+    extensionId?: string;
+  };
+};
 
 /**
  * @public
  */
 export class MatomoAnalytics implements AnalyticsApi, AnalyticsImplementation {
+  private readonly enhancedTracking: boolean;
+  private readonly deferInitialPageView: boolean;
+  private userIdSet = false;
+  private pageViewSent = false;
+  private pendingEvents: NormalizedMatomoEvent[] = [];
+
   private constructor(options: {
     matomoUrl: string;
     siteId: number;
     identity: string;
     identityApi?: IdentityApi;
     sendPlainUserId?: boolean;
+    enhancedTracking?: boolean;
+    deferInitialPageView?: boolean;
   }) {
-    loadMatomo(options.matomoUrl, options.siteId);
+    this.enhancedTracking = !!options.enhancedTracking;
+    this.deferInitialPageView =
+      this.enhancedTracking && !!options.deferInitialPageView;
+    this.userIdSet = !this.enhancedTracking && options.identity === 'disabled';
 
-    /* Add user tracking if identity is enabled and identityApi is provided */
+    loadMatomo(options.matomoUrl, options.siteId);
+    // Initial PV unless explicitly deferred (enhancedTracking + deferInitialPageView)
+    if (!this.enhancedTracking || !this.deferInitialPageView) {
+      this.trackInitialPageView();
+    }
     if (options.identity !== 'disabled' && options.identityApi) {
-      this.setUserFrom(options.identityApi, options.sendPlainUserId).catch(
-        () => {
-          return;
-        },
-      );
+      const shouldNotifyReady = true;
+
+      this.setUserFrom(
+        options.identityApi,
+        options.sendPlainUserId,
+        shouldNotifyReady,
+      ).catch(() => {});
+    } else if (!this.userIdSet) {
+      this.onIdentityReady();
     }
   }
 
@@ -67,12 +101,20 @@ export class MatomoAnalytics implements AnalyticsApi, AnalyticsImplementation {
       'app.analytics.matomo.sendPlainUserId',
     );
 
+    const enhancedTracking = config.getOptionalBoolean(
+      'app.analytics.matomo.enhancedTracking',
+    );
+
+    const deferInitialPageView = config.getOptionalBoolean(
+      'app.analytics.matomo.deferInitialPageView',
+    );
+
     const matomoUrl = config.getString('app.analytics.matomo.host');
     const siteId = config.getNumber('app.analytics.matomo.siteId');
 
     if (identity === 'required' && !options?.identityApi) {
       throw new Error(
-        'Invalid config: identity API must be provided to deps when app.matomo.identity is required',
+        "Invalid config: identity API must be provided when app.analytics.matomo.identity is 'required'",
       );
     }
 
@@ -82,36 +124,117 @@ export class MatomoAnalytics implements AnalyticsApi, AnalyticsImplementation {
       identity,
       identityApi: options?.identityApi,
       sendPlainUserId,
+      enhancedTracking,
+      deferInitialPageView,
     });
   }
 
   captureEvent(event: AnalyticsEvent | LegacyAnalyticsEvent) {
-    const { context, action, subject, value } = event;
-    // REF: https://github.com/backstage/community-plugins/blob/main/workspaces/analytics/plugins/analytics-module-ga/src/apis/implementations/AnalyticsApi/GoogleAnalytics.ts#L160
-    // REF: https://matomo.org/faq/reports/implement-event-tracking-with-matomo/
-    window._paq.push([
+    const normalizedEvent = this.normalizeEvent(event);
+    if (!this.userIdSet) {
+      this.pendingEvents.push(normalizedEvent); // Buffer until identity ready
+      return;
+    }
+    this.handleNormalizedEvent(normalizedEvent);
+  }
+
+  private handleNormalizedEvent(event: NormalizedMatomoEvent) {
+    if (event.action === 'navigate') {
+      this.trackPageView(event);
+      return;
+    }
+    this.pushEvent(event);
+  }
+
+  private normalizeEvent(
+    event: AnalyticsEvent | LegacyAnalyticsEvent,
+  ): NormalizedMatomoEvent {
+    const context = (event.context ?? {}) as NormalizedMatomoEvent['context'];
+
+    return {
+      action: event.action,
+      subject: event.subject,
+      value: event.value,
+      context: {
+        extension: context.extension,
+        extensionId: context.extensionId,
+      },
+    };
+  }
+
+  private pushEvent(event: NormalizedMatomoEvent) {
+    pushPaq(
       'trackEvent',
-      context.extensionId || context.extension || 'App',
-      action,
-      subject,
-      value,
-    ]);
+      event.context.extensionId || event.context.extension || 'App',
+      event.action,
+      event.subject,
+      event.value,
+    );
+  }
+
+  private trackPageView(event: NormalizedMatomoEvent) {
+    const subject = event.subject ?? window.location.pathname ?? '/';
+    const normalizedSubject = subject.startsWith('/') ? subject : `/${subject}`;
+    const fullUrl = `${window.location.origin}${normalizedSubject}`;
+
+    pushPaq('setCustomUrl', fullUrl);
+    pushPaq('setDocumentTitle', normalizedSubject);
+    pushPaq('trackPageView');
+
+    // Mark global initial PV sentinel if first time; navigate events may serve as initial PV
+    if (!window.__MATOMO_INITIAL_PV_SENT) {
+      window.__MATOMO_INITIAL_PV_SENT = true;
+      window.__MATOMO_INITIAL_PV_TS = Date.now();
+    }
+    this.pageViewSent = true; // prevent duplicate initial PV within instance
+  }
+
+  private trackInitialPageView() {
+    if (this.pageViewSent) return;
+    // If deferral requested, caller MUST invoke only after identity ready; constructor invokes early only when no deferral
+    try {
+      if (!window.__MATOMO_INITIAL_PV_SENT) {
+        pushPaq('trackPageView');
+        window.__MATOMO_INITIAL_PV_SENT = true;
+        window.__MATOMO_INITIAL_PV_TS = Date.now();
+      }
+      this.pageViewSent = true;
+    } catch {
+      // Matomo script not loaded yet; ignoring initial PV
+    }
+  }
+
+  private flushPendingEvents() {
+    if (!this.pendingEvents.length) {
+      return;
+    }
+
+    const bufferedEvents = this.pendingEvents.slice();
+    this.pendingEvents = [];
+    bufferedEvents.forEach(e => this.handleNormalizedEvent(e));
+  }
+
+  private onIdentityReady() {
+    this.userIdSet = true;
+    // First flush pending events; if a buffered navigate event exists it will send PageView
+    this.flushPendingEvents();
+    // If no navigate event has set pageViewSent yet, send initial PageView now
+    this.trackInitialPageView();
   }
 
   private async setUserFrom(
     identityApi: IdentityApi,
     sendPlainUserId?: boolean,
+    notifyReady?: boolean,
   ) {
     const { userEntityRef } = await identityApi.getBackstageIdentity();
+    const resolvedId = sendPlainUserId
+      ? userEntityRef
+      : await this.getPrivateUserId(userEntityRef); // hashed ID (no salt)
 
-    if (sendPlainUserId) {
-      window._paq.push(['setUserId', userEntityRef]);
-    } else {
-      // Prevent PII from being passed to Matomo
-      const userId = await this.getPrivateUserId(userEntityRef);
+    pushPaq('setUserId', resolvedId);
 
-      window._paq.push(['setUserId', userId]);
-    }
+    if (notifyReady) this.onIdentityReady();
   }
 
   private getPrivateUserId(userEntityRef: string): Promise<string> {
@@ -120,7 +243,7 @@ export class MatomoAnalytics implements AnalyticsApi, AnalyticsImplementation {
 
   private async hash(value: string): Promise<string> {
     const digest = await window.crypto.subtle.digest(
-      'sha-256',
+      'SHA-256',
       new TextEncoder().encode(value),
     );
     const hashArray = Array.from(new Uint8Array(digest));

workspaces/analytics/plugins/analytics-module-matomo/src/api/loadMatomo.ts

@@ -19,8 +19,7 @@ export const loadMatomo = (matomoUrl: string, siteId: number) => {
   if (isInitialized) return;
 
   const _paq = ((window as any)._paq = (window as any)._paq || []);
-  /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
-  _paq.push(['trackPageView']);
+  /* Do not queue a page view yet; MatomoAnalytics controls when to emit it */
   _paq.push(['enableLinkTracking']);
   (() => {
     const u = `//${matomoUrl}/`;