feat(analytics): intégration Matomo via wrapper maison

Provider, hook useMatomo et validation Zod des env VITE_MATOMO ; tracking inerte hors production.

Author: sbenfares

.env.example

@@ -0,0 +1,14 @@
+# Matomo (mesure d'audience) — toutes les variables sont optionnelles.
+# Sans VITE_MATOMO_URL + VITE_MATOMO_SITE_ID, l'analytics est désactivé.
+# Le tracking n'est actif qu'en build production (jamais en dev ni en test).
+VITE_MATOMO_URL=
+VITE_MATOMO_SITE_ID=
+
+# Optionnel : identifiant de funnel.
+VITE_MATOMO_FUNNEL_ID=
+
+# Optionnel : dimensions personnalisées, format VITE_MATOMO_DIMENSION_<NOM>_ID=<id numérique>.
+# VITE_MATOMO_DIMENSION_PROFIL_ID=1
+
+# Optionnel : logge les events en console sans les envoyer (debug en dev).
+VITE_DEBUG_MATOMO=false

src/App.tsx

@@ -2,6 +2,7 @@ import { Routes, Route } from "react-router-dom";
 import { ROUTES } from "@shared/config/routes.config";
 import { ErrorBoundary } from "@shared/components/ErrorBoundary";
 import { Layout } from "@shared/components/layout/Layout";
+import { Matomo } from "@shared/analytics";
 import { HomePage } from "@features/home/pages/HomePage";
 import { SimulateursIndexPage } from "@features/simulateurs/pages/SimulateursIndexPage";
 import { DocumentationReglementairePage } from "@features/documentation/pages/DocumentationReglementairePage";
