Meta Dataset Quality API: cos'è, cosa misura e perché dovresti conoscerla

C’è una battaglia che ormai credo di aver perso che però mi è molto cara: quella contro i punteggi di qualità di meta. Se hai attivato le Conversion API sul tuo account, probabilmente avrai già visto il punteggio accanto ai tuoi eventi su Events Manager.

Di che cosa rappresenta quel numero e come vada interpretato, ne ho parlato tantissime volte sia sui social che su Substack.

Scherzando (ma neanche tanto) io dico spesso che quei numerini lì sono fuorvianti e soprattutto creano più confusione che altro. Tuttavia, sono comunque l’unico indicatore della quantità delle informazioni utente che inviamo e della qualità di quest’ultime, di conseguenza dobbiamo comunque tenerli monitorati.

Effettuare un check sui punteggi di qualità di Meta non è complicato: basta entrare su events manager e dare una sbirciatina ai punteggi e alle informazioni all’interno dei singoli eventi (tabs Qualità degli eventi).

Ma cosa fai quando non devi controllare un solo account, ma dieci, venti o trenta dataset? E bada bene, che non si tratta di controllarli una volta ogni tanto ma almeno 1/2 volte alla settimana.

Quel cacchio di numero è comunque un indicatore della qualità del dato delle campagne ed un abbassamento improvviso può significare un problema nel tracciamento del tuo sito web. E tra l’altro, un problema silenzioso, poiché non si tratta di eventi che smettono di arrivare all’improvviso (di quelli ce ne accorgeremmo in AdsManager), ma di qualità del segnale che degrada nel tempo.

Meta Dataset Quality API ci viene incontro offrendoci la possibilità di automatizzare la lettura del dato in modo piuttosto granulare. E’ più di un anno che devo scrivere questo post, perché davvero, credo valga la pena conoscere questo strumento.

Se lo stai leggendo, sappi che sono davvero felice, perché nelle prossime righe, vedremo cosa fa, cosa misura e in che modo ha senso utilizzare Dataset Quality API di Meta.

Perché la qualità dei dati Meta conta (e non basta guardare l’EMQ)

Meta usa i dati che gli inviamo per fare tre cose fondamentalmente: matching (associare un evento a un utente reale), attribuzione (collegare quella conversione a un annuncio specifico), e ottimizzazione (far funzionare Advantage+, il bidding automatico, e tutto il resto della macchina algoritmica).

Se i dati che arrivano sono incompleti, formattati in modo erroneo o totalmente sbagliati, tutte e tre queste aree ne risentono.

Non è un concetto astratto: significa CPA più alti, fasi di apprendimento più lunghe, e l’algoritmo che prende decisioni con informazioni parziali.

L’EMQ è un indicatore utile per farci un idea della “qualità” dei nostri eventi. Tuttavia, un 8.2 su un evento Purchase ti dice che il matching è discreto, ma non ti dice quale parametro manca, quanto stai perdendo in termini di conversioni attribuite, o se c’è un problema tecnico nell’integrazione.

E’ per questo che all’interno del mio post su Substack, consigliavo di fare un controllo granulare di tutta l’infrastruttura.

Concentrarsi sul punteggio in sé ha poco senso - la cosa che conta davvero è guardare i dati che stai inviando, capire cosa manca, e lavorare su quello. Il punteggio segue come conseguenza naturale. E’ un indicatore utile, ma non è l’unico indicatore della qualità del dato da seguire.

Quello su cui dobbiamo concentrarci è la qualità e la quantità generale delle informazioni che inoltriamo alla piattaforma.

Se Meta riceve dati migliori per l’attribuzione, attribuisce meglio. E se attribuisce meglio, le campagne performano meglio. Di quanto esattamente? Non lo sappiamo con precisione. La stessa documentazione di Meta usa la parola “may” quando ne parla (“high quality event matching may improve ads attribution and performance”). Non abbiamo quindi alcuna garanzia, ma è logico che più dati e dati di maggiore qualità = performance migliori.

Detto questo, quando parliamo di qualità del dato non parliamo solo del punteggio parliamo di tutta una serie di fattori (deduplicazione, tempo di arrivo degli eventi ecc…) che dobbiamo tenere monitorati in modo costante.

Il problema grosso arriva quando devi fare tutto questo non per un account, ma per decine di account.

In Events Manager vedi le metriche di qualità per un dataset alla volta. Devi entrare, navigare, controllare, prendere nota, passare al prossimo. Per chi gestisce più clienti o più pixel - agenzie, consulenti, tech partner - è un lavoro che non scala. Ed è qui che entra in gioco Dataset Quality API.

Cos’è la Dataset Quality API

