Instalar el script qm.js

La forma más sencilla de medir un sitio: un script de menos de 4 KB comprimido que no escribe ningún identificador en el dispositivo de sus visitantes, ni en cookie ni en localStorage. Solo dos escrituras son posibles, y ninguna distingue a una persona de otra: el marcador de exclusión qm_ignore, que la persona coloca ella misma para dejar de ser contada, y la cookie de continuidad de visita qm_visit, de diez minutos deslizantes. Esa ausencia de cookie de identificación y de rastreo no garantiza por sí sola una exención de consentimiento: cargue el script según sus finalidades documentadas, las funciones activadas y su base jurídica.

Inicio rápido

1. Obtenga su clave de sitio. En su panel, abra Sitios → su sitio → Instalación. Su clave pública tiene esta forma: qm_pub_XXXXXXXXXXXXXXXXX. Es visible en el HTML, lo cual es normal; la clave secreta, en cambio, no debe aparecer nunca en el lado del navegador.

2. Añada el script. Copie el archivo qm.js propuesto en la pantalla de instalación a la raíz de su sitio: servido desde su dominio, el seguimiento sigue siendo first-party y las listas de bloqueo por dominio no surten efecto:

<script defer src="/qm.js" data-site="qm_pub_XXXXXXXXXXXXXXXXX"></script>

El script deduce su endpoint de recogida de su propio origen (…/qm.js → …/collect). Si se sirve desde su dominio, reenvíe los hits con el proxy first-party; si no, cárguelo directamente desde la plataforma:

<script defer src="https://quietmetrics.dev/qm.js"
        data-site="qm_pub_XXXXXXXXXXXXXXXXX"
        data-endpoint="https://quietmetrics.dev/api/v1/collect"></script>

3. Verifique. La pantalla de instalación comprueba en directo la recepción del primer hit. Visite su sitio: la marca de verificación se pone verde.

Opciones del script

Aplicaciones de página única (SPA)

Por defecto, cada history.pushState() genera una página vista: React Router, Vue Router, Inertia, Livewire… funcionan sin hacer nada. Dos precisiones:

• Una navegación hacia la misma URL no emite un duplicado.
• El script se protege de las dobles inclusiones (window.__qmLoaded): si su bundler y su layout lo inyectan ambos, solo cuenta uno.

Para el disparo manual (router exótico, navegación por hash): desactive el seguimiento automático (data-spa="false") y llame a qm.pageview() después de cada navegación.

Eventos personalizados

<script>
  qm('registro', { plan: 'pro', source: 'landing' });
</script>

Reglas: nombre ≤ 120 caracteres, ≤ 30 propiedades escalares (cadena, número, booleano; sin objetos anidados), valores truncados a 190 caracteres. Evite los valores de alta cardinalidad (ID de usuario, correo electrónico): son datos personales y saturan los agregados.

Si el script aún no se ha cargado, encole sin riesgo:

<script>window.qm = window.qm || function () { (window.qm.q = window.qm.q || []).push(arguments); };</script>