@@ -17,6 +18,7 @@ import { GestionCookiesPage } from "@features/legal/pages/GestionCookiesPage";
 function App() {
   return (
     <Layout>
+      <Matomo />
       <ErrorBoundary fallback={<ErrorFallbackPage />}>
         <Routes>
           <Route path={ROUTES.HOME} element={<HomePage />} />

src/shared/analytics/Matomo.tsx

@@ -0,0 +1,26 @@
+// Provider monté une fois à la racine. Init unique + page view à chaque changement de route.
+// Inerte hors production ; ne rend rien.
+
+import { useEffect } from "react";
+import { useLocation } from "react-router-dom";
+import { matomoSettings } from "./matomo.env";
+import { initMatomo } from "./matomo.client";
+import { useMatomo } from "./useMatomo";
+
+export function Matomo(): null {
+  const { enabled, debug, env } = matomoSettings;
+  const { trackPageView } = useMatomo();
+  const location = useLocation();
+
+  useEffect(() => {
+    if (enabled && env.url && env.siteId) initMatomo(env.url, env.siteId);
+  }, [enabled, env.url, env.siteId]);
+
+  useEffect(() => {
+    if (!enabled && !debug) return;
+    const customUrl = `${window.location.origin}${location.pathname}${location.search}`;
+    trackPageView(customUrl);
+  }, [enabled, debug, location.pathname, location.search, trackPageView]);
+
+  return null;
+}

src/shared/analytics/events.ts

@@ -0,0 +1,13 @@
+// Constantes d'events Matomo centralisées (évite les chaînes magiques).
+// Funnel adapté au flux réel ODICE : formulaire pleine-page, pas wizard multi-étapes.
+
+export const MATOMO_EVENT_CATEGORY = "Simulateur PPA";
+
+export const MATOMO_EVENTS = {
+  SIMULATEUR_OUVERT: "simulateur_ouvert",
+  SIMULATION_LANCEE: "simulation_lancee",
+  RESULTAT_AFFICHE: "resultat_affiche",
+  REINITIALISATION: "reinitialisation",
+} as const;
+
+export type MatomoEventName = (typeof MATOMO_EVENTS)[keyof typeof MATOMO_EVENTS];

src/shared/analytics/index.ts

@@ -0,0 +1,6 @@
+// API publique du module analytics.
+
+export { Matomo } from "./Matomo";
+export { useMatomo, type UseMatomo } from "./useMatomo";
+export { MATOMO_EVENTS, MATOMO_EVENT_CATEGORY, type MatomoEventName } from "./events";
+export { matomoSettings, parseMatomoEnv, type MatomoSettings } from "./matomo.env";

src/shared/analytics/matomo.client.ts

@@ -0,0 +1,38 @@
+// Wrapper bas niveau autour de window._paq (équivalent de ce que fait @socialgouv/matomo-next).
+// Injecte le snippet officiel une seule fois et expose push().
+
+declare global {
+  interface Window {
+    _paq?: unknown[][];
+  }
+}
+
+let initialised = false;
+
+function getPaq(): unknown[][] {
+  if (typeof window === "undefined") return [];
+  window._paq = window._paq ?? [];
+  return window._paq;
+}
+
+export function push(args: unknown[]): void {
+  getPaq().push(args);
+}
+
+// Init unique : configure le tracker et charge matomo.js. Garde anti double-init.
+export function initMatomo(url: string, siteId: string): void {
+  if (initialised || typeof document === "undefined") return;
+  initialised = true;
+
+  const base = url.endsWith("/") ? url : `${url}/`;
+  const paq = getPaq();
+  paq.push(["enableLinkTracking"]);
+  paq.push(["setTrackerUrl", `${base}matomo.php`]);
+  paq.push(["setSiteId", siteId]);
+
+  const script = document.createElement("script");
+  script.async = true;
+  script.src = `${base}matomo.js`;
+  const firstScript = document.getElementsByTagName("script")[0];
+  firstScript?.parentNode?.insertBefore(script, firstScript);
+}

src/shared/analytics/matomo.env.spec.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from "vitest";
+import { parseMatomoEnv } from "./matomo.env";
+
+const CORE = {
+  VITE_MATOMO_URL: "https://matomo.exemple.fr/",
+  VITE_MATOMO_SITE_ID: "42",
+};
+
+describe("parseMatomoEnv", () => {
+  it("active le tracking quand url + siteId présents et build production", () => {
+    const settings = parseMatomoEnv(CORE, true);
+    expect(settings.enabled).toBe(true);
+    expect(settings.env.url).toBe("https://matomo.exemple.fr/");
+    expect(settings.env.siteId).toBe("42");
+  });
+
+  it("désactive le tracking hors production même avec les env", () => {
+    expect(parseMatomoEnv(CORE, false).enabled).toBe(false);
+  });
+
+  it("désactive le tracking si url ou siteId manquant", () => {
+    expect(parseMatomoEnv({ VITE_MATOMO_URL: CORE.VITE_MATOMO_URL }, true).enabled).toBe(false);
+    expect(parseMatomoEnv({}, true).enabled).toBe(false);
+  });
+
+  it("collecte les dimensions personnalisées VITE_MATOMO_DIMENSION_*_ID", () => {
+    const settings = parseMatomoEnv(
+      { ...CORE, VITE_MATOMO_DIMENSION_PROFIL_ID: "3", VITE_MATOMO_DIMENSION_ZONE_ID: "5" },
+      true,
+    );
+    expect(settings.env.dimensions).toEqual({ profil: 3, zone: 5 });
+  });
+
+  it("interprète VITE_DEBUG_MATOMO", () => {
+    expect(parseMatomoEnv({ VITE_DEBUG_MATOMO: "true" }, false).debug).toBe(true);
+    expect(parseMatomoEnv({}, false).debug).toBe(false);
+  });
+
+  it("désactive proprement sur configuration invalide sans lever d'exception", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    const settings = parseMatomoEnv(
+      { VITE_MATOMO_URL: "pas-une-url", VITE_MATOMO_SITE_ID: "1" },
+      true,
+    );
+    expect(settings.enabled).toBe(false);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});

src/shared/analytics/matomo.env.ts

@@ -0,0 +1,72 @@
+// Lecture + validation Zod des variables Matomo exposées au bundle (VITE_*).
+// SPA statique : aucun secret ici (cf. CLAUDE.md "Variables d'environnement").
+
+import { z } from "zod";
+
+// Coerce "true"/true vers boolean ; undefined -> false.
+const booleanFromEnv = z
+  .union([z.boolean(), z.string()])
+  .optional()
+  .transform((value) => value === true || value === "true");
+
+const matomoEnvSchema = z.object({
+  url: z.url().optional(),
+  siteId: z.string().min(1).optional(),
+  funnelId: z.string().min(1).optional(),
+  debug: booleanFromEnv,
+  // Dimensions personnalisées : nom logique -> id numérique Matomo.
+  dimensions: z.record(z.string(), z.coerce.number().int().positive()),
+});
+
+export type MatomoEnv = z.infer<typeof matomoEnvSchema>;
+
+export interface MatomoSettings {
+  env: MatomoEnv;
+  /** init + envoi réel : env complètes ET build production. */
+  enabled: boolean;
+  /** log des events sans envoi (activable en dev via VITE_DEBUG_MATOMO). */
+  debug: boolean;
+}
+
+const DIMENSION_KEY = /^VITE_MATOMO_DIMENSION_(.+)_ID$/;
+
+const DISABLED: MatomoSettings = {
+  env: { debug: false, dimensions: {} },
+  enabled: false,
+  debug: false,
+};
+
+// Fonction pure (testable) : parse un environnement brut et décide de l'activation.
+export function parseMatomoEnv(
+  rawEnv: Record<string, string | undefined>,
+  isProd: boolean,
+): MatomoSettings {
+  const dimensions: Record<string, string | undefined> = {};
+  for (const key of Object.keys(rawEnv)) {
+    const match = DIMENSION_KEY.exec(key);
+    if (match) dimensions[match[1].toLowerCase()] = rawEnv[key];
+  }
+
+  const result = matomoEnvSchema.safeParse({
+    url: rawEnv.VITE_MATOMO_URL,
+    siteId: rawEnv.VITE_MATOMO_SITE_ID,
+    funnelId: rawEnv.VITE_MATOMO_FUNNEL_ID,
+    debug: rawEnv.VITE_DEBUG_MATOMO,
+    dimensions,
+  });
+
+  if (!result.success) {
+    // Analytics ne doit jamais casser l'app : on désactive sur configuration invalide.
+    console.warn("[ODICE matomo] configuration invalide, analytics désactivé", result.error.issues);
+    return DISABLED;
+  }
+
+  const env = result.data;
+  const hasCore = Boolean(env.url && env.siteId);
+  return { env, enabled: isProd && hasCore, debug: env.debug };
+}
+
+export const matomoSettings: MatomoSettings = parseMatomoEnv(
+  import.meta.env as unknown as Record<string, string | undefined>,
+  import.meta.env.PROD,
+);

src/shared/analytics/useMatomo.spec.tsx

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+const pushMock = vi.fn();
+
+// Force le mode activé pour tester la logique d'envoi.
+vi.mock("./matomo.env", () => ({
+  matomoSettings: { enabled: true, debug: false, env: { debug: false, dimensions: {} } },
+}));
+vi.mock("./matomo.client", () => ({ push: (args: unknown[]) => pushMock(args) }));
+
+import { useMatomo } from "./useMatomo";
+import { MATOMO_EVENTS, MATOMO_EVENT_CATEGORY } from "./events";
+
+describe("useMatomo (activé)", () => {
+  beforeEach(() => pushMock.mockClear());
+
+  it("pose puis supprime les dimensions autour de l'event (set -> track -> delete)", () => {
+    const { result } = renderHook(() => useMatomo());
+    act(() => {
+      result.current.trackEvent(MATOMO_EVENTS.SIMULATION_LANCEE, undefined, { 3: "abattoir" });
+    });
+
+    const calls = pushMock.mock.calls.map((call) => call[0] as unknown[]);
+    expect(calls[0]).toEqual(["setCustomDimension", 3, "abattoir"]);
+    expect(calls[1]).toEqual([
+      "trackEvent",
+      MATOMO_EVENT_CATEGORY,
+      MATOMO_EVENTS.SIMULATION_LANCEE,
+    ]);
+    expect(calls[2]).toEqual(["deleteCustomDimension", 3]);
+  });
+
+  it("pose setCustomUrl avant trackPageView", () => {
+    const { result } = renderHook(() => useMatomo());
+    act(() => {
+      result.current.trackPageView("https://odice.fr/simulateurs");
+    });
+
+    const calls = pushMock.mock.calls.map((call) => call[0] as unknown[]);
+    expect(calls[0]).toEqual(["setCustomUrl", "https://odice.fr/simulateurs"]);
+    expect(calls[1]).toEqual(["trackPageView"]);
+  });
+});

src/shared/analytics/useMatomo.ts

@@ -0,0 +1,74 @@
+// Helpers typés autour de _paq. No-op hors production ; log sans envoi en mode debug.
+
+import { useCallback } from "react";
+import { matomoSettings } from "./matomo.env";
+import { push } from "./matomo.client";
+import { MATOMO_EVENT_CATEGORY, type MatomoEventName } from "./events";
+
+interface TrackEventOptions {
+  name?: string;
+  value?: number;
+}
+
+// dimensionId Matomo -> valeur.
+type CustomDimensions = Record<number, string>;
+
+export interface UseMatomo {
+  trackEvent: (
+    event: MatomoEventName,
+    options?: TrackEventOptions,
+    customDimensions?: CustomDimensions,
+  ) => void;
+  trackPageView: (customUrl?: string) => void;
+  enableHeatmaps: () => void;
+}
+
+export function useMatomo(): UseMatomo {
+  const { enabled, debug } = matomoSettings;
+
+  const trackEvent = useCallback<UseMatomo["trackEvent"]>(
+    (event, options = {}, customDimensions = {}) => {
+      if (debug) console.info("[ODICE matomo] trackEvent", { event, options, customDimensions });
+      if (!enabled) return;
+      try {
+        const dimensionIds = Object.keys(customDimensions).map(Number);
+        // set -> track -> delete : sinon les dimensions fuitent sur les events suivants.
+        for (const id of dimensionIds) push(["setCustomDimension", id, customDimensions[id]]);
+        push(
+          ["trackEvent", MATOMO_EVENT_CATEGORY, event, options.name, options.value].filter(
+            (value) => value !== undefined,
+          ),
+        );
+        for (const id of dimensionIds) push(["deleteCustomDimension", id]);
+      } catch (error) {
+        console.warn("[ODICE matomo] trackEvent a échoué", error);
+      }
+    },
+    [enabled, debug],
+  );
+
+  const trackPageView = useCallback<UseMatomo["trackPageView"]>(
+    (customUrl) => {
+      if (debug) console.info("[ODICE matomo] trackPageView", { customUrl });
+      if (!enabled) return;
+      try {
+        if (customUrl) push(["setCustomUrl", customUrl]);
+        push(["trackPageView"]);
+      } catch (error) {
+        console.warn("[ODICE matomo] trackPageView a échoué", error);
+      }
+    },
+    [enabled, debug],
+  );
+
+  const enableHeatmaps = useCallback<UseMatomo["enableHeatmaps"]>(() => {
+    if (!enabled) return;
+    try {
+      push(["HeatmapSessionRecording::enable"]);
+    } catch (error) {
+      console.warn("[ODICE matomo] enableHeatmaps a échoué", error);
+    }
+  }, [enabled]);
+
+  return { trackEvent, trackPageView, enableHeatmaps };
+}