Per farla semplice, è l’endpoint di Meta che ci permette di accedere alle metriche di qualità dei dataset con una singola chiamata API. Tutto quello che vediamo sparso in Events Manager (e anche qualcosa in più) possiamo recuperarlo con una semplice GET, in formato strutturato, pronto per essere processato o messo in una dashboard.

Se il nome non ti suona familiare, è perché fino a poco tempo fa si chiamava Integration Quality API. Meta l’ha rinominata per allinearla al concetto di “Dataset” che ha sostituito il vecchio “Pixel” come unità organizzativa in Events Manager.

Il Dataset è il contenitore che aggrega tutto - dati web (pixel + Conversions API), offline, app, retail. La Dataset Quality API è lo strumento che ti dice come sta messo quel contenitore.

Per chi è pensata? Per tre tipi di persone, fondamentalmente: tech partner che integrano la Conversions API per i loro clienti, agenzie che gestiscono più account e vogliono una dashboard di qualità centralizzata, e advertiser con tanti pixel che vogliono automatizzare il monitoraggio.

Se hai un solo account con uno o due pixel, la verità è che Events Manager ti basta e avanza. L’API diventa utile quando la scala rende il controllo manuale impraticabile.

Veniamo a cosa restituisce. L’API copre sei aree di metriche (la maggior parte aggiunte con l’aggiornamento del 28 maggio 2025, che ha reso l’API molto più ricca di prima):

• EMQ (Event Match Quality) - quanto bene i dati utente che invii si associano a un account Meta

• ACR (Additional Conversions Reported) - quante conversioni in più stai misurando grazie alla Conversions API rispetto al solo pixel

• Event Coverage - che percentuale dei tuoi eventi pixel è coperta anche da eventi server

• Data Freshness - quanto velocemente arrivano i tuoi dati a Meta

• Diagnostica EMQ - problemi specifici dell’integrazione con soluzioni suggerite (esposta solo quando Meta rileva problemi critici)

• ACR potenziale per parametro - quanto guadagneresti in conversioni attribuite se iniziassi a inviare un certo dato (è esposto a livello di singola match key dentro l’EMQ, non come campo top-level)

Una nota onesta prima di andare avanti: la documentazione Meta cita anche un campo dedup_key_feedback per il feedback sulla deduplicazione browser/server. Al momento in cui scrivo, l’API lo rifiuta con errore “nonexisting field” su tutti i dataset che ho testato. È uno di quei casi in cui doc e implementazione vanno a velocità diverse - probabilmente è stato rinominato o temporaneamente disattivato. Ne riparlo nella sezione tutorial.

Questa lista è il motivo per cui dico che l’API è più ricca di quello che sembra. Non è solo “l’EMQ via API” - è un pacchetto di diagnostica completo che ti dice cosa funziona, cosa no, e dove hai margine di miglioramento.

Le metriche nel dettaglio - cosa guardare e perché

Sei metriche sono tante. Vediamo quali contano davvero e cosa ti dicono in pratica.

Metrica

Cosa misura

Soglia/goal

Perché conta

EMQ

Efficacia del matching eventi-utenti

6+ buono, 8+ eccellente

Matching migliore = attribuzione migliore

ACR

Conversioni aggiuntive via CAPI

Più alto è, meglio è

Ti dice il valore concreto della CAPI

Event Coverage

% eventi pixel coperti dal server

75%

Sotto questa soglia perdi dati

Data Freshness

Latenza di invio eventi

Real-time o hourly

Ritardi riducono l’efficacia

Diagnostica EMQ

Problemi tecnici + soluzioni

Nessun problema critico

Ti dice esattamente cosa fixare

EMQ è lo score composito da 0 a 10, con breakdown per match key (essenzialmente il punteggio di qualità). Tra i parametri che pesano di più nel calcolo ci sono email (hashata in SHA-256) e numero di telefono (formato E.164, hashato), con nome e cognome, indirizzo IP, user agent e i cookie fbp/fbc come complementari.

Meta non pubblica il peso esatto di ciascun parametro, ma nella response dell’API trovi il campo potential_aly_acr_increase che ti dice, a parità di tutto il resto, quanto guadagneresti in conversioni attribuite se migliorassi la copertura di quel singolo parametro - è il modo più onesto per capire dove conviene mettere le mani.

Una cosa che ho notato studiando i dati di Triple Whale: sopra 6-7 i rendimenti diventano decrescenti. Passare da un 4 a un 6 fa una differenza grossa, passare da un 7 a un 9 molto meno.

In pratica, non ha senso ossessionarsi per raggiungere il 10 - la cosa produttiva è assicurarsi di inviare i dati giusti nei formati corretti.

