Un botón por cada cosa que Umami sabe hacer.

El clic más simple

data-umami-event

• fichaa1

Sale un evento con nombre y una propiedad. El rastreador escucha los clics de todo el documento y busca el atributo hacia arriba, así que funciona aunque pulses el icono de dentro del botón y no el botón.

En el panelEventos → lab-clic

El mismo evento en otro sitio

data-umami-event

• fichaa2

Mismo nombre que la ficha anterior, otro valor de la propiedad. En el panel siguen siendo un solo contador hasta que abres el desglose: ahí se parte en dos barras. Es la diferencia entre saber cuánta gente pulsa y saber dónde.

En el panelEventos → lab-clic → Propiedades → ficha

Tres propiedades en un solo clic

data-umami-event

• fichaa3
• varianteoscura
• posicionderecha

Umami guarda cada clave por separado y las tres se pueden cruzar. Ojo al detalle: por esta vía todos los valores llegan como texto, aunque parezcan números. Los números de verdad son cosa del bloque B.

En el panelEventos → lab-clic-rico → Propiedades

Un enlace que se va a otra pestaña

data-umami-event en un enlace con target="_blank"

• destinoexample.com

En un enlace normal el rastreador cancela la navegación, espera a que el evento salga y después te lleva. Con target="_blank" no espera: la pestaña nueva se abre sola y el evento viaja en paralelo. Por eso la petición de navegación no aparece en el Network de esta pestaña: aparece en la otra.

En el panelEventos → lab-externo

El antiejemplo: una propiedad distinta cada vez

data-umami-event con un valor aleatorio por clic

• idun identificador nuevo en cada clic

Púlsalo diez veces y mira el desglose: diez filas de un evento cada una. La propiedad es técnicamente correcta y analíticamente inútil. Esto es lo que el sitio de verdad evita metiendo los valores en cubos.

En el panelEventos → lab-cardinalidad → Propiedades → id

Un valor que el HTML no podía saber

umami.track(nombre, datos)

• opcionla que elijas en el desplegable

La regla del proyecto es que si el valor se puede escribir en el HTML, va en el HTML. Esta ficha es el otro caso: el valor se decide en el navegador, así que hace falta una línea de JavaScript.

En el panelEventos → lab-programatico → Propiedades → opcion

Una propiedad numérica

umami.track() con un número, no una cadena

• importeun número entre 200 y 5000
• monedaMXN

Compáralo con la ficha a5. Una propiedad de texto se cuenta por valor; una numérica se agrega, y el panel te da promedio, mínimo, máximo y suma. Es la diferencia entre «cuántos cotizaron» y «cuánto sumaron las cotizaciones».

En el panelEventos → lab-importe → Propiedades → importe

Una vista de página que no existe

umami.track(base => ({ ...base, url, title }))

• url/laboratorio/paso-2
• titlePaso 2

No se navega a ningún lado, pero Umami registra una visita a /laboratorio/paso-2. Así se miden los pasos de un asistente, los modales o una aplicación de una sola página, donde la URL del navegador nunca cambia.

En el panelPáginas → /laboratorio/paso-2

El fallo deliberado

umami.track({ url: "/mal" })

Un objeto suelto se envía tal cual, sin mezclarse con los datos que el rastreador calcula: va sin el id del sitio y el servidor lo rechaza. En la consola de abajo lo verás marcado en rojo. En el panel de Umami no verás nada, que es justo la lección: la forma correcta es la de la ficha b3.

En el panelEn ningún sitio. Ese es el punto.

Una vista de página a secas

umami.track() sin argumentos

Cuenta otra visita a la página actual. Fíjate en la consola: una vista y un evento se mandan por el mismo canal y con el mismo sobre; lo único que las distingue es que la vista no lleva nombre.

En el panelPáginas → /laboratorio

Cambiar la URL sin recargar

history.pushState()

• url/laboratorio/paso-3

El rastreador vigila el historial por su cuenta. Al empujar una URL nueva espera 300 ms —para no contar tres vistas si el enrutador hace tres saltos seguidos— y manda la visita solo. Esto es lo que hace que Umami funcione en una SPA sin escribir nada. Segundo y medio después la URL vuelve a su sitio para que recargar no acabe en un 404, y eso genera una segunda vista de /laboratorio: el rastreador no distingue nuestra limpieza de una navegación de verdad.

En el panelPáginas → /laboratorio/paso-3

Datos que se pegan a la visita

umami.identify() y después umami.track()

• plangratis · pro · empresa
• roladmin · editor

Primero sale un envío de tipo identify con esos datos y después un evento normal. La diferencia es el alcance: las propiedades de un evento describen ese clic, las de identify describen a quien está navegando y acompañan a todo lo que venga después en la misma sesión.

