Come configurare il tracciamento degli errori JavaScript in Google Analytics 4 tramite Google tag Manager

Pubblicato il Aggiornato il 12 min di lettura
Come configurare il tracciamento degli errori JavaScript in Google Analytics 4 tramite Google tag Manager
Aggiungi Marketing News comeFonte preferita su Google

Perché tracciare i bug del codice direttamente su Analytics

Un malfunzionamento silenzioso nel codice del sito può azzerare le conversioni senza lasciare traccia nei log del server. Quando uno script fallisce sul browser dell'utente, la pagina non restituisce un errore HTTP 500, ma continua a funzionare in apparenza, mentre un pulsante di checkout o un modulo di contatto smettono di rispondere al clic. Rilevare questi problemi in tempo reale consente di intervenire prima che le vendite subiscano cali prolungati.

Google Analytics 4 non registra i guasti del codice front-end in modo automatico. La piattaforma offre una solida architettura a eventi, ma richiede una sorgente che intercetti l'anomalia e la trasmetta con i relativi parametri di contesto. Questa guida accompagna nell'impostazione completa del monitoraggio attraverso il sistema di gestione tag di Google, così da trasformare ogni eccezione non gestita in un evento quantificabile.

I prerequisiti e le variabili integrate da conoscere

Prima di intervenire sulla configurazione, occorre verificare il possesso dei permessi di modifica sul contenitore di Google Tag Manager e del ruolo di editor sulla proprietà di Google Analytics 4 collegata al dominio. Serve inoltre verificare che il codice del contenitore sia inserito correttamente nell'intestazione di tutte le pagine destinate al monitoraggio.

All'interno del browser avvengono diversi tipi di anomalie. Quando un'istruzione non valida blocca l'interprete, l'evento globale associato all'oggetto finestra genera alcune informazioni fondamentali. Per raccogliere questi dati senza scrivere codice complesso, Tag Manager mette a disposizione tre variabili native dedicate agli errori che occorre conoscere prima di procedere.

La prima variabile si chiama Error Message e contiene la descrizione testuale del problema, come una variabile non definita o una funzione inesistente. La seconda è Error URL, che identifica l'indirizzo esatto dello script che ha generato il blocco. La terza è Error Line, che riporta il numero di riga del file sorgente in cui si è verificata l'interruzione. Questi tre elementi formano la base diagnostica di ogni rapporto analitico.

La procedura passo a passo su Google Tag Manager

Per impostare una raccolta pulita e scalabile delle eccezioni client-side, serve una sequenza operativa precisa che colleghi l'ambiente del browser ai server di Google. In questa fase si crea un circuito chiuso: il sistema intercetta l'anomalia nel momento esatto in cui il motore del browser la rileva, estrae i valori contestuali tramite variabili dedicate e li raggruppa in un payload conforme ai requisiti di Google Analytics 4.

Esegui queste modifiche all'interno di una nuova area di lavoro separata su Tag Manager, così da non interferire con le release commerciali durante la messa a punto dei controlli. Di seguito si trovano i cinque passaggi tecnici con cui si configura l'intero flusso senza toccare i file sorgente del CMS.

Passaggio 1. Abilita le variabili native per i messaggi di errore

Accedi alla schermata di lavoro del contenitore in Tag Manager e seleziona la voce Variabili dal menu di navigazione a sinistra. Nella sezione dedicata alle variabili integrate, fai clic sul pulsante Configura situato in alto a destra.

Scorri l'elenco verso il basso fino a individuare il gruppo denominato Errori. Qui si trovano tre caselle di selezione corrispondenti a Messaggio di errore, URL errore e Riga errore. Seleziona tutte e tre le voci. Tag Manager salva immediatamente la selezione e rende disponibili queste chiavi nei menu a discesa dell'area di lavoro con i nomi convenzionali di Error Message, Error URL ed Error Line. In assenza di questo passaggio iniziale, le successive configurazioni dei tag e dei trigger non potranno richiamare i dati diagnostici essenziali.

Passaggio 2. Crea l'attivatore per gli errori di esecuzione

Spostati nella sezione Attivatori e premi il pulsante Nuovo in alto a destra. Assegna all'attivatore un nome chiaro e descrittivo, ad esempio Eccezione JavaScript Globale. Fai clic sul riquadro centrale per scegliere la tipologia di trigger.

Nel pannello laterale che compare, individua la categoria Altro e seleziona la voce Errore JavaScript. Questa impostazione istruisce il sistema ad ascoltare costantemente l'evento nativo del browser. Nella schermata di configurazione, mantieni attiva la spunta sulla voce che raccoglie tutti gli errori, oppure imposta una condizione restrittiva se desideri escludere porzioni note del sito o specifici domini di terze parti. Premi il pulsante Salva in alto a destra per registrare la regola nel contenitore prima di passare alla definizione del tag di invio.

