Por que partes de tu pagina aparecen cortadas en tu heatmap de Matomo (y como arreglarlo)

Si has abierto un heatmap de Matomo y has visto la barra lateral truncada, la mitad inferior de un modal que falta, o marcadores de clic flotando sobre contenido que no parece corresponderles, los clics en si estan bien. Matomo los registro en las coordenadas correctas. Lo que esta roto es la captura de pantalla que tienen debajo. Algun wrapper de la pagina tiene overflow: hidden, overflow: auto o overflow: scroll, y el renderizador de Matomo trata todo lo que queda mas alla del borde visible de ese wrapper como si no existiera. Asi que el heatmap te muestra un recorte de la pagina en vez de la pagina que vieron tus visitantes.

La solucion mas rapida es una extension gratuita de Chrome que mantenemos nosotros llamada Matomo Heatmap Helper. Neutraliza los contenedores con overflow justo antes de cada captura, deja que el renderizador vea el documento completo y restaura los estilos originales despues. El resto de este post explica como hacer lo mismo sin la extension, mas algunas soluciones permanentes que merece la pena publicar.

Como arreglarlo sin la extension

Hay un snippet de consola que tapa el problema justo antes de cada captura, y algunas soluciones permanentes que puedes publicar con el sitio. Elige la que mejor se adapte a las restricciones con las que trabajas.

Lista todos los elementos con overflow restringido en la pagina

Antes de cambiar nada, averigua que wrappers estan recortando. Abre la pagina en Chrome, pulsa F12 para abrir las DevTools, cambia a la Consola y pega:

// Lists every element that's currently clipping content
Array.from(document.querySelectorAll('*')).filter(el => {
  const s = getComputedStyle(el);
  return ['hidden','auto','scroll'].includes(s.overflow)
      || ['hidden','auto','scroll'].includes(s.overflowY);
});

Esto te da la lista exacta de nodos que el renderizador de Matomo va a tratar como cajas de tamano fijo. Los sospechosos habituales son barras laterales, modales, wrappers de scroll personalizados alrededor de <main> y wrappers de clearfix antiguos con overflow: hidden por razones de layout que llevan anos sin ser relevantes.

La solucion rapida: eliminar las restricciones de overflow desde la consola

Este es el snippet que pegamos en la consola del navegador justo antes de lanzar la captura del heatmap de Matomo. Recorre cada elemento que esta recortando y le pone overflow y overflow-y a visible. Cuando Matomo serializa el DOM, nada esta ocultando contenido mas alla de un borde visible.

// Paste into the browser console right before capture.
// Turns every overflow container on the page into 'visible'.
document.querySelectorAll('*').forEach(el => {
  const s = getComputedStyle(el);
  if (['hidden','auto','scroll'].includes(s.overflow) ||
      ['hidden','auto','scroll'].includes(s.overflowY)) {
    el.style.overflow = 'visible';
    el.style.overflowY = 'visible';
  }
});

La pagina va a tener un aspecto extrano por un momento. Las barras laterales se expanden hasta su altura completa de contenido, los modales se estiran mas alla del borde del viewport, y cualquier cosa que dependia de un contenedor de altura fija de repente ya no lo tiene. No pasa nada. Estas haciendo la captura del heatmap, no navegando por el sitio. Actualiza cuando hayas terminado.

Esa es la via rapida. Funciona para capturas puntuales y los ciclos de revision en los que necesitas una captura limpia ahora y no quieres esperar a un cambio de codigo. Para lo que vayas a volver a capturar con regularidad, publica una de las soluciones permanentes que vienen a continuacion.

Solucion CSS permanente limitada al modo de captura

La respuesta mas limpia cuando controlas la hoja de estilos es una override solo para heatmaps que desactiva cada contenedor con overflow en el momento en que el tracker de Matomo se carga. Un bloque CSS, una linea de JavaScript y listo.

/* Edit the selectors to match the wrappers on your site */
html.heatmap-mode .sidebar,
html.heatmap-mode main,
html.heatmap-mode .modal-shell {
  overflow: visible !important;
  overflow-y: visible !important;
  height: auto !important;
  max-height: none !important;
}

// Add to your site. Flips the class on whenever Matomo's tracker is on the page.
if (window._paq) document.documentElement.classList.add('heatmap-mode');

Asi la override solo se activa en paginas donde Matomo se esta cargando de todas formas, lo que esta bien para una revision de heatmap y es invisible para el resto de tu trafico. Si prefieres limitarlo mas, controlalo con un parametro de query (?heatmap=1) o una hoja de estilos separada que solo se incluya en la copia de staging a la que apuntas Matomo.

Eliminar el contenedor de scroll anidado del todo

Si tu pagina tiene overflow: auto en <main> o en algun otro wrapper por razones de "scrollytelling", la solucion arquitectonica es eliminarlo y dejar que el documento haga scroll. El renderizador de Matomo puede reproducir el scroll del documento, pero no puede reproducir la posicion de scroll interna de un contenedor anidado con scroll. Ademas mejoras la UX movil (iOS Safari tiene sus propias opiniones sobre los contenedores de scroll anidados) y la accesibilidad mejora porque el scroll con teclado y la navegacion por lector de pantalla empiezan a funcionar como los usuarios esperan.

Es un cambio mayor que la override de CSS, pero es el que evita que el problema vuelva la proxima vez que alguien anade una nueva seccion al layout.

Reemplaza el clearfix overflow: hidden con display: flow-root