ACR (Additional Conversions Reported) è forse la metrica più concreta di tutte. Ti dice letteralmente quante conversioni in più stai misurando grazie alla Conversions API rispetto a quello che avresti misurato col solo pixel (è la metrica in verde che si vede in events manager aprendo il singolo evento).

L’API ti dà anche l’ACR potenziale per singolo parametro: in pratica ti mostra quanto guadagneresti se iniziassi a inviare un certo dato (come l’email) che al momento non stai inviando. Utile per convincere un cliente o per decidere dove investire tempo di sviluppo.

Event Coverage ha un goal chiaro: 75%. È la media su 7 giorni della percentuale di eventi pixel che sono coperti anche da eventi inviati via server.

Se sei a zero, la Conversions API non è configurata (o non funziona). Se sei sotto il 75%, stai lasciando una fetta significativa di dati non coperta dal tracking server-side.

Naturalmente questa ha senso solo se le CAPI sono attive, ma mi auguro che nel 2026 le CAPI siano attive nei tuoi tracciamenti. Se così non fosse, posso aiutarti, non ha senso avere un tracciamento di Meta senza CAPI ad oggi.

La diagnostica EMQ è per me la novità più utile dell’aggiornamento di maggio 2025. L’API non ti dice solo “hai un problema” - ti dice quale, su quanti eventi impatta, e come risolverlo. Un esempio reale dalla documentazione: “Server sending IPv4 addresses” con la soluzione “Configure web server for IPv6 support” e il dato che il 59.5% degli eventi ne era impattato. Questo tipo di informazione è oro per chi fa troubleshooting.

Infine, Data Freshness misura quanto velocemente i tuoi dati arrivano a Meta. La raccomandazione è “real time or as close to real time as possible”. Nella pratica, gli eventi inviati con più di un paio d’ore di ritardo perdono efficacia per l’attribuzione: se arrivano tardi, Meta non può usarli per ottimizzare le campagne in tempo reale.

Le metriche offline e l’omnichannel

Tutte le metriche di cui ho parlato finora riguardano gli eventi web. Tuttavia l’API ha anche una sezione dedicata agli eventi offline, accessibile usando il campo offline al posto di web nella stessa chiamata.

Le metriche offline funzionano in modo diverso. Invece dei singoli indicatori che vedi per il web, qui il dato principale è un composite score da 0 a 10, calcolato sugli ultimi 28 giorni. Tiene conto di tre fattori: la freshness (quanto sono recenti i dati che invii - idealmente entro poche ore dall’evento), la frequenza (quanto spesso fai upload - invii giornalieri sono meglio di batch settimanali), e la ricchezza di identificatori (quanti dei tuoi eventi offline contengono email o telefono per il matching). Ognuno di questi fattori ha il suo sotto-punteggio da 0 a 10, ma è il composite che decide cosa puoi fare.

Il numero che conta davvero è 8.5. Un composite score di almeno 8.5 è il requisito per abilitare le inserzioni omnicanale, cioè le campagne Web + Store purchase optimization che collegano acquisti online e in negozio nella stessa ottimizzazione. In pratica, sotto 8.5 non puoi dire a Meta “ottimizza considerando sia le vendite online che quelle in negozio”. Se vendi in entrambi i canali, questa soglia è il gate di ingresso.

Una nota: al momento la sezione offline dell’API è ancora in beta. Funziona già, ma Meta non la considera stabile. Se lavori con dati offline, tienilo presente.

Autenticazione - chi sei, quale strada prendi

Quando ho iniziato a leggere la documentazione sulla parte di autenticazione, ho avuto la sensazione che Meta stesse cercando di parlare a due pubblici molto diversi nello stesso documento, e che questo confondesse la maggior parte di chi prova ad utilizzare l’API o vorrebbe utilizzarla.

Da un lato c’è l’advertiser singolo che vuole vedere come stanno andando i dati del suo pixel.

Dall’altro c’è il tech partner che deve accedere a centinaia di dataset di clienti diversi senza passare manualmente da ognuno. I requisiti, ovviamente, sono molto diversi.

I metodi disponibili sono tre, e vanno scelti in base a come accedi ai dataset. Vediamoli uno per uno.

1. Token da Events Manager. È il metodo più semplice e copre la maggior parte dei casi reali. Vai su Events Manager, selezioni il dataset, apri Settings, scendi alla sezione Conversions API e clicchi “Generate access token”. Da metà 2025, durante questo flusso compare un’opzione esplicita per abilitare i permessi della Dataset Quality API: se la spunti, il token che esce è già pronto sia per inviare eventi che per leggere le metriche di qualità.

Questo metodo funziona in due scenari:

• Dataset di proprietà diretta - il pixel è stato creato nel tuo Business Manager. Caso tipico dell’advertiser che monitora i propri pixel.