Passaggio 3. Configura il tag di evento per Analytics

Vai nella sezione Tag e crea un nuovo elemento. Assegna un nome univoco al componente, per esempio GA4 Event - Eccezione JS, e seleziona il modello Google Analytics: evento GA4. Nel campo dedicato all'ID di misurazione, inserisci la costante che identifica il flusso web o richiama la variabile di configurazione già presente nel contenitore.

Assegna all'evento un nome conforme agli standard di raccolta, come ad esempio custom_exception oppure javascript_error. Espandi quindi la sezione Parametri evento e aggiungi le righe necessarie per trasmettere il contesto diagnostico. Nel primo parametro inserisci come nome error_message e come valore la variabile {{Error Message}}. Nel secondo parametro definisci il nome error_url con il valore {{Error URL}}. Nel terzo parametro specifica il nome error_line associato a {{Error Line}}. Per arricchire la diagnosi, aggiungi un quarto parametro facoltativo denominato page_location che raccoglie l'indirizzo della pagina su cui l'utente naviga tramite {{Page URL}}. Scorri in basso, associa l'attivatore creato in precedenza e salva il tag.

Passaggio 4. Definisci le dimensioni personalizzate su Analytics

Se invii parametri a Google Analytics 4 senza registrarli nel pannello amministrativo, non potrai visualizzarli nei rapporti standard e nelle analisi libere. Apri dunque la console di Google Analytics 4, accedi alla sezione di amministrazione tramite l'ingranaggio in basso a sinistra e clicca su registro delle definizioni personalizzate all'interno della colonna della proprietà.

Seleziona la scheda Dimensioni personalizzate e premi il pulsante Crea dimensione personalizzata. Compila la maschera per ciascuno dei parametri definiti nel tag. Per il primo elemento, assegna il nome dimensione Messaggio Errore JS, lascia l'ambito impostato su Evento e inserisci nel campo Parametro evento la stringa esatta error_message.

Ripeti l'operazione per registrare l'indirizzo dello script con il parametro error_url e una terza volta per error_line.

Passaggio 5. Esegui la verifica in anteprima e simula un guasto

Torna nell'interfaccia di Tag Manager e clicca sul pulsante Anteprima per aprire Tag Assistant. Inserisci l'indirizzo del sito e attendi il caricamento della pagina nella finestra di test. Apri gli strumenti per sviluppatori del browser: premi il tasto F12 oppure fai clic con il tasto destro del mouse e scegli la voce Ispeziona.

Accedi alla scheda Console del browser ed esegui un comando che generi un errore immediato e controllato. Si può digitare ad esempio la chiamata a una funzione inesistente come generaErroreTest() e premere Invio. La console mostrerà subito un messaggio di errore in rosso. Torna nella finestra di Tag Assistant e controlla la colonna di sinistra, dove troverai un evento denominato JavaScript Error. Seleziona questo evento e verifica che il tag GA4 Event - Eccezione JS compaia tra quelli eseguiti con successo, pronto a trasmettere i parametri verso la piattaforma.

Come risolvere il problema del testo generico Script error

Uno degli ostacoli più frequenti durante il monitoraggio dei problemi front-end consiste nella comparsa della stringa generica Script error. priva di dettagli sulla riga e sul file di origine. Questo fenomeno si verifica per ragioni di sicurezza legate alla politica di stessa origine del browser web quando il codice difettoso proviene da un dominio esterno, come una rete di distribuzione contenuti o uno strumento di terze parti.

I browser proteggono la privacy dell'utente e nascondono i dettagli delle eccezioni quando queste provengono da file esterni privi di intestazioni di condivisione delle risorse tra origini diverse. Per recuperare i dettagli completi sul codice ospitato sui server remoti o sui sottodomini statici, occorre implementare due modifiche tecniche.

Nel tag script HTML che carica il file esterno, inserisci l'attributo crossorigin="anonymous". Sul server di destinazione o sulla rete CDN che distribuisce il file JavaScript, abilita l'intestazione di risposta HTTP denominata Access-Control-Allow-Origin: * oppure imposta il dominio principale del sito. In assenza di questi due elementi congiunti, il browser continuerà a mascherare i messaggi e il rapporto analitico conterrà una percentuale elevata di voci mute.

Il tracciamento avanzato delle promesse asincrone non gestite

L'attivatore nativo di Tag Manager intercetta gli errori classici legati alla funzione window.onerror, ma ignora completamente i fallimenti delle chiamate asincrone basate su promesse che non possiedono un blocco di cattura. Nelle moderne applicazioni web a pagina singola, gran parte delle richieste asincrone verso le API si affida a queste strutture logiche.