Para contar una conversión, cree el objetivo correspondiente en Sitios → Objetivos: un objetivo de tipo evento coincide con el nombre exacto; un objetivo de tipo página coincide con una ruta con comodines (/gracias, /docs/*).

Sin JavaScript: el píxel

Para los contextos sin JS (correos electrónicos, AMP, <noscript>), un GIF de 1×1 cuenta una página vista:

<noscript><img src="https://quietmetrics.dev/p.gif?k=qm_pub_XXXXXXXXXXXXXXXXX&u=https%3A%2F%2Fmisitio.es%2Fpage" alt=""></noscript>

El píxel responde siempre 200 (nunca una imagen rota); el estado real lo transporta la cabecera X-QM-Status.

Dejar de ser contado: el marcador de exclusión

Cualquier persona puede pedir que se deje de contarla en su sitio, sin cuenta y sin escribir a nadie: carga cualquier URL del sitio con ?qm_ignore=1, y ?qm_ignore=0 la devuelve a la medición.

https://misitio.es/?qm_ignore=1     dejar de ser contado
https://misitio.es/?qm_ignore=0     volver a ser contado

El marcador es una cookie propia de su sitio, llamada qm_ignore y con el valor 1 (path=/, samesite=lax, secure en https, cinco años), que qm.js duplica además en localStorage. Dos almacenamientos y no uno: la cookie es el único de los dos que un SDK de servidor sabe leer, y localStorage toma el relevo allí donde la cookie se rechaza o se borra. Una sola visita cubre por tanto el script y el seguimiento de servidor.

No contiene ningún identificador, ya que su valor es el mismo para todo el mundo, nunca se transmite a Quiet Metrics y solo existe para detener la medición: es un marcador de rechazo, no un rastreador. La visita que lo coloca no se cuenta; la que lo retira se cuenta de inmediato.

Es también la forma más sencilla de excluir sus propias visitas, desde cualquier navegador. Las demás integraciones respetan el mismo marcador con el mismo nombre: PHP, Laravel, Symfony y el plugin de WordPress.

La cookie de continuidad de visita

Lo segundo, y último, que se escribe en el equipo de sus visitantes. No se confunde con lo anterior: aquello lo pide la persona, esto lo coloca la medición.

Se llama qm_visit, vale 1, y es una cookie propia de su sitio (path=/, samesite=lax, secure en https) cuya caducidad se desliza diez minutos y se refresca en cada hit. Sin duplicado en localStorage, a diferencia del marcador de exclusión.

Lo que corrige: la huella que distingue a sus visitantes se recalcula en cada hit a partir de la red del abonado y del navegador. Cuando esa red cambia durante la visita, típicamente al pasar de los datos móviles al wifi, la huella cambia con ella y la misma persona cuenta como dos visitantes únicos en su panel. La cookie aporta el dato que falta: ya hay una visita en curso en este navegador.

No contiene ningún identificador, ya que su valor es el mismo para todo el mundo; solo su presencia se comunica, en forma de la clave c del payload de recogida. Y nunca se coloca en un visitante que lleva qm_ignore: el marcador de exclusión corta la medición antes de cualquier escritura.

Al servir a la medición y no al registro de una negativa, esta cookie no se beneficia de la exención propia del marcador de exclusión: trátela como el resto de su configuración de medición, a la vista de sus finalidades y de su base jurídica.

Casos particulares

Content-Security-Policy. Copia local: script-src 'self' es suficiente, más connect-src 'self' si el proxy first-party está en el mismo dominio. Carga directa desde la plataforma: añada https://quietmetrics.dev a script-src y a connect-src.

Caché y CDN. La copia local de qm.js puede cachearse de forma agresiva sin riesgo: el archivo es estable. Tras una actualización del tracker, vuelva a descargar la copia desde la pantalla de instalación (añada ?v=2 a la URL del script si su CDN ignora las invalidaciones).

Varios dominios. Un sitio puede declarar dominios adicionales (Sitios → Dominios). La política de origen log (por defecto) acepta todos los hosts registrándolos; strict rechaza (403) los hits cuya URL no corresponde al dominio principal, a un dominio declarado o a sus subdominios.

Excluir sus propias visitas. Tres mecanismos: el marcador de exclusión de más arriba (una visita a ?qm_ignore=1, desde cualquier navegador), la autoexclusión del propietario en el panel (su navegador es reconocido), o window.__qmDisable = true establecido por su entorno (extensión, staging, consola).

Entornos de prueba. Cree un sitio separado con su propia clave para el staging, o excluya sus rutas: no contamine las estadísticas de producción.

Límites de la ruta caliente

El endpoint de recogida protege la plataforma: payload ≤ 4 KB (400 si se supera), 60 hits/minuto por IP y por sitio (429 si se supera), clave desconocida u origen rechazado → 403. Todas estas respuestas son invisibles para sus visitantes: la analítica nunca rompe la página.

Los visitantes sin JavaScript también pueden contarse en el lado del servidor: véase el SDK PHP, Laravel, Symfony o el plugin de WordPress.