• Dataset condiviso via Pixel Sharing - il cliente ha condiviso il pixel al tuo Business Manager dalle impostazioni e tu generi il token da lì. Caso tipico dell’agenzia che riceve l’accesso al pixel del cliente per impostare il tracking. Qui potrebbe sembrare uno step extra, ma in realtà la generazione del token è lo stesso passaggio che serve già per configurare il Server Side: quindi non è un dramma, è un’operazione che quasi sicuramente stai già facendo.

Niente app registrata, niente review, niente system user. È anche il metodo che useremo nel tutorial qui sotto. Il limite è che non scala quando hai decine o centinaia di dataset: ogni pixel richiede un passaggio manuale in Events Manager.

2. Facebook Login for Business. È il metodo raccomandato per i tech partner che hanno un’app registrata su Meta e vogliono accedere ai dataset dei clienti in modo strutturato. Funziona come un OAuth: definisci nella configurazione dell’app quali permessi ti servono, il cliente clicca su un link, autorizza la tua app, e tu ricevi un token che puoi usare per accedere ai suoi dataset senza che lui debba generare nulla manualmente. Più complesso da impostare, ma scala bene quando hai centinaia di clienti e non puoi fare il giro a mano.

3. Meta Business Extension (beta). Una versione semplificata del metodo precedente, ancora in beta. Restituisce in automatico tutte le informazioni necessarie per inviare eventi e leggere la qualità per conto del cliente, gestendo da sé la creazione del system user e dei permessi sul Business Manager del cliente. Più rapido da integrare di Facebook Login for Business, ma con i limiti del beta - non lo userei per qualcosa di mission-critical finché non esce dalla fase beta.

In sintesi, quale metodo scegliere a seconda di chi sei:

Profilo

Metodo consigliato

Note

Pixel di proprietà (pochi)

Token Events Manager

Caso più semplice, no review

Agenzia con Pixel Sharing dal cliente

Token Events Manager

Stesso flusso, dataset condiviso. Token gia necessario per il Server Side

Tech partner con app pubblicata

Facebook Login for Business

Scala su centinaia/migliaia di dataset

Tech partner che vuole onboarding rapido

Meta Business Extension (beta)

Più semplice ma ancora beta

Sui permessi a livello app, il minimo richiesto è ads_read più uno tra ads_management e business_management. Per chi gestisce volumi alti come tech partner, serve il livello Advanced di ads_management con la funzione “Ads Management Standard Access”, che richiede una app review da parte di Meta.

A livello utente, chi genera o usa il token deve avere almeno il permesso “Use Event Dataset” sul dataset in questione. Si imposta in Business Manager nelle impostazioni del dataset.

Non serve essere amministratore del Business Manager: il permesso “Use Event Dataset” è un accesso parziale che si può assegnare a qualsiasi utente collaborator del dataset, anche senza ruoli admin. Se sei stato aggiunto come “editor” o “analyst” sul pixel, tipicamente ce l’hai già.

Una cosa che vale la pena sapere: se hai generato un token CAPI in Events Manager prima di luglio 2025, quel token non ha automaticamente i permessi per la Dataset Quality API. Per attivarli devi entrare in Events Manager e completare un opt-in: una volta fatto, sia il token vecchio sia tutti quelli generati in seguito dallo stesso utente possono accedere all’API. È un dettaglio piccolo ma ci cascano in tanti, perché molti pixel in produzione oggi girano con token più vecchi di quella data.

Tutorial: chiamare la Dataset Quality API per un singolo pixel

Ok, entriamo ora nel vivo con un test pratico dell’API. Vediamo passo dopo passo come impostare una chiamata ed esaminiamo il risultato dell’API.

Ho eseguito alcune chiamate di prova su di un Dataset e-commerce con un bel pò di eventi cui avevo accesso. Come vedremo, l’API ha identificato alcune ottimizzazioni necessarie per alcuni degli eventi.

Tra l’altro, nel mio esperimento, rispetto al dato da documentazione, ho visto delle divergenze. Ne parliamo tra poco, magari potrebbe essere un caso limite del mio test, ma non credo; probabilmente alcune delle informazioni della documentazione non sono state aggiornate.

PS: lascio tutti gli step che ho eseguito tipo tutorial, in questo modo, dovresti anche tu riuscire a replicarli seguendoli passo passo.

Prerequisiti

Tre cose che devi avere prima di partire:

• Accesso al Business Manager che possiede il pixel

• Permessi “Use Event Dataset” sul dataset che vuoi interrogare (lo verifichi nel pannello del dataset, sezione assegnazioni)