En el panelSesiones → propiedades de sesión

Un identificador estable entre visitas

umami.identify("cliente-042")

• idcliente-042

Con un id propio, dos visitas en días distintos son la misma persona para Umami. Al identificar, el rastreador tira su caché de sesión y deja que el servidor la resuelva otra vez. Debajo se imprime lo que devuelve getSession().

En el panelSesiones → busca el id

Profundidad de scroll

escucha de scroll, una vez por tramo

• profundidad25 · 50 · 75 · 100

Baja por esta página y se disparan hasta cuatro eventos, uno por cuarto alcanzado y sin repetirse. Es la métrica que dice si la gente llega al final de una página larga o abandona en el primer pliegue.

En el panelEventos → lab-scroll → Propiedades → profundidad

Tiempo mirando una zona

IntersectionObserver + reloj

• tramo0-10s · 10-30s · 30-60s · 60s+

El reloj corre mientras el recuadro está en pantalla y se para cuando sale. El valor no es el número de segundos sino el tramo: una propiedad con mil valores distintos no responde ninguna pregunta (ver la ficha a5).

En el panelEventos → lab-atencion → Propiedades → tramo

Interés sin clic

puntero quieto encima durante 1,5 s

• zonatarjeta-precio

Deja el ratón encima del recuadro sin pulsar. Mide la duda: gente que se para en el precio y no pulsa. Solo con ratón, y a propósito: en un móvil no existe el concepto de estar encima sin tocar.

En el panelEventos → lab-interes

Clic de rabia

tres clics en menos de 700 ms

• zonaalgo-que-no-responde

Pulsa tres veces seguidas y rápido sobre algo que no hace nada. Es la señal clásica de frustración: si esta cifra sube sobre un elemento concreto, la gente cree que ese elemento es un botón y no lo es.

En el panelEventos → lab-rabia

Un error de JavaScript

window.addEventListener("error")

• tipoTypeError · ReferenceError · Error

El botón lanza una excepción de verdad, que sube hasta window y se convierte en un evento. Umami no es un Sentry, pero para un sitio pequeño saber que algo se rompe —y en qué página— vale más que no saberlo. Solo se manda el tipo del error, nunca el mensaje: los mensajes traen datos dentro.

En el panelEventos → lab-error → Propiedades → tipo

La salida

visibilitychange → hidden

• permanencia0-10s · 10-30s · 30-60s · 60s+

Cambia de pestaña y mira la consola al volver. El navegador ya no garantiza nada en el evento de cierre, por eso se usa visibilitychange y no unload; el rastreador manda la petición con keepalive para que sobreviva a la pestaña que se va.

En el panelEventos → lab-salida → Propiedades → permanencia

El gancho que ya tenía el sitio

data-evento-al-cargar (scripts/eventos.ts)

• origenutm_source, dominio del referente o «directo»

Este no lo dispara el laboratorio: lo dispara el mismo código que mide la página de gracias, sin una línea nueva. Ya salió al cargar la página, así que búscalo arriba del todo en la consola. Solo puede haber uno por página: ese script busca el atributo en singular.

En el panelEventos → lab-al-cargar → Propiedades → origen

Diagnóstico del rastreador

lectura del estado, no manda nada

Todo lo que puede dejar el panel vacío sin dar un solo error: que el script venga bloqueado, que el dominio no esté en la lista de data-domains, que alguien dejara puesto el silenciador, que el navegador pida no rastrear. Si la consola de abajo está muda, la respuesta está aquí arriba.

En el panelEn esta misma página.

Consentimiento en una línea

data-before-send devolviendo false

Con el interruptor puesto, los clics siguen ocurriendo y el gancho sigue viéndolos, pero nada sale del navegador: la consola lo marca como cancelado y en el Network no aparece ninguna petición. Es un banner de cookies completo en una función de tres líneas.

En el panelEn ningún sitio, que es lo que se quiere.

El silenciador reversible

localStorage["umami.disabled"]

El rastreador lo consulta en cada envío, así que se apaga y se enciende sin recompilar. Es lo que conviene dejar puesto en el navegador desde el que administras el sitio, para no contarte a ti mismo. Y es una de las razones por las que un panel amanece vacío sin que nadie haya roto nada.

En el panelEn ningún sitio mientras esté puesto.

Los interruptores de la etiqueta script

data-tag · data-performance · data-auto-pageview

Estos no se leen en cada envío sino una sola vez, al cargar: por eso hay que recargar para que surtan efecto, y por eso son la lección de que no todo se cambia en caliente. data-tag marca cada envío con una etiqueta para filtrar el panel, data-performance añade las métricas web y data-auto-pageview en false apaga la vista automática.

En el panelPanel → filtro por etiqueta, y Eventos → envíos de tipo performance.