Grav-Plugin

MetriXs bietet ein erstklassiges Grav-Plugin, das den Tracker auf jede Seite Ihrer Website setzt, Ihre Website automatisch verifiziert und strikt Opt-in bleibt: Es wird nichts geladen, bis Sie es verbinden. Keine Theme-Bearbeitung, keine Twig-Snippets, kein Consent-Banner.

Diese Anleitung führt durch das komplette Setup.

Bevor Sie starten

Sie brauchen ein MetriXs-Konto. Das Plugin selbst ist kostenlos und voll funktionsfähig; der kostenlose MetriXs-Plan reicht für den Einstieg.

1. Gehen Sie zu app.metrixs.eu und registrieren Sie sich
2. Bestätigen Sie Ihre E-Mail-Adresse über den Link, den Sie erhalten

Schritt 1: Website in MetriXs anlegen

1. Melden Sie sich im MetriXs-Dashboard an
2. Legen Sie während des Onboardings (oder unter Einstellungen → Websites) die Domain Ihrer Website an, z. B. yourdomain.com — ohne https:// und ohne www.
3. Überspringen Sie den vorgeschlagenen Snippet-Verifizierungsschritt — das Plugin verifiziert Ihre Website automatisch in Schritt 4
4. Starten Sie bei Bedarf eine Testphase oder wählen Sie den Gratisplan (Events erfordern einen aktiven Plan)

Schritt 2: Site-API-Key erstellen

Das Plugin authentifiziert sich mit einem site-spezifischen API-Key. Er gewährt nur Zugriff auf diese eine Website (stats:read + event:write), nie auf Ihr Konto, und ist jederzeit widerrufbar.

1. Gehen Sie im Dashboard zu Einstellungen → Websites
2. Klappen Sie Ihre Website auf und finden Sie den Bereich API-Keys
3. Klicken Sie auf Create API key und benennen Sie ihn, z. B. „Grav“
4. Kopieren Sie den Key (mtx_live_...) sofort — er wird nur einmal angezeigt und kann später nicht mehr abgerufen werden

Schritt 3: Plugin installieren

Installation über GPM im Grav-Stammverzeichnis:

bin/gpm install mx-cookieless-analytics

oder im Admin-Plugin unter Plugins → Hinzufügen nach MX Cookieless Analytics suchen. Alternativ das ZIP von der GitHub-Releases-Seite herunterladen und nach user/plugins/mx-cookieless-analytics entpacken.

Das Plugin ist mit Grav 1.7 und 2.0 getestet (klassisches Admin und die 2.0-Admin/API-Technik).

Schritt 4: Plugin konfigurieren

Gehen Sie im Admin-Plugin zu Plugins → MX Cookieless Analytics:

Feld	Eingabe
Enable tracking	Vorerst aus — nach der Verifizierung einschalten (Schritt 4)
Site API key	Der Key aus Schritt 2
MetriXs URL	Standard https://app.metrixs.eu lassen
Site domain	Leer lassen für automatische Erkennung über die konfigurierte Website-URL
Exclude admins	Standardmäßig an — Nutzer mit Admin-Zugriff zählen nicht

Klicken Sie auf Speichern. Das Plugin verifiziert Ihre Website automatisch mit demselben Speichervorgang — Sie sehen die grüne Bestätigung „site verified“ (oder eine Fehlermeldung mit Hinweisen).

Schritt 5: Tracking prüfen

1. Stellen Sie sicher, dass Enable tracking eingeschaltet ist, und speichern Sie
2. Öffnen Sie Ihre Website in einem Inkognito-Fenster und surfen Sie ein paar Seiten an
3. Prüfen Sie im MetriXs-Dashboard die Realtime-Ansicht — Pageviews sollten binnen Sekunden erscheinen

Hinweis: Nutzer mit Admin-Zugriff sind standardmäßig ausgeschlossen. Reguläre eingeloggte Nutzer (Mitglieder) werden getrackt. Testen Sie im Inkognito-Modus oder passen Sie den Ausschluss in den Plugin-Einstellungen an.

So funktioniert die Verifizierung: Das Plugin fragt die MetriXs-API nach einem Einmal-Challenge-Token, serviert ihn über Ihre eigene Domain und die API holt ihn zurück. Nur wer Ihre Domain kontrolliert, kann den Token servieren — das beweist das Eigentum Der Token wird nach abgeschlossenem Handshake wieder entfernt.

Einstellungsreferenz

Einstellung	Standard	Bedeutung
Enable tracking	Aus	Hauptschalter — nichts lädt, bis die Website verbunden ist und dies an ist
Site API key	—	Site-spezifischer Key aus dem Dashboard
MetriXs URL	https://app.metrixs.eu	Nur bei eigenen Endpoints ändern (nur HTTPS)
Site domain	Leer (auto)	Muss der Domain in MetriXs entsprechen
Exclude admins	An	Nutzer mit Admin-Zugriff nicht tracken

Der Tracker-Skript wird von app.metrixs.eu mit versionierter URL geladen, in den Seiten-Output injiziert und asynchron (defer) geladen. Er arbeitet problemlos neben Grav-Seiten-Caching und aggressiven Caching-Setups.

Fehlerbehebung

Verifizierung schlägt fehl

• Stellen Sie sicher, dass Ihre Website öffentlich über HTTPS erreichbar ist (kein Wartungsmodus, keine Firewall, die die MetriXs-Server blockt)
• Speichern Sie die Plugin-Einstellungen erneut — der Handshake läuft bei jedem Speichern
• 2.0-Admin/API-Technik im Einsatz? Stellen Sie sicher, dass das API-Plugin installiert ist und Sie im Admin eingeloggt sind

Keine Daten im Dashboard

• Die Plugin-Einstellungen müssen die „site verified“-Bestätigung gezeigt haben
• Enable tracking muss eingeschaltet sein
• Die Website-Domain muss exakt der Domain in MetriXs entsprechen (ohne www., ohne https://)
• Sie sind als Admin eingeloggt? Standardmäßig ausgeschlossen — Inkognito testen

API-Key verloren Keys sind nach der Erstellung nicht abrufbar. Widerrufen Sie den alten Key im Dashboard (Einstellungen → Websites → API-Keys), erstellen Sie einen neuen und tragen Sie ihn im Plugin ein.

Konfiguration ohne Admin-Plugin Die Auto-Verifizierung läuft beim Speichern einer Admin-Einstellung. Installieren Sie das Admin-Plugin für den automatischen Ablauf — ohne es gibt es keine Oberfläche, um den Verifizierungs-Handshake auszulösen. Als manuelle Alternative kann ein Entwickler die MetriXs-API direkt mit dem Site-API-Key aufrufen: Challenge anfordern (POST /api/integrations/grav/challenge), den zurückgegebenen Token als challenge in die yaml eintragen, dann (POST /api/integrations/grav/verify) aufrufen.

Deinstallation

Beim Entfernen des Plugins:

• Ihre Website wird nicht automatisch in MetriXs getrennt (Grav-Plugins haben keinen Deinstallations-Hook) — widerrufen Sie den API-Key im Dashboard (Einstellungen → Websites → API-Keys), um die Erfassung zu stoppen
• Ihre historischen Daten bleiben in Ihrem MetriXs-Konto

Ohne Plugin bevorzugt?

Sie können den Tracker jederzeit manuell mit dem Snippet aus den Plattform-Guides hinzufügen — das Plugin automatisiert nur Installation und Verifizierung.