Los wrappers de clearfix antiguos con overflow: hidden eran un workaround para contener hijos flotantes. display: flow-root hace lo mismo sin recortar nada, y es seguro usarlo en todos los navegadores que merezca la pena soportar desde 2018.

/* Edit the selector to match your clearfix wrapper */
.row-with-floats {
  display: flow-root;
}

El mismo comportamiento de contencion, sin recorte, y dejas de pelearte con la captura. La forma rapida de encontrar candidatos es buscar en tu CSS overflow: hidden y comprobar si cada uno tiene la intencion real de recortar algo. La mayoria de las veces, no.

Una nota sobre el trade-off

Sea cual sea la solucion permanente que elijas, limita la override (una clase, un parametro de query, una hoja de estilos solo para heatmaps) en vez de cambiar los estilos en vivo para todos. Tus visitantes estan viendo el layout que disenaste para ellos, y el modal que se supone que hace scroll dentro de su propia caja deberia seguir haciendolo para ellos. La override solo necesita existir para el renderizador al que Matomo apunta la pagina.

Por que Matomo no puede renderizar tus contenedores con overflow

La captura de pantalla de Matomo es un proceso en dos pasos. Primero, el tracker serializa tu DOM en vivo en HTML y lo envia. Despues, tu servidor de Matomo vuelve a renderizar ese HTML a un viewport fijo para producir la captura que ves en la vista del heatmap. Sin sesion de navegador, sin posicion de scroll del visitante, sin ajustes de layout basados en JavaScript. Solo un archivo HTML renderizandose en frio desde una IP diferente.

El renderizador puede reproducir el scroll del documento, por eso las paginas largas se capturan bien. Lo que no puede reproducir es la posicion de scroll interna de un contenedor anidado con overflow: auto, porque eso vive en el navegador del visitante y nunca llega al DOM serializado. Cuando el renderizador se encuentra con un wrapper overflow: hidden, hace lo que hace cualquier navegador y recorta. El resultado es una captura que parece el recorte visible de la pagina en un momento concreto, con todo lo demas eliminado.

Las coordenadas de los clics lo empeoran. Matomo registra los clics relativos al documento, no relativos a la posicion de scroll interna del contenedor que el usuario estaba desplazando. Un clic en el tercer elemento de una barra lateral con scroll se almacena en la coordenada y que tenia en el momento del clic. Cuando el renderizador hace la captura de la barra lateral con scroll-top a cero, esa coordenada y ahora pertenece al primer elemento. El marcador se pone ahi. El clic parece que cayo en el enlace equivocado.

Que esta fallando realmente

Unos cuantos patrones con los que nos seguimos encontrando:

• Barras laterales y modales con sus propias barras de scroll. El wrapper tiene una altura fija y overflow: auto, la lista interior es mas alta, y solo la parte visible en el momento de la captura llega a la captura.
• Paginas de "scrollytelling" con overflow: auto en <main> o un wrapper similar. El body no hace scroll, el elemento interior si, y el heatmap captura un viewport de contenido.
• Wrappers de clearfix heredados con overflow: hidden que no tienen la intencion real de recortar nada. Estaban pensados para contener floats. Siguen recortando, y siguen eliminando contenido de la captura.
• Menus desplegables personalizados o acordeones que animan recortando su contenido con overflow: hidden mas una transicion de altura. El estado cerrado es lo que ve Matomo.
• CSS mask o clip-path en un contenedor. Propiedad diferente, mismo efecto en la captura. La solucion es la misma: desactivalo en el modo de captura.

Si a tu heatmap le falta contenido o los marcadores de clic no coinciden con los elementos que esperarias, estas sufriendo al menos uno de estos. A menudo mas de uno en la misma pagina.

Esta es tambien la misma familia de problema que rompe fuentes, imagenes y encabezados sticky en la misma captura. Hemos escrito un post mas largo sobre capturas de heatmap de Matomo rotas que recorre el resto, y posts separados sobre por que las fuentes no cargan y por que las imagenes no cargan ya que aparecen casi con la misma frecuencia.

Lo que nosotros hariamos

Si controlas la hoja de estilos, publica la override solo para heatmaps. Un bloque CSS limitado a una clase que activas cuando el tracker de Matomo se carga. Es el diff minimo que resuelve el problema de forma permanente y no toca lo que ven los visitantes.

Si el layout tiene un contenedor de scroll anidado que te ha estado molestando por otras razones tambien, toma la solucion arquitectonica y deja que el documento haga scroll. Te ahorrara este problema en cada captura de heatmap futura, y tus usuarios moviles te lo agradeceran.

Si ninguna de las dos opciones es alcanzable (sin acceso a la hoja de estilos, widgets de terceros que no puedes reestilizar, un CMS que no te deja publicar CSS personalizado), la extension Matomo Heatmap Helper para Chrome es lo que usamos en sitios de clientes donde no podemos cambiar el stack. Recorre los mismos contenedores con overflow que encuentra el snippet, los neutraliza para la captura y los restaura despues, asi la pagina esta intacta para el siguiente visitante. Gratuita, de codigo abierto, codigo en GitHub.

Martez es el proyecto mas amplio del que salio la extension. Conecta Matomo con Meta Ads y Google Ads para que el ROAS, el CLV y la atribucion esten junto a tu analitica web en vez de en una hoja de calculo aparte. Esta en beta privada. Unete a la lista de espera si eso te resulta relevante.

La mayoria de las veces, esto esta a un cambio de hoja de estilos de distancia. Vale la pena hacerlo una vez.