Grav-plugin

MetriXs heeft een officiële Grav-plugin die de tracker op elke pagina van je site zet, je site automatisch verifieert () en strikte opt-in blijft: er wordt niets geladen tot je hem verbindt. Geen themabewerking, geen Twig-snippets, geen cookiemelding.

Deze guide loopt door de complete installatie, stap voor stap.

Voordat je begint

Je hebt een MetriXs-account nodig. De plugin zelf is gratis en volledig functioneel; het gratis MetriXs-plan is genoeg om te starten.

1. Ga naar app.metrixs.eu en registreer je
2. Bevestig je e-mailadres via de link die je ontvangt

Stap 1: voeg je site toe in MetriXs

1. Log in op het MetriXs-dashboard
2. Voeg tijdens het onboarding (of via Instellingen → Sites) het domein van je site toe, bijv. jouwdomain.nl — zonder https:// en zonder www.
3. Sla de snippet-verificatiestap van het dashboard over — de plugin verifieert je site automatisch in stap 4
4. Start indien gevraagd een proefperiode of kies het gratis plan (events vereisen een actief plan)

Stap 2: maak een sitesleutel aan

De plugin authenticiteert met een sitespecifieke API-sleutel. Die geeft alleen toegang tot deze ene site (stats:read + event:write), nooit tot je account, en is op elk moment in te trekken.

1. Ga in het dashboard naar Instellingen → Sites
2. Vouw je site uit en zoek het gedeelte API-sleutels
3. Klik op Create API key en geef hem een naam, bijv. “Grav”
4. Kopieer de sleutel (mtx_live_...) meteen — hij wordt één keer getoond en is later niet meer op te halen

Stap 3: installeer de plugin

Installeer via GPM vanuit de Grav-root:

bin/gpm install mx-cookieless-analytics

of ga in de Admin-plugin naar Plugins → Toevoegen en zoek MX Cookieless Analytics. Je kunt ook de ZIP van de GitHub-releases-pagina downloaden en uitpakken in user/plugins/mx-cookieless-analytics.

De plugin is getest op Grav 1.7 en 2.0 (klassieke Admin en de 2.0-Admin/API-stack).

Stap 4: configureer de plugin

Ga in de Admin-plugin naar Plugins → MX Cookieless Analytics:

Veld	Wat in te vullen
Enable tracking	Laat voorlopig uit — aanzetten na verificatie (stap 4)
Site API key	De sleutel uit stap 2
MetriXs URL	Laat de standaardwaarde https://app.metrixs.eu staan
Site domain	Laat leeg voor automatische detectie via de geconfigureerde site-URL
Exclude admins	Standaard aan — gebruikers met beheerderstoegang tellen niet

Klik op Opslaan. De plugin verifieert je site automatisch met hetzelfde opslaan — je ziet de groene bevestiging “site verified” (of een foutmelding met uitleg).

Stap 5: controleer of tracking werkt

1. Zorg dat Enable tracking aan staat en sla op
2. Open je site in een incognitovenster en bezoek een paar pagina’s
3. Open het MetriXs-dashboard en check de Realtime-weergave — pageviews moeten binnen enkele seconden verschijnen

Let op: gebruikers met beheerderstoegang zijn standaard uitgesloten. Reguliere ingelogde gebruikers (leden) worden wel gevolgd. Test in incognitomodus of pas de uitsluiting aan in de plugin-instellingen.

Hoe de verificatie werkt: de plugin vraagt de MetriXs-API om een eenmalige challangetoken, servet hem vanaf je eigen domein en de API haalt hem terug. Alleen iemand die jouw domein beheert kan de token serveren — dat bewijst eigendom De token wordt weer verwijderd zodra de uitwisseling klaar is.

Instellingenreferentie

Instelling	Standaard	Betekenis
Enable tracking	Uit	Hoofdschakelaar — er wordt niets geladen tot de site verbonden is en dit aan staat
Site API key	—	Sitespecifieke sleutel uit het dashboard
MetriXs URL	https://app.metrixs.eu	Alleen wijzigen voor eigen endpoints (alleen HTTPS)
Site domain	Leeg (auto)	Moet overeenkomen met het domein in MetriXs
Exclude admins	Aan	Gebruikers met beheerderstoegang niet volgen

Het tracker-script wordt vanaf app.metrixs.eu geleverd met een geversioneerde URL, geïnjecteerd in de pagina-output en asynchroon (defer) geladen. Hij werkt prima naast Grav’s page caching en agressieve caching-setups.

Problemen oplossen

Verificatie mislukt

• Zorg dat je site openbaar bereikbaar is via HTTPS (geen onderhoudsmodus, geen firewall die de MetriXs-servers blokkeert)
• Sla de plugin-instellingen opnieuw op — de uitwisseling draait bij elk opslaan
• 2.0-Admin/API-stack in gebruik? Zorg dat de API-plugin geïnstalleerd is en dat je in de beheeromgeving bent ingelogd

Geen data in het dashboard

• De plugin-instellingen moeten de “site verified”-bevestiging hebben getoond
• Enable tracking moet aan staan
• Het sitedomein moet exact overeenkomen met het domein in MetriXs (zonder www., zonder https://)
• Ben je als beheerder ingelogd? Standaard uitgesloten — test incognito

API-sleutel kwijt Sleutels zijn na aanmaak niet op te halen. Trek de oude in het dashboard in (Instellingen → Sites → API-sleutels), maak een nieuwe aan en vul die in de plugin in.

Configureren zonder de Admin-plugin De auto-verificatie draait bij het opslaan van beheerinstellingen. Installeer de Admin-plugin voor de automatische flow — zonder hem is er geen interface die de verificatie-uitwisseling triggert. Als handmatig alternatief kan een ontwikkelaar de MetriXs-API direct aanroepen met de sitesleutel: vraag een challenge aan (POST /api/integrations/grav/challenge), plak de teruggegeven token als challenge in de yaml en roep daarna (POST /api/integrations/grav/verify) aan.

Deinstalleren

Als je de plugin verwijdert:

• Je site wordt niet automatisch ontkoppeld in MetriXs (Grav-plugins hebben geen de-installatiehook) — trek de API-sleutel in het dashboard in (Instellingen → Sites → API-sleutels) om de invoer te stoppen
• Je historische gegevens blijven in je MetriXs-account

Liever zonder plugin?

Je kunt de tracker altijd handmatig toevoegen met het fragment uit de platformguides — de plugin automatiseert alleen installatie en verificatie.