snapshot of https://github.com/jitsi/jitsi-meet.git @ fd1749dd28f4138aa80234fc7f311b19aaffa0e7 (2026-09-15)

react/features/analytics/handlers/MatomoHandler.ts

@@ -0,0 +1,170 @@
+/* global _paq */
+
+import { getJitsiMeetGlobalNS } from '../../base/util/helpers';
+
+import AbstractHandler, { IEvent } from './AbstractHandler';
+
+/**
+ * Analytics handler for Matomo.
+ */
+export default class MatomoHandler extends AbstractHandler {
+    _userProperties: Object;
+
+    /**
+     * Creates new instance of the Matomo handler.
+     *
+     * @param {Object} options - The matomo options.
+     * @param {string} options.matomoEndpoint - The Matomo endpoint.
+     * @param {string} options.matomoSiteID   - The site ID.
+     */
+    constructor(options: any) {
+        super(options);
+        this._userProperties = {};
+
+        if (!options.matomoEndpoint) {
+            throw new Error(
+                'Failed to initialize Matomo handler: no endpoint defined.'
+            );
+        }
+        if (!options.matomoSiteID) {
+            throw new Error(
+                'Failed to initialize Matomo handler: no site ID defined.'
+            );
+        }
+
+        this._enabled = true;
+        this._initMatomo(options);
+    }
+
+    /**
+     * Initializes the _paq object.
+     *
+     * @param {Object} options - The matomo options.
+     * @param {string} options.matomoEndpoint - The Matomo endpoint.
+     * @param {string} options.matomoSiteID   - The site ID.
+     * @returns {void}
+     */
+    _initMatomo(options: any) {
+        // @ts-ignore
+        const _paq = window._paq || [];
+
+        // @ts-ignore
+        window._paq = _paq;
+
+        _paq.push([ 'trackPageView' ]);
+        _paq.push([ 'enableLinkTracking' ]);
+
+        (function() {
+            // add trailing slash if needed
+            const u = options.matomoEndpoint.endsWith('/')
+                ? options.matomoEndpoint
+                : `${options.matomoEndpoint}/`;
+
+            // configure the tracker
+            _paq.push([ 'setTrackerUrl', `${u}matomo.php` ]);
+            _paq.push([ 'setSiteId', options.matomoSiteID ]);
+
+            // insert the matomo script
+            const d = document,
+                g = d.createElement('script'),
+                s = d.getElementsByTagName('script')[0];
+
+            g.type = 'text/javascript';
+            g.async = true;
+            g.defer = true;
+            g.src = `${u}matomo.js`;
+            s.parentNode?.insertBefore(g, s);
+        })();
+    }
+
+    /**
+     * Extracts the integer to use for a Matomo event's value field
+     * from a lib-jitsi-meet analytics event.
+     *
+     * @param {Object} event - The lib-jitsi-meet analytics event.
+     * @returns {number} - The integer to use for the 'value' of a Matomo
+     * event, or NaN if the lib-jitsi-meet event doesn't contain a
+     * suitable value.
+     * @private
+     */
+    _extractValue(event: IEvent) {
+        const value = event?.attributes?.value;
+
+        // Try to extract an integer from the 'value' attribute.
+        return Math.round(parseFloat(value ?? ''));
+    }
+
+    /**
+     * Sets the permanent properties for the current session.
+     *
+     * @param {Object} userProps - The permanent properties.
+     * @returns {void}
+     */
+    setUserProperties(userProps: any = {}) {
+        if (!this._enabled) {
+            return;
+        }
+
+        const visitScope = [ 'user_agent', 'callstats_name', 'browser_name' ];
+
+        // add variables in the 'page' scope
+        Object.keys(userProps)
+            .filter(key => visitScope.indexOf(key) === -1)
+            .forEach((key, index) => {
+                // @ts-ignore
+                _paq.push([
+                    'setCustomVariable',
+                    1 + index,
+                    key,
+                    userProps[key],
+                    'page'
+                ]);
+            });
+
+
+        // add variables in the 'visit' scope
+        Object.keys(userProps)
+            .filter(key => visitScope.indexOf(key) !== -1)
+            .forEach((key, index) => {
+                // @ts-ignore
+                _paq.push([
+                    'setCustomVariable',
+                    1 + index,
+                    key,
+                    userProps[key],
+                    'visit'
+                ]);
+            });
+    }
+
+    /**
+     * This is the entry point of the API. The function sends an event to
+     * the Matomo endpoint. The format of the event is described in
+     * analyticsAdapter in lib-jitsi-meet.
+     *
+     * @param {Object} event - The event in the format specified by
+     * lib-jitsi-meet.
+     * @returns {void}
+     */
+    sendEvent(event: IEvent) {
+        if (this._shouldIgnore(event)) {
+            return;
+        }
+
+        const value = this._extractValue(event);
+        const matomoEvent: Array<string | number | undefined> = [
+            'trackEvent', 'jitsi-meet', this._extractName(event) ];
+
+        if (!isNaN(value)) {
+            matomoEvent.push(value);
+        }
+
+        // @ts-ignore
+        _paq.push(matomoEvent);
+    }
+}
+
+const globalNS = getJitsiMeetGlobalNS();
+
+globalNS.analyticsHandlers = globalNS.analyticsHandlers || [];
+globalNS.analyticsHandlers.push(MatomoHandler);