Aller au contenu

Le tracking dans Forge Stats

Ce document décrit le helper track_event, qui enregistre un événement dans la base.

Le fichier de code correspondant est forge_mvc_stats/tracking.py.

1. À quoi sert ce module ?

Tracker, c'est écrire un événement dans forge_stats_events.
Le développeur appelle track_event() volontairement : Forge ne trace rien automatiquement.

Principes :

  • aucune page n'est tracée automatiquement ;
  • aucun cookie visiteur n'est créé ;
  • ni IP, ni user-agent, ni géolocalisation ne sont stockés ;
  • l'exécuteur SQL est injecté par l'appelant ; track_event() ne crée pas de connexion.

2. Enregistrer un événement

from forge_mvc_stats import track_event

track_event(
    execute=db.execute,
    event_or_name="page_view",
    label="Vue de page",
    category="traffic",
    metadata={"path": "/contact"},
)

Avec un événement déjà construit :

from forge_mvc_stats import make_event, track_event

event = make_event("contact_click", label="Clic contact", metadata={"source": "footer"})
track_event(db.execute, event)

3. L'API

Fonction Comportement
get_track_event_sql() le SQL INSERT INTO forge_stats_events (name, label, category, metadata) VALUES (?, ?, ?, ?)
prepare_track_event_values(event) le tuple (name, label, category, metadata_json) prêt pour l'exécution
track_event(execute, event_or_name, ...) valide, prépare, appelle execute(sql, params), retourne le StatsEvent

metadata est sérialisée en JSON avec sort_keys=True ; une métadonnée non sérialisable lève StatsEventError.

4. Contextes d'utilisation

  • Contrôleur : track_event(db.execute, "form_submit", ...) après une action réussie.
  • Tests : passer un execute factice pour vérifier le SQL et les paramètres.

5. Voir aussi