• Uno strumento per fare richieste HTTP: curl da terminale, Postman, oppure direttamente il Graph API Explorer di Meta che puoi usare nel browser senza installare nulla (puoi farti aiutare da un LLM ad impostare la chiamata tranquillamente)

Step 1 - Generare il token

Vai su business.facebook.com/events_manager, seleziona il dataset, apri il tab “Settings”. Scorri fino alla sezione “Conversions API” e clicca su “Generate access token”.

Da metà 2025, durante questo flusso compare un’opzione esplicita “Set up with Dataset Quality API” (la dicitura esatta può cambiare a ogni revisione dell’interfaccia, ma il concetto è quello). Spuntala.

Copia il token che esce e mettilo in un posto sicuro. È una credenziale, trattalo come tale: niente Slack, niente file in chiaro nel repo, niente screenshot pubblicabili.

Step 2 - Recuperare l’id del tuo Dataset

Lo trovi nello stesso pannello di Events Manager: in alto, accanto al nome del dataset, c’è il suo ID. Oppure se il Dataset è pubblico sul sito web, recuperalo da Events Manager. Recuperare l’ID del pixel non dovrebbe essere complicato, ma eventualmente, scrivimi che ti do una mano.

Step 3 - Prima chiamata minimale per testare il token

Prima di chiedere tutte e sette le metriche, ha senso fare una chiamata leggera per verificare che il token funzioni e che abbia i permessi giusti. Chiediamo solo l’EMQ:

curl -X GET -G \
  -d "fields=web{event_match_quality,event_name}" \
  -d "dataset_id=$META_DATASET_ID" \
  -d "access_token=$META_TOKEN" \
  https://graph.facebook.com/v25.0/dataset_quality

Se tutto funziona, la response è un JSON con un array web che contiene un oggetto per ogni evento del dataset. Per ognuno trovi il composite_score e il dettaglio per match key. Questa è una response reale (anonimizzata) estratta dal dataset di test, per l’evento Purchase:

{
  "web": [
    {
      "event_name": "Purchase",
      "event_match_quality": {
        "composite_score": 7,
        "match_key_feedback": [
          {
            "identifier": "email",
            "coverage": { "percentage": 33.3 },
            "potential_aly_acr_increase": { "percentage": 34.14 }
          },
          {
            "identifier": "phone",
            "coverage": { "percentage": 14.3 },
            "potential_aly_acr_increase": { "percentage": 15.1 }
          },
          {
            "identifier": "ip_address",
            "coverage": { "percentage": 100 },
            "potential_aly_acr_increase": { "percentage": 0.34 }
          },
          {
            "identifier": "user_agent",
            "coverage": { "percentage": 100 },
            "potential_aly_acr_increase": { "percentage": 0.34 }
          },
          {
            "identifier": "fbp",
            "coverage": { "percentage": 100 },
            "potential_aly_acr_increase": { "percentage": 4.02 }
          },
          {
            "identifier": "fbc",
            "coverage": { "percentage": 33.3 },
            "potential_aly_acr_increase": { "percentage": 200 }
          },
          { "identifier": "fn", "coverage": { "percentage": 31 } },
          { "identifier": "ln", "coverage": { "percentage": 16.7 } },
          { "identifier": "ct", "coverage": { "percentage": 23.8 } },
          { "identifier": "st", "coverage": { "percentage": 14.3 } },
          { "identifier": "zip", "coverage": { "percentage": 40.5 } },
          { "identifier": "country", "coverage": { "percentage": 14.3 } }
        ]
      }
    }
  ]
}

Già da questa singola chiamata minimale emergono informazioni dense. Il composite_score di 7 è il punteggio che vedresti in Events Manager. Ma il valore vero sta nell’array match_key_feedback: ti dice, per ogni identificatore, quale percentuale di eventi lo contiene e (dove disponibile) quanto guadagneresti in termini di attribuzione se lo portassi al 100%.

Su questo Purchase reale: l’email arriva solo al 33.3% degli eventi, con potenziale di +34% di conversioni attribuite se fosse al 100%. fbc al 33.3% ha un potenziale del +200% - un classico sintomo di click ID fbclid che si perdono lungo il funnel (redirect, cross-domain, SPA routing).

Nota: FBCLID al 100% è poco sensato concettualmente. Non tutto il traffico del tuo sito web è infatti traffico da campagna.

