Come gestiamo gli screenshot rotti delle heatmap di Matomo

Se hai aperto una heatmap di Matomo e hai trovato un rettangolo bianco al posto dell'immagine hero, o una griglia prodotti che si taglia dopo la prima riga, o un header sticky piazzato sopra il contenuto della pagina, non sei il primo. Gli screenshot delle heatmap si rompono sulla maggior parte dei siti moderni out of the box. Il motivo è strutturale, non qualcosa che si risolve modificando la configurazione del tracciamento.

Lo script di tracciamento di Matomo serializza il DOM della tua pagina in HTML e lo spedisce al server Matomo. Il server poi ri-renderizza quell'HTML in un contesto completamente diverso per produrre lo screenshot che vedi. Niente cookie. Niente sessione. Origine diversa. Niente del runtime che il tuo framework JavaScript aveva impostato. Molte cose che funzionavano perché giravano in un browser vero smettono di funzionare silenziosamente quando lo stesso HTML viene ri-renderizzato a freddo da qualche altra parte.

Una volta capita questa cosa, la lista dei bug inizia ad avere senso.

I pattern che continuiamo a incontrare

La maggior parte dei siti ne colpisce almeno tre. Alcuni li colpiscono tutti e sei.

• CORS blocca le immagini e i font ospitati sul CDN, perché il server Matomo non ha le credenziali del tuo dominio. Le immagini escono come icone rotte. I font ripiegano sui default di sistema.
• I container con scroll (overflow: hidden o overflow: auto con altezza fissa) tagliano tutto ciò che è sotto l'area visibile. Matomo serializza il DOM nel suo stato attuale, quindi quello che non era sullo schermo al momento della cattura non finisce nello snapshot.
• Gli header sticky e fixed collassano sul contenuto sottostante. Le loro posizioni vengono calcolate rispetto a una viewport, e lato server non c'è nessuna viewport, quindi si piazzano dove cadono nel DOM.
• Gli URL relativi come /images/hero.jpg si risolvono rispetto al server Matomo invece che al tuo. Il file lì non esiste, quindi fallisce in silenzio.
• I font personalizzati caricati via @font-face ripiegano sui default di sistema quando i file font sono protetti da CORS o bloccano lo user-agent del server Matomo.
• Le single-page app vengono catturate prima che React o Vue abbiano finito il rendering, lasciando metà della pagina fuori dallo snapshot.

La maggior parte di questi problemi ha soluzioni a livello infrastrutturale. Aggiungi header CORS sul CDN. Passa a URL assoluti. Usa un hook CSS matomoHeatmap per sovrascrivere il posizionamento sticky durante la cattura. La documentazione di Matomo ne copre diversi, e abbiamo scritto un post più lungo che analizza ogni problema e come risolverlo lato server se è quella la strada che vuoi percorrere.

Il problema è che il lavoro si distribuisce su configurazione CDN, CSS e setup del tracciamento, e alcune cose non riesci a sistemarle se non controlli gli asset. Ci siamo scontrati con questo muro su abbastanza siti di clienti che alla fine abbiamo fatto un'altra cosa.

Cosa abbiamo finito per costruire

Abbiamo iniziato con un piccolo script che incollavamo in DevTools prima di ogni cattura. Incorporava immagini e font come data URI, espandeva i container con scroll, rimetteva in flusso normale gli header sticky, riscriveva gli URL relativi in assoluti. Col tempo è diventato un'estensione Chrome che usavamo internamente su ogni cliente.

Questo è Matomo Heatmap Helper. L'abbiamo resa open source.

Il setup è una schermata sola. Inserisci il tuo URL Matomo, un token API, e scegli su quali siti vuoi che compaia la toolbar. Su ogni pagina corrispondente appare una piccola barra.

Il lavoro avviene al momento della cattura. Quando premi il pulsante screenshot, l'estensione fa le cose che sono noiose da fare staticamente. Incorpora immagini e font come data URI base64 così il server Matomo non deve scaricare nulla cross-origin. Espande i container con scroll alla loro altezza completa. Converte header sticky e fixed in flusso normale. Riscrive gli URL relativi in assoluti, ridimensiona gli iframe, mette in pausa i video al fotogramma zero, e dà tempo al contenuto SPA di renderizzarsi. Poi chiama l'API screenshot di Matomo, aspetta il risultato, e annulla ogni modifica. La tua pagina live torna com'era.

Il motivo per cui funziona è che puoi interagire con gli elementi prima della cattura. Container con scroll personalizzati, un header sticky che fa i capricci, una sezione dove gli asset non si caricano: li clicchi in modalità Interactive, prendono un'icona a lucchetto, e la pipeline sa cosa fare. Lo script di tracciamento da solo non può farlo, perché cattura qualunque stato il DOM si trovi nel momento in cui gira. Lasciare che una persona indichi all'estensione quali elementi hanno bisogno di gestione è ciò che risolve i casi che lo script non avrebbe mai potuto risolvere.

L'estensione comunica solo con la tua istanza Matomo. Il tuo token API è in chrome.storage.local, che è isolato dalle pagine che visiti. Niente telemetria, niente tracciamento dell'uso. Il codice è su GitHub. Issue e pull request sono benvenute.

Perché l'abbiamo pubblicata

Come agenzia Official Matomo Partner, le heatmap rotte erano un problema che incontravamo quasi in ogni cliente. Gli eventi venivano tracciati correttamente, ma gli screenshot erano inutilizzabili, che è proprio la parte che la maggior parte degli stakeholder guarda davvero.

Matomo ci ha dato tanto come agenzia. Usiamo l'estensione ogni giorno sul lavoro con i clienti e continuiamo a migliorare i casi limite che troviamo sui siti. Se incontri problemi con le heatmap che non riesci a risolvere, apri un'issue su GitHub e vediamo se riusciamo ad aggiungere una correzione all'estensione.

Su cosa stiamo lavorando

Matomo Heatmap Helper è nata da un progetto più grande. Martez connette Matomo con Meta Ads e Google Ads, così ROAS, CLV e attribuzione multi-touch stanno accanto alla tua web analytics invece di essere in un foglio di calcolo separato. È in private beta. Se ti interessa, puoi unirti alla waitlist.

In ogni caso, l'estensione per le heatmap è una cosa a sé, e continuerà ad esserlo. L'abbiamo costruita perché ne avevamo bisogno.