Debug del Measurement Protocol GA4: perché il 2xx non dimostra nulla

Il Measurement Protocol GA4 restituisce uno stato 2xx per quasi tutto ciò che gli invii: un evento valido, un evento con un errore di ortografia, un evento senza client_id, un segreto inventato. Il codice di stato è quindi inutile per il debug. Per eseguire il debug delle chiamate al Measurement Protocol GA4, invia lo stesso corpo al server di convalida in /debug/mp/collect, leggi le validationMessages restituite, correggi ciò che indicano e solo allora conferma l'arrivo in DebugView o Realtime.

Quest'ultimo passaggio conta più di quanto ci si aspetti. Perché? Il server di convalida non controlla il segreto API, quindi un payload può superare la convalida, ricevere un 204 dall'endpoint reale e non arrivare mai nella tua proprietà. Ho visto un team perdere una settimana proprio per questo, prima che qualcuno pensasse di ricopiare il segreto.

Se stai collegando eventi lato server per monitorare le campagne, la guida fondamentale sul monitoraggio degli UTM dall'inizio alla fine spiega cosa dovrebbe essere presente nel link prima di tutto questo. Questo articolo riguarda il momento in cui invii l'evento e non compare nulla.

Perché il Measurement Protocol risponde 2xx a tutto

Il riferimento del protocollo di Google è esplicito: l'endpoint restituisce un codice di stato 2xx se riceve la richiesta HTTP e non restituisce un errore se il payload è malformato o i dati non vengono elaborati. La raccolta è fire-and-forget. Il tuo server non attende l'elaborazione.

Lo abbiamo verificato personalmente. Un POST a /mp/collect con il corpo {"garbage":true}, un ID di misurazione fittizio e un segreto inventato ha restituito HTTP 204 con un corpo vuoto. Esattamente come un evento perfetto.

La logica di ritentativo basata sui codici di stato rileva i problemi di rete. Nient'altro. Non può dirti che GA4 ha scartato i tuoi eventi. Per questo serve il secondo endpoint.

Come usare il server di convalida in /debug/mp/collect

Il server di convalida del Measurement Protocol si trova sullo stesso host. Stessa stringa di query, stesso corpo:

curl -s -X POST \
  "https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"name":"session_start","params":{"firebase_x":1}}]}'

Risponde con 200 e un corpo JSON anziché con uno vuoto. Quel payload di prova presenta tre problemi e il server riporta il primo che incontra:

{
  "validationMessages": [
    {
      "fieldPath": "client_id",
      "description": "Measurement requires a client_id.",
      "validationCode": "VALUE_REQUIRED"
    }
  ]
}

Aggiungi un client_id e passa a NAME_RESERVED per session_start; rinomina l'evento e il prefisso firebase_ è il successivo. Ogni messaggio contiene un fieldPath, una descrizione leggibile e un codice. I codici documentati da Google includono VALUE_INVALID, VALUE_REQUIRED, NAME_INVALID, NAME_RESERVED, VALUE_OUT_OF_BOUNDS, EXCEEDED_MAX_ENTITIES e NAME_DUPLICATED.

Un array vuoto, "validationMessages": [ ], significa che la struttura è corretta. Nulla di ciò che invii a /debug/mp/collect viene memorizzato. Usalo pure intensamente durante lo sviluppo; ricorda solo che una chiamata di debug non prova mai l'arrivo dei dati.

Cosa non controlla il server di convalida

La maggior parte dei tutorial salta questa parte. La pagina di Google sulla convalida degli eventi afferma chiaramente che il server di convalida non convalida api_secret. Nel nostro test del 22 settembre 2026 non ha controllato neppure l'ID di misurazione: G-FAKE123 con il segreto nonsense ha restituito un array validationMessages vuoto.

Un segreto errato passa. Lo stesso vale per uno revocato, per uno di un altro flusso di dati o per un errore di battitura in G-. L'api_secret del Measurement Protocol è il motivo più comune che vedo per "payload valido, nessun dato", e puoi confermarlo solo vedendo arrivare un evento.

La seconda lacuna è la modalità di convalida. Per impostazione predefinita, il server funziona in modalità RELAXED e in tale modalità ha lasciato passare due elementi vietati dai limiti di Google: un evento con 26 parametri e un valore di parametro di 120 caratteri. Aggiungi "validation_behavior": "ENFORCE_RECOMMENDATIONS" al corpo di debug ed entrambi falliscono, con EXCEEDED_MAX_ENTITIES e VALUE_TOO_LONG. Convaliderei sempre in modalità rigorosa, anche se la produzione resta rilassata. È la differenza tra un controllore e un timbro automatico.

Visualizzare gli eventi server in DebugView e Realtime di GA4

Una volta convalidato il payload, invialo all'endpoint reale e osservane l'arrivo. Due viste funzionano per gli eventi lato server, e i report standard non sono tra queste, poiché possono ritardare da 24 a 48 ore.

DebugView richiede un'attivazione esplicita per ogni evento. La guida di verifica di Google richiede "debug_mode": 1 (oppure true) nei parametri dell'evento, oltre a un engagement_time_msec positivo. Compaiono solo gli eventi che hanno il flag, quindi un batch in cui un evento ne è privo sembra mezzo vuoto. Apri Admin, quindi DebugView, e attendi un minuto.

Realtime non richiede altro. Scorri fino alla scheda "Conteggio eventi per nome dell'evento" e cerca il tuo evento. Google segnala che session_id e engagement_time_msec sono importanti affinché l'attività utente compaia in Realtime, quindi se un evento si convalida ma Realtime resta vuoto, controlla prima questi due valori.