Se invece ricevi un errore tipo (#10) Application does not have permission for this action oppure (#200) Permissions error, significa che il token non ha i permessi per la Dataset Quality API.

Vai su Events Manager e completa l’opt-in di cui parlavo allo Step 1. Se ricevi (#190) Invalid OAuth access token, il token è scaduto o è stato invalidato (l’utente che lo ha generato ha perso accesso al BM): ne devi rigenerare uno nuovo.

Se invece ricevi (#100) Missing Permission o (#1) An unknown error occurred su una chiamata base, nove volte su dieci è il token che non è autorizzato su quel dataset specifico: puoi verificarlo con una chiamata al debug_token endpoint per vedere i granular_scopes.target_ids associati al tuo token.

Se l’ID del dataset che stai interrogando non è in quella lista, Meta risponde con un errore generico che non ti dice chiaramente cosa c’è che non va.

Step 4 - Chiamata completa con tutte le metriche

Una volta confermato che la base funziona, puoi chiedere il pacchetto completo:

curl -X GET -G \
  -d "fields=web{event_name,event_match_quality,acr,event_coverage,data_freshness}" \
  -d "dataset_id=$META_DATASET_ID" \
  -d "access_token=$META_TOKEN" \
  https://graph.facebook.com/v25.0/dataset_quality

I cinque campi che ho messo in fields corrispondono alle metriche descritte nella sezione “Le metriche nel dettaglio”. L’ordine non conta.

Una nota importante che ho scoperto testando live l’API: la documentazione ufficiale di Meta elenca tra i campi disponibili anche dedup_key_feedback, che dovrebbe dare un feedback sulla qualità della deduplicazione browser/server.

Alla data in cui scrivo questo post, l’API lo rifiuta con errore (#100) Tried accessing nonexisting field (dedup_key_feedback) su tutti i dataset che ho testato (inclusi dataset pieni di traffico e-commerce con deduplicazione attiva).

Ho provato anche varianti del nome (dedup_feedback, deduplication_feedback, event_deduplication) e sono tutte rifiutate nello stesso modo. Probabilmente è stato rinominato, rimosso, o spostato dietro una feature flag.

Per ora: non mettere dedup_key_feedback nel tuo array fields, altrimenti l’intera chiamata torna errore. Se in futuro Meta allinea doc e API, aggiornerò questo post.

Un discorso simile vale per la diagnostica EMQ dettagliata: la doc la chiama diagnostics come sotto-oggetto di event_match_quality, ma nel dataset di test che ho usato non è mai tornata popolata.

Probabilmente appare solo quando Meta ha effettivamente rilevato un problema critico sull’integrazione (tipo IPv4 only, hashing sbagliato, formato telefono non E.164). Se la tua implementazione è pulita, non la vedrai - ed è una buona notizia.

Step 5 - Leggere la response

La struttura del JSON che torna è abbastanza leggibile. Sotto web trovi un array, con un elemento per ogni evento standard o custom del dataset. Per ogni elemento trovi (i nomi dei campi sono quelli effettivi che l’API restituisce, non quelli che trovi a volte in giro nella doc):

• event_name: il nome dell’evento (Purchase, ViewContent, AddToCart, Lead, PageView, ecc.)

• event_match_quality: oggetto con composite_score (numero 0-10) e match_key_feedback (array di oggetti, uno per identifier - vedi sotto)

• acr: oggetto con un solo campo, percentage. È la percentuale di conversioni in più misurate via CAPI rispetto al solo pixel. Nota: non tutti gli eventi hanno acr nella response - compare solo sugli eventi che hanno effettivamente una Conversions API attiva. Se un evento è solo pixel, il campo acr non torna proprio, non è zero.

• event_coverage: oggetto con un solo campo, percentage. La soglia 75% è una soglia documentata, non un campo nella response: il confronto lo devi fare tu lato codice.

• data_freshness: oggetto con upload_frequency. Nei test ho visto tornare hourly come valore. La doc menziona anche real_time ma non l’ho intercettato direttamente nei dataset provati.

Ogni elemento di match_key_feedback ha questa struttura:

{
  "identifier": "email",
  "coverage": { "percentage": 33.3 },
  "potential_aly_acr_increase": { "percentage": 34.14 }
}

Gli identifier che ho visto tornare nella response reale sono 12: email, phone, ip_address, user_agent, fbp, fbc, fn (first name), ln (last name), ct (city), st (state), zip, country. Il campo potential_aly_acr_increase non c’è su tutti - Meta lo popola solo per i parametri dove ha abbastanza segnale per stimare il delta. Tipicamente su fn, ln, ct, st, zip, country non te lo dà.

Se un evento ha pochi dati, alcuni campi possono mancare o tornare vuoti. Non è un errore, è Meta che ti sta dicendo “su questo evento non ho abbastanza segnale”. Eventi come PageView puri o custom event non e-commerce (tipo ScrollTracking, SubscribedButtonClick) spesso tornano con il solo event_name e nient’altro. Se fai parsing automatico, gestisci l’assenza dei campi invece di dare per scontato che ci siano.

Come leggere una response reale - un caso pratico

Vedere la struttura è una cosa. Imparare a leggerla è un’altra. Prendo i dati che sono usciti dalla chiamata sul dataset di test e ci costruisco sopra una panoramica operativa. Questi numeri sono reali (solo il dataset è anonimizzato):

Evento

EMQ

Event Coverage

ACR

Freshness

Lead

8.2

95.0%

100%

hourly

Purchase

7.0

76.5%

66.7%

hourly

AddPaymentInfo

7.0

71.4%

40%

hourly

InitiateCheckout

7.0

76.4%

30%

hourly

AddToCart

6.8

87.7%

30%

hourly

ViewContent

6.4

88.5%

34.4%

hourly

PageView

6.5

92.5%

62.2%

hourly

Tre letture operative che questa singola tabella ti permette di fare.

Lead con ACR al 100% è un campanello. Significa che tutti i Lead di questo dataset arrivano esclusivamente via Conversions API, non ce n’è nemmeno uno tracciato dal pixel browser.

Può essere una scelta deliberata (Lead calcolato lato server da un CRM, da un Typeform webhook o da una logica custom), oppure un gap di tracking nel form browser-side.

Purchase con ACR 66.7% è una miniera d’oro argomentativa. Vuol dire che la Conversions API sta recuperando circa due terzi di conversioni in più rispetto al solo pixel.

In termini grezzi: se domani disattivassi la CAPI su questo account, Meta attribuirebbe circa il 40% dei Purchase in meno. È il tipo di numero che mostri a un cliente che chiede perché sta pagando per la server-side. Non è un “trust me bro”, è un valore letto direttamente dall’API di Meta sul suo dataset.

Event Coverage su Purchase al 76.5% vs AddToCart all’87.7%. Entrambi sono sopra la soglia del 75%, quindi formalmente “ok”. Ma il gap tra i due è interessante: significa che il Purchase server-side ha ancora eventi pixel senza controparte CAPI, e il gap è più marcato proprio sull’evento che pesa di più economicamente. È un pattern classico di implementazione affrettata, dove il browser-side copre tutto il funnel ma il server-side si ferma a monte. Su un setup maturo, ti aspetteresti Purchase con coverage allineato o superiore ad AddToCart (il Purchase è più semplice da tracciare server-side perché lo scateni da un webhook o da un ordine già salvato).

Ora scendiamo dentro il campo match_key_feedback dell’evento Purchase. Questo è il dettaglio per singolo parametro (solo quelli con potential_aly_acr_increase popolato):

Parametro

Coverage attuale

ACR potenziale se migliorato

email

33.3%

+34.14%

phone

14.3%

+15.1%

ip_address

100%

+0.34%

user_agent

100%

+0.34%

fbp

100%

+4.02%

fbc

33.3%

+200%

Qui la lettura diventa molto più specifica. ip_address, user_agent e fbp sono già al 100% di copertura, quindi non c’è niente da fare: li stai già inviando su tutti gli eventi. Email e phone sono invece a un terzo e a un settimo della copertura possibile, con potenziali di +34% e +15% - portare l’email dal 33% al 100% potrebbe aumentare l’ACR di un ulteriore terzo.

Questo è l’argomento operativo più forte per lavorare sulla raccolta email in checkout.

Ma il vero colpo d’occhio è fbc al 33% con potenziale +200%. fbc contiene il fbclid che Meta assegna ai click provenienti dai propri annunci, ed è l’identificatore più potente per legare un evento a una campagna specifica.

Se una conversione non ha fbc, Meta non riesce ad attribuirla al click originale.

Un potenziale del +200% non vuol dire letteralmente che raddoppieresti le conversioni, ma che un volume enorme di click sta passando senza essere riconosciuto.

I sospetti tipici in questo scenario: redirect intermedi che droppano i query parameter, landing page su domini diversi senza cross-domain tracking configurato, app mobile che perde i deep link parameter, oppure SPA routing che riscrive l’URL prima che il pixel legga fbclid.

C’è anche da dire che potrebbe trattarsi di un sito web con elevato traffico da Google ADS o traffico organico e che di conseguenza il traffico Meta a pagamento rappresenta proprio quella percentuale.

Nota: questa info la vedi anche entrando sul singolo evento su Events Manager, ma farlo su diversi Pixel è scomodo e inoltre, grazie all’API possiamo orchestrare sistemi automatici di controllo.

Step 6 - Chiamare le metriche offline (opzionale)

Se gestisci anche dati offline (acquisti in negozio, CRM uploads, retail), puoi interrogare la sezione offline cambiando web con offline nel parametro fields:

curl -X GET -G \
  -d "fields=offline{event_name,composite,match_key,frequency,freshness}" \
  -d "dataset_id=$META_DATASET_ID" \
  -d "access_token=$META_TOKEN" \
  https://graph.facebook.com/v25.0/dataset_quality

Secondo la documentazione, ogni evento offline nella response ha quattro sotto-oggetti: composite, match_key, frequency, freshness. Ognuno espone score (0-10) e recommendation (stringa testuale); match_key ha anche coverage con il dettaglio per email e phone. Ricorda due cose: la sezione offline è ancora in beta, e il composite score 8.5 è la soglia per abilitare le inserzioni omnicanale Web + Store purchase optimization. Se sei sotto, sai dove devi arrivare.

Piccolo disclaimer: non ho testato la sezione offline sul dataset usato per la parte web, perché non aveva eventi offline associati. I nomi dei campi sopra vengono dalla doc ufficiale Meta, non da una mia verifica diretta.

Note di sicurezza e gestione token

Tre cose da non dimenticare prima di mettere in produzione una pipeline di monitoraggio:

Validità del token. I token generati via Events Manager per la Conversions API non scadono automaticamente per default: la chiamata a debug_token su un token appena generato restituisce expires_at: 0, cioè non ha scadenza. Vengono però invalidati se l’utente (o il system user) a cui sono associati perde l’accesso al Business Manager o al dataset, oppure se vengono revocati esplicitamente. Se il monitoraggio si rompe da un giorno all’altro senza apparente motivo, controlla per primo questo con debug_token.

Revoca. Non c’è una lista gestibile di token in Events Manager, né un pulsante “elimina questo token” singolarmente. La revoca avviene a monte, dal Business Manager: vai su Utenti di sistema, seleziona il system user associato alla Conversions API (tipicamente chiamato “Conversions API System User”) e usa il pulsante Revoca token che trovi in alto a destra, accanto a “Genera token”.

L’azione è immediata e revoca tutti i token di quel system user in un colpo solo, non uno per uno.

Dopo la revoca, i token smettono di funzionare subito e per tornare operativo devi rigenerarne uno nuovo da Events Manager o direttamente da qui con “Genera token”. Generare un nuovo token, da solo, non invalida i vecchi: la generazione e la revoca sono due azioni separate. Se sospetti che un token sia finito in un posto sbagliato (commit pubblico, log, screenshot), l’unica strada sicura è revocare tutti i token del system user e rigenerare quelli che servono.

Nello stesso pannello vedi anche le Risorse assegnate al system user, divise in tre blocchi: App (la Conversions API Application con i suoi permessi), Pixel (con accesso parziale “Visualizzare pixel”) e Dataset (con accesso parziale “Usa dataset degli eventi”).

Quest’ultimo è proprio il permesso utente di cui parlavo nella sezione autenticazione: è la granularità minima che serve per chiamare la Dataset Quality API, ed è già presente di default sui system user creati dal flusso automatico di Events Manager.

Rate limit. L’API è soggetta ai rate limit standard del Marketing API. Per il monitoraggio di pochi pixel non li toccherai mai, ma se cicli su decine o centinaia di dataset ha senso aggiungere un piccolo delay tra le chiamate per evitare di prenderti un 429.

A chi serve davvero la Dataset Quality API

A questo punto hai una visione abbastanza completa di cosa fa questa API e cosa restituisce. La domanda pratica è: ti serve?

La risposta breve: la Dataset Quality API ha senso se gestisci più di una manciata di dataset e vuoi automatizzare il monitoraggio della qualità.

Se sei un’agenzia con dieci o più clienti, un tech partner che integra la Conversions API, o un advertiser enterprise con tanti pixel - è lo strumento che ti permette di passare dal “guardo l’EMQ ogni tanto nell’Events Manager” al “monitoro la qualità dei dati in modo strutturato e programmatico”.

Se invece hai un account con un pixel e lo controlli a mano ogni tanto, Events Manager fa il suo lavoro e questa API non ti cambia la vita.

Le chiamate, le response e gli insight che hai letto qui sopra non sono ipotetici: li ho fatti girare su un dataset Shopify con traffico e-commerce reale mentre scrivevo il post, e dove doc e API divergono l’ho detto in modo esplicito.

Il prossimo step naturale, su cui sto lavorando, è uno script che gira la chiamata su più dataset in batch, li salva in un Google Sheet o in un DB, e ti notifica quando una metrica scende sotto soglia - il passaggio da “controllo una tantum” a “monitoraggio continuo”.

Ne parlerò in un post dedicato appena è pronto.

Se ti interessa il tema della qualità dei dati nel tracking, ho scritto anche un post su Google Tag Gateway - un altro pezzo del puzzle, lato Google.