Grav plugin

MetriXs has a first-party Grav plugin that adds the tracker to every page of your site, verifies your site automatically, and stays strictly opt-in: nothing loads until you connect it. No theme editing, no Twig snippets, no consent banner.

This guide walks through the full setup, step by step.

Before you start

You need a MetriXs account. The plugin itself is free and fully functional; a free MetriXs plan is enough to get started.

1. Go to app.metrixs.eu and sign up
2. Verify your email address via the link you receive

Step 1: Add your site in MetriXs

1. Log in to the MetriXs dashboard
2. During onboarding (or via Settings → Sites), add your site’s domain, e.g. yourdomain.com — without https:// and without www.
3. Skip the dashboard’s snippet verification step — the plugin verifies your site automatically in step 4
4. If prompted, start a trial or pick the free plan (events require an active plan)

Step 2: Create a site API key

The plugin authenticates with a site-scoped API key. It only grants access to that one site (stats:read + event:write), never to your account, and can be revoked at any time.

1. In the dashboard, go to Settings → Sites
2. Expand your site and find the API keys section
3. Click Create API key and give it a name, e.g. “Grav”
4. Copy the key (mtx_live_...) immediately — it is shown once and cannot be retrieved later

Step 3: Install the plugin

Install it via GPM from your Grav root:

bin/gpm install mx-cookieless-analytics

or in the Admin plugin, go to Plugins → Add and search for MX Cookieless Analytics. You can also download the ZIP from the GitHub releases page and unzip it into user/plugins/mx-cookieless-analytics.

The plugin is tested on Grav 1.7 and 2.0 (classic Admin and the 2.0 Admin/API stack).

Step 4: Configure the plugin

In the Admin plugin, go to Plugins → MX Cookieless Analytics:

Field	What to enter
Enable tracking	Leave off for now — turn on after verification (step 4)
Site API key	The key from step 2
MetriXs URL	Leave at the default https://app.metrixs.eu
Site domain	Leave empty to auto-detect from the configured site URL
Exclude admins	On by default — users with admin access don’t count

Click Save. The plugin verifies your site automatically with the same save — you should see the green notice “site verified” (or an error message explaining what to check).

Step 5: Verify tracking works

1. Make sure Enable tracking is on and save
2. Open your site in an incognito/private window and browse a few pages
3. Open the MetriXs dashboard and check the Realtime view — pageviews should appear within seconds

Note: users with admin access are excluded from tracking by default. Regular logged-in users (members) are tracked. Test from an incognito window or adjust the exclusion in the plugin settings.

How the verification works: the plugin asks the MetriXs API for a one-time challenge token, serves it from your own domain, and the API fetches it back. Only someone who controls your domain can serve the token, so this proves ownership. The token is removed again once the handshake is done.

Settings reference

Setting	Default	Meaning
Enable tracking	Off	Master switch — nothing loads until the site is connected and this is on
Site API key	—	Site-scoped key from the dashboard
MetriXs URL	https://app.metrixs.eu	Only change for custom endpoints (HTTPS only)
Site domain	Empty (auto)	Must match the domain in MetriXs
Exclude admins	On	Don’t track users with admin access

The tracker script is served from app.metrixs.eu with a versioned URL, injected into the page output and loaded asynchronously (defer). It works fine alongside Grav’s page caching and AGgressive caching setups.

Troubleshooting

Verification fails

• Make sure your site is publicly reachable over HTTPS (no maintenance mode, no firewall blocking the MetriXs servers)
• Save the plugin settings again — the handshake runs on every save
• Using the 2.0 Admin/API stack? Make sure the API plugin is installed and you are logged in to the admin

No data in the dashboard

• The plugin settings must have shown the “site verified” confirmation
• Enable tracking must be on
• The site domain must exactly match the domain in MetriXs (no www., no https://)
• You are logged in as an admin? You’re excluded by default — test incognito

API key lost Keys cannot be retrieved after creation. Revoke the old one in the dashboard (Settings → Sites → API keys), create a new one, and update it in the plugin settings.

Configuring without the Admin plugin The auto-verification runs on an admin settings save. If your site has no Admin plugin, install it for the automatic flow — without it there is no UI to trigger the verification handshake. As a manual alternative, a developer can call the MetriXs API directly with the site API key: request a challenge (POST /api/integrations/grav/challenge), paste the returned token as challenge into the yaml, then call (POST /api/integrations/grav/verify).

Uninstalling

When you remove the plugin:

• Your site is not automatically disconnected in MetriXs (Grav plugins have no uninstall hook) — revoke the API key in the dashboard (Settings → Sites → API keys) to stop ingestion
• Your historical data stays in your MetriXs account

Prefer no plugin?

You can always add the tracker manually with the snippet from the platform guides — the plugin simply automates installation and verification.