Plugin Grav

MetriXs propose un plugin Grav officiel qui ajoute le tracker à chaque page de votre site, vérifie votre site automatiquement et reste strictement optionnel : rien ne se charge tant que vous ne le connectez pas. Aucune modification de thème, aucun snippet Twig, aucun bandeau de consentement.

Ce guide détaille toute l’installation, étape par étape.

Avant de commencer

Vous avez besoin d’un compte MetriXs. Le plugin lui-même est gratuit et entièrement fonctionnel ; la formule gratuite MetriXs suffit pour démarrer.

1. Rendez-vous sur app.metrixs.eu et inscrivez-vous
2. Vérifiez votre adresse e-mail via le lien reçu

Étape 1 : ajoutez votre site dans MetriXs

1. Connectez-vous au tableau de bord MetriXs
2. Pendant l’onboarding (ou via Réglages → Sites), ajoutez le domaine de votre site, p. ex. votresite.com — sans https:// et sans www.
3. Ignorez l’étape de vérification du snippet proposée — le plugin vérifie votre site automatiquement à l’étape 4
4. Si besoin, démarrez un essai ou choisissez la formule gratuite (les événements nécessitent une formule active)

Étape 2 : créez une clé API de site

Le plugin s’authentifie avec une clé API propre au site. Elle ne donne accès qu’à ce site (stats:read + event:write), jamais à votre compte, et peut être révoquée à tout moment.

1. Dans le tableau de bord, allez dans Réglages → Sites
2. Dépliez votre site et repérez la section Clés API
3. Cliquez sur Create API key et nommez-la, p. ex. « Grav »
4. Copiez la clé (mtx_live_...) immédiatement — elle n’est affichée qu’une seule fois et ne peut pas être récupérée plus tard

Étape 3 : installez le plugin

Installation via GPM depuis la racine Grav :

bin/gpm install mx-cookieless-analytics

ou dans le plugin Admin, allez dans Plugins → Ajouter et cherchez MX Cookieless Analytics. Vous pouvez aussi télécharger le ZIP depuis la page des versions GitHub et le décompresser dans user/plugins/mx-cookieless-analytics.

Le plugin est testé sur Grav 1.7 et 2.0 (Admin classique et pile Admin/API 2.0).

Étape 4 : configurez le plugin

Dans le plugin Admin, allez dans Plugins → MX Cookieless Analytics :

Champ	Saisie
Enable tracking	Laissez désactivé pour l’instant — à activer après la vérification (étape 4)
Site API key	La clé de l’étape 2
MetriXs URL	Laissez la valeur par défaut https://app.metrixs.eu
Site domain	Laissez vide pour la détection automatique depuis l’URL configurée
Exclude admins	Activé par défaut — les utilisateurs avec accès admin ne comptent pas

Cliquez sur Enregistrer. Le plugin vérifie votre site automatiquement avec ce même enregistrement — vous voyez la confirmation verte « site verified » (ou un message d’erreur expliquant quoi vérifier).

Étape 5 : vérifiez le suivi

1. Assurez-vous que Enable tracking est activé et enregistrez
2. Ouvrez votre site dans une fenêtre privée et naviguez quelques pages
3. Dans le tableau de bord MetriXs, ouvrez la vue Temps réel — les pages vues doivent apparaître en quelques secondes

Remarque : les utilisateurs avec accès admin sont exclus par défaut. Les utilisateurs connectés ordinaires (membres) sont suivis. Testez en navigation privée ou ajustez l’exclusion dans les réglages du plugin.

Fonctionnement de la vérification : le plugin demande un jeton de défi unique à l’API MetriXs, le sert depuis votre propre domaine, et l’API va le relire. Seul quelqu’un qui contrôle votre domaine peut servir ce jeton, ce qui prouve la propriété Le jeton est retiré une fois le handshake terminé.

Référence des réglages

Réglage	Défaut	Signification
Enable tracking	Désactivé	Interrupteur principal — rien ne charge tant que le site n’est pas connecté et ceci activé
Site API key	—	Clé propre au site depuis le tableau de bord
MetriXs URL	https://app.metrixs.eu	À changer uniquement pour un endpoint personnalisé (HTTPS uniquement)
Site domain	Vide (auto)	Doit correspondre au domaine dans MetriXs
Exclude admins	Activé	Ne pas suivre les utilisateurs avec accès admin

Le script tracker est servi depuis app.metrixs.eu avec une URL versionnée, injecté dans le rendu de la page et chargé de façon asynchrone (defer). Il fonctionne sans problème avec le cache de pages Grav et les caches plus agressifs.

Dépannage

La vérification échoue

• Assurez-vous que votre site est joignable publiquement en HTTPS (pas de mode maintenance, pas de pare-feu bloquant les serveurs MetriXs)
• Enregistrez à nouveau les réglages du plugin — le handshake s’exécute à chaque enregistrement
• Pile Admin/API 2.0 ? Assurez-vous que le plugin API est installé et que vous êtes connecté à l’admin

Aucune donnée dans le tableau de bord

• Les réglages du plugin doivent avoir affiché la confirmation « site verified »
• Enable tracking doit être activé
• Le domaine du site doit correspondre exactement au domaine dans MetriXs (sans www., sans https://)
• Vous êtes connecté en tant qu’admin ? Exclu par défaut — testez en navigation privée

Clé API perdue Les clés ne sont pas récupérables après création. Révoquez l’ancienne dans le tableau de bord (Réglages → Sites → Clés API), créez-en une nouvelle et mettez-la à jour dans le plugin.

Configuration sans le plugin Admin La vérification automatique s’exécute lors d’un enregistrement de réglages admin. Installez le plugin Admin pour le flux automatique — sans lui, aucune interface ne déclenche le handshake de vérification. En alternative manuelle, un développeur peut appeler l’API MetriXs directement avec la clé API du site : demander un défi (POST /api/integrations/grav/challenge), coller le jeton retourné comme challenge dans le yaml, puis appeler (POST /api/integrations/grav/verify).

Désinstallation

Lorsque vous retirez le plugin :

• Votre site n’est pas automatiquement déconnecté dans MetriXs (les plugins Grav n’ont pas de hook de désinstallation) — révoquez la clé API dans le tableau de bord (Réglages → Sites → Clés API) pour arrêter la collecte
• Vos données historiques restent dans votre compte MetriXs

Sans plugin ?

Vous pouvez toujours ajouter le tracker manuellement avec l’extrait des guides plateformes — le plugin automatise simplement l’installation et la vérification.