Un'altra avvertenza della stessa guida: per i flussi web, un evento valido usa un client_id che gtag.js ha già usato. Gli ID sintetici vengono comunque conteggiati, ciascuno come utente separato, ma non si uniscono mai a una sessione del browser; in un report basato sulle sessioni, il risultato è una lunga coda di utenti con un solo evento che non riesci a spiegare finché non ne conosci l'origine. Ne parliamo meglio nella sezione successiva. Se mancano dati della campagna anziché eventi, i parametri UTM non visualizzati in GA4 illustra il lato DebugView del problema.

Errori comuni nel payload e risposte del validatore

La maggior parte degli eventi non validi rientra in pochi schemi. Ecco quali sono, insieme a ciò che il server di convalida ha restituito quando li abbiamo inviati il 22 settembre 2026:

Due righe meritano un commento. Il prefisso ga_ è riservato secondo il riferimento, eppure il validatore ha accettato ga_session_id in entrambe le modalità durante i nostri test, quindi non considerare un array vuoto come un'autorizzazione. Inoltre, il limite di 100 caratteri per i valori intercetta di continuo gli URL di destinazione completi: una pagina di atterraggio con cinque tag UTM è spesso più lunga.

Il caso del client_id è il più sottile. Qualsiasi stringa supera la convalida rilassata, ma la modalità rigorosa ha rifiutato sia c1 sia elido-12-4711 con "It should be in . format". Se gli eventi devono collegarsi alle sessioni del browser, invia il vero valore _ga; la guida al monitoraggio lato server con GA4 spiega nel dettaglio questo collegamento.

Come Elido usa l'inoltro GA4 e il test della connessione

Elido inoltra i clic sui link brevi a GA4 lato server. Incolli un Measurement ID e un segreto API del Measurement Protocol nella scheda GA4 delle integrazioni, e da quel momento ogni clic in quello spazio di lavoro diventa un evento link_click:

{
  "client_id": "elido-12-4711",
  "events": [
    {
      "name": "link_click",
      "params": {
        "workspace_id": 12,
        "link_id": 4711,
        "slug": "spring-26",
        "country": "DE",
        "device": "mobile",
        "destination": "https://shop.example/spring?utm_source=newsletter",
        "engagement_time_msec": 100
      }
    }
  ]
}

Il client_id è elido-<workspace>-<link>, quindi ogni clic su un link viene interpretato come lo stesso utente GA4 e nessuno si unisce a una sessione del browser. È il compromesso trasparente di farlo senza cookie: i totali e le suddivisioni per slug, paese e dispositivo funzionano; i conteggi utenti e i funnel di sessione no. Paese e dispositivo sono semplici parametri evento. Registrali prima come dimensioni personalizzate. Inoltre, una destination oltre 100 caratteri incontra il limite della tabella precedente, quindi crea report su slug o link_id.

Il pulsante per testare la connessione segue l'ordine consigliato da questo articolo:

Prima invia un link_click sintetico, contrassegnato con elido_test: true, a /debug/mp/collect. Se validationMessages non è vuoto, il test fallisce e mostra testualmente le descrizioni di Google. Se l'array è vuoto, lo stesso evento viene inviato realmente a /mp/collect. Sotto il pulsante vedi la risposta del fornitore (stato HTTP, endpoint di debug con il tuo ID di misurazione ma mai il segreto, e corpo di Google), più una nota che indica che il Measurement Protocol non verifica il segreto API.

Quindi il verde significa "valido e ricevuto da Google". Non "presente nella tua proprietà". L'evento di test contiene debug_mode: 1 e elido_test: true, quindi compare in DebugView come link_click; anche Realtime funziona. Se desideri eventi di clic in GA4 senza un tag su ogni pagina di atterraggio, avvia uno spazio di lavoro e indica prima nella scheda GA4 una proprietà di test.

Un ordine efficace per il debug del Measurement Protocol GA4

Quando gli eventi GA4 non compaiono, segui questo ordine e fermati al primo errore:

1. Invia il corpo a /debug/mp/collect con validation_behavior impostato su ENFORCE_RECOMMENDATIONS. Correggi ogni messaggio.
2. Copia di nuovo il segreto API da Amministrazione, Flussi di dati, il tuo flusso web, segreti API del Measurement Protocol. Verifica che provenga dallo stesso flusso dell'ID G-.
3. Invia un evento a /mp/collect con debug_mode: 1 e osserva DebugView per due minuti.
4. Rimuovi il flag e controlla Realtime, quindi concedi ai report standard uno o due giorni.

Il passaggio 2 è quello in cui termina la maggior parte dei miei debug. La pagina di risoluzione dei problemi di Google si apre con le stesse tre domande: segreto corretto, ancora valido, copiato esattamente. Quando i numeri finalmente arrivano ma non corrispondono ancora ai conteggi dei tuoi link, clic sui link brevi rispetto alle sessioni GA4 spiega la differenza, mentre monitoraggio delle conversioni lato server tratta gli eventi di conversione che di solito seguono. La stessa abitudine di convalidare e poi verificare si applica alle altre destinazioni nella pagina monitoraggio delle conversioni.

Correlati nel blog

• Monitoraggio lato server GA4 tramite reindirizzamenti - credenziali, struttura del payload e collegamento tramite client_id.
• Mixpanel o GA4 per l'analisi dei link - quale strumento dovrebbe contenere i dati sui clic.
• Monitoraggio dei link Mixpanel - lo stesso inoltro diretto a Mixpanel, con la sua peculiarità del 200 per qualsiasi cosa.
• Parametri UTM non visualizzati in GA4 - la versione del problema di debug relativa ai dati delle campagne.
• Monitoraggio delle conversioni lato server - GA4, Meta CAPI e TikTok affiancati.