Questa configurazione per tracciare le promesse asincrone tramite un tag HTML personalizzato con l'ascoltatore per l'evento unhandledrejection risolve una grave cecità operativa, ma non trasforma Analytics in una piattaforma per il debug dei programmatori. Se si applica il trigger su ogni singolo errore senza filtri restrittivi, si bruciano rapidamente le quote di raccolta verso i server di Google, ossia i limiti rigidi sul volume di eventi inviabili per sessione e per proprietà oltre i quali il sistema blocca i report.

Se un endpoint remoto restituisce una risposta imprevista o fallisce per timeout e il codice non gestisce il rifiuto, l'utente subisce un blocco della schermata ma l'attivatore nativo non scatta. Per superare questo limite senza dipendere solo dal trigger standard, si può inserire un tag di tipo HTML personalizzato che ascolti questo evento globale non gestito sul livello della finestra.

Crea un tag con codice personalizzato che contenga l'ascoltatore per l'evento unhandledrejection. All'interno di questo blocco, scrivi un'istruzione che effettui il push nel dataLayer di un evento su misura, con chiavi dedicate al motivo del rifiuto e al messaggio di errore. Imposta l'attivazione di questo tag su tutte le pagine all'avvio del caricamento. In questo modo si ottiene la copertura sia dei guasti sincroni sia di quelli asincroni tipici delle moderne piattaforme digitali.

Come analizzare i dati raccolti dentro le esplorazioni di GA4

Dopo aver accumulato almeno quarantotto ore di dati, entra nella sezione Esplora di Google Analytics 4 per costruire un prospetto utile per il team di sviluppo. Crea una nuova esplorazione a formato libero e carica le metriche e le dimensioni necessarie nella colonna delle variabili.

Trascina tra le dimensioni il Nome evento, la Pagina, il Messaggio Errore JS e l'URL Errore JS. Tra le metriche, importa il Conteggio eventi e gli Utenti totali. Applica un filtro sull'esplorazione per visualizzare esclusivamente le righe in cui il Nome evento corrisponde alla stringa javascript_error.

Ordina la tabella per Conteggio eventi decrescente. Questa vista mette in evidenza i bug più frequenti e mostra con precisione quanti visitatori unici subiscono ogni singolo malfunzionamento. L'incrocio di questi dati con il tasso di conversione o con il funnel di acquisto permette di quantificare l'impatto economico diretto di ciascun difetto software e stabilire le priorità di correzione con precisione millimetrica.

Gli errori frequenti e le strategie per evitare il limite di quote

La trappola principale di questa configurazione risiede nei loop infiniti di errore. Se uno script difettoso esegue una funzione ricorsiva o fallisce all'interno di un evento di scorrimento della pagina, il browser può generare centinaia di eccezioni al secondo per singolo visitatore.

Google Analytics 4 applica rigidi limiti sul volume di eventi inviabili per sessione e per singola proprietà. Se si consuma l'intera quota consentita a causa di un'ondata anomala di errori, la piattaforma smette di raccogliere tutti gli altri eventi analitici, compresi gli acquisti e le visualizzazioni di pagina, con un danno diretto per l'integrità dei report globali.

Per difendere l'infrastruttura da questa evenienza, si adotta una delle seguenti contromisure operative:

  • Limita l'invio degli eventi con una variabile JavaScript che conta le eccezioni per singola sessione e blocca l'attivatore quando si superano dieci segnalazioni identiche.
  • Configura un filtro nell'attivatore per ignorare errori generati da estensioni del browser o plugin installati dagli utenti sul proprio computer personale.

Riempire Analytics con dettagli tecnici prolissi come gli stack trace completi del codice risulta una pratica dispersiva. Questa procedura rischia di saturare la lunghezza massima consentita per i parametri evento sui siti ad alto traffico senza ricavare informazioni utili. Analytics deve servire da allarme strategico sul volume dei problemi, mentre la diagnosi chirurgica della singola riga di codice compete a piattaforme dedicate di monitoraggio degli errori.

Risposte alle domande più frequenti sul debug dei siti web

Molti professionisti si chiedono se il tracciamento dei bug rallenti il rendering delle pagine web. L'ascolto dell'evento di errore in Tag Manager non introduce alcun ritardo percepibile, poiché il sistema cattura l'eccezione solo nel momento in cui essa si manifesta, senza bloccare il flusso principale di visualizzazione.

Un altro dubbio comune riguarda la conformità al regolamento europeo sulla protezione dei dati. I messaggi tecnici del linguaggio di programmazione non contengono informazioni personali dei visitatori, a meno che il codice non incorpori variabili con nomi utente o indirizzi di posta direttamente nei testi di errore. Controlla preventivamente che gli script non contengano mai dati personali nei messaggi inviati alla console per evitare violazioni involontarie.

Se noti discrepanze tra il numero di guasti registrati su Analytics e quelli visualizzati nella console, controlla i filtri attivi nel trigger e le estensioni del browser.

Altri articoli in Guide