Plugin de Grav

MetriXs ofrece un plugin oficial de Grav que añade el tracker a cada página de tu sitio, verifica tu sitio automáticamente y permanece estrictamente opcional: no se carga nada hasta que lo conectas. Sin editar el tema, sin snippets de Twig, sin banner de consentimiento.

Esta guía recorre toda la configuración, paso a paso.

Antes de empezar

Necesitas una cuenta de MetriXs. El plugin en sí es gratis y totalmente funcional; el plan gratuito de MetriXs es suficiente para empezar.

1. Ve a app.metrixs.eu y regístrate
2. Verifica tu dirección de correo con el enlace que recibes

Paso 1: añade tu sitio en MetriXs

1. Inicia sesión en el panel de MetriXs
2. Durante el onboarding (o en Ajustes → Sitios), añade el dominio de tu sitio, p. ej. tusitio.com — sin https:// y sin www.
3. Omite el paso de verificación del snippet que sugiere el panel — el plugin verifica tu sitio automáticamente en el paso 4
4. Si se te pide, inicia una prueba o elige el plan gratuito (los eventos requieren un plan activo)

Paso 2: crea una clave API del sitio

El plugin se autentica con una clave API del sitio. Solo da acceso a ese sitio (stats:read + event:write), nunca a tu cuenta, y puede revocarse en cualquier momento.

1. En el panel, ve a Ajustes → Sitios
2. Despliega tu sitio y busca la sección de claves API
3. Pulsa Create API key y dale un nombre, p. ej. «Grav»
4. Copia la clave (mtx_live_...) inmediatamente — se muestra una sola vez y no se puede recuperar después

Paso 3: instala el plugin

Instálalo con GPM desde la raíz de Grav:

bin/gpm install mx-cookieless-analytics

o en el plugin de administración, ve a Plugins → Añadir y busca MX Cookieless Analytics. También puedes descargar el ZIP desde la página de releases de GitHub y descomprimirlo en user/plugins/mx-cookieless-analytics.

El plugin está probado en Grav 1.7 y 2.0 (administración clásica y la pila Admin/API 2.0).

Paso 4: configura el plugin

En el plugin de administración, ve a Plugins → MX Cookieless Analytics:

Campo	Qué poner
Enable tracking	Déjalo desactivado por ahora — actívalo tras la verificación (paso 4)
Site API key	La clave del paso 2
MetriXs URL	Deja el valor por defecto https://app.metrixs.eu
Site domain	Déjalo vacío para autodetección desde la URL configurada
Exclude admins	Activado por defecto — los usuarios con acceso de administración no cuentan

Pulsa Guardar. El plugin verifica tu sitio automáticamente con ese mismo guardado — verás la confirmación verde «site verified» (o un mensaje de error explicando qué revisar).

Paso 5: comprueba el seguimiento

1. Asegúrate de que Enable tracking está activado y guarda
2. Abre tu sitio en una ventana de incógnito y navega unas páginas
3. En el panel de MetriXs, abre la vista en tiempo real — las páginas vistas deben aparecer en segundos

Nota: los usuarios con acceso de administración quedan excluidos por defecto. Los usuarios normales con sesión iniciada (miembros) sí se siguen. Prueba en incógnito o ajusta la exclusión en los ajustes del plugin.

Cómo funciona la verificación: el plugin pide a la API de MetriXs un token de desafío de un solo uso, lo sirve desde tu propio dominio y la API lo vuelve a leer. Solo alguien que controle tu dominio puede servir ese token, lo que demuestra la propiedad El token se retira una vez terminado el intercambio.

Referencia de ajustes

Ajuste	Por defecto	Significado
Enable tracking	Desactivado	Interruptor principal — no se carga nada hasta conectar el sitio y activarlo
Site API key	—	Clave del sitio desde el panel
MetriXs URL	https://app.metrixs.eu	Cambiar solo para endpoints propios (solo HTTPS)
Site domain	Vacío (auto)	Debe coincidir con el dominio en MetriXs
Exclude admins	Activado	No seguir a usuarios con acceso de administración

El script del tracker se sirve desde app.metrixs.eu con una URL versionada, se inyecta en la salida de la página y se carga de forma asíncrona (defer). Funciona sin problemas junto a la caché de páginas de Grav y configuraciones de caché más agresivas.

Solución de problemas

La verificación falla

• Asegúrate de que tu sitio es accesible públicamente por HTTPS (sin modo mantenimiento, sin firewall que bloquee los servidores de MetriXs)
• Guarda otra vez los ajustes del plugin — el intercambio se ejecuta en cada guardado
• ¿Usas la pila Admin/API 2.0? Asegúrate de que el plugin API está instalado y de que tienes sesión en la administración

Sin datos en el panel

• Los ajustes del plugin deben haber mostrado la confirmación «site verified»
• Enable tracking debe estar activado
• El dominio del sitio debe coincidir exactamente con el de MetriXs (sin www., sin https://)
• ¿Has iniciado sesión como administrador? Excluido por defecto — prueba en incógnito

Clave API perdida Las claves no se pueden recuperar tras crearlas. Revoca la antigua en el panel (Ajustes → Sitios → claves API), crea una nueva y actualízala en el plugin.

Configuración sin el plugin de administración La verificación automática se ejecuta al guardar ajustes en la administración. Instala el plugin de administración para el flujo automático — sin él no hay interfaz que dispare el intercambio de verificación. Como alternativa manual, un desarrollador puede llamar a la API de MetriXs directamente con la clave API del sitio: pedir un desafío (POST /api/integrations/grav/challenge), pegar el token devuelto como challenge en el yaml y luego llamar a (POST /api/integrations/grav/verify).

Desinstalación

Al eliminar el plugin:

• Tu sitio no se desconecta automáticamente en MetriXs (los plugins de Grav no tienen hook de desinstalación) — revoca la clave API en el panel (Ajustes → Sitios → claves API) para detener la ingesta
• Tus datos históricos permanecen en tu cuenta de MetriXs

¿Prefieres sin plugin?

Siempre puedes añadir el tracker manualmente con el fragmento de las guías de plataformas — el plugin solo automatiza la instalación y la verificación.