Servono sia il pixel Meta sia la Conversions API?

Meta consiglia di usarli entrambi. Il pixel aggiunge dati del browser come il cookie fbp, mentre la Conversions API consegna gli eventi che il browser perde. Dai a entrambe le copie lo stesso nome evento e lo stesso event id, così Meta conta ogni evento una sola volta.

Quanto tempo aspetta Meta per deduplicare un evento del browser e uno del server?

Meta deduplica un evento del browser e uno del server con lo stesso nome evento e lo stesso event id quando arrivano a meno di 48 ore di distanza l’uno dall’altro. Una copia che arriva più tardi viene contata di nuovo.

La Conversions API richiede che i dati del cliente siano sottoposti a hash?

Sì, per i dati di contatto. I campi email, telefono, nome e indirizzo devono essere normalizzati e sottoposti a hash SHA-256. Indirizzo IP, user agent, fbp e fbc vengono inviati senza hash.

Quali campi sono obbligatori per un evento del sito web?

Ogni evento richiede event_name, event_time, action_source e almeno un parametro con informazioni sul cliente. Per gli eventi del sito web, Meta richiede anche event_source_url e client_user_agent.

Posso inviare vecchi ordini tramite la Conversions API?

Solo quelli recenti. L’event_time può essere al massimo di 7 giorni nel passato, e se un evento di una richiesta è più vecchio, Meta rifiuta l’intera richiesta.

Meta Conversions API (CAPI): una guida pratica

Punti chiave

La Meta Conversions API invia dal tuo server eventi come Purchase, così arrivano a Meta anche quando il pixel del browser è bloccato.
Usala insieme al pixel e dai a entrambe le copie lo stesso nome evento e lo stesso event_id; Meta allora conta l’evento una sola volta se entrambe arrivano entro 48 ore.
Gli eventi del sito richiedono action_source, event_source_url e lo user agent dell’acquirente; email e telefono con hash, indirizzo IP, fbp e fbc decidono quanto bene Meta riesce ad associarli.
Testa con la scheda Test events in Events Manager, poi rimuovi il codice di test, perché gli eventi di test non vengono scartati.
La maggior parte dei problemi nasce da event id che non coincidono, dall’indirizzo IP del server stesso, da un fbclid perso o da dati di contatto sottoposti ad hash senza normalizzazione.

La Meta Conversions API (CAPI) permette al tuo server di inviare eventi come Purchase direttamente a Meta. Il pixel Meta invia gli stessi eventi dal browser dell’acquirente. CAPI li invia dal tuo server, quindi arrivano comunque quando un ad blocker blocca il pixel, un cookie è sparito o la pagina di ringraziamento non si carica mai.

Questa guida spiega cosa contiene un evento della Conversions API, come usarla insieme al pixel con un solo event_id, quali parametri Meta richiede e consiglia, come testare con Test events e gli errori che compaiono più spesso.

Che cos’è la Meta Conversions API?

La Conversions API fa parte della Graph API di Meta. Il tuo server invia una richiesta HTTPS POST a graph.facebook.com/VERSION/PIXEL_ID/events con un token di accesso e un elenco data di al massimo 1,000 eventi. Ogni evento descrive un’azione, come un acquisto, in tre parti: cosa è successo, chi l’ha fatto e i dettagli.

Campo	Cosa contiene
`event_name`	L’azione, per esempio `Purchase`, `AddToCart` o `InitiateCheckout`
`event_time`	Quando è successo, come timestamp Unix in secondi
`event_id`	Un ID univoco per questo evento, usato per deduplicarlo rispetto al pixel
`action_source`	Dove è successo: `website` per gli acquisti nel negozio
`event_source_url`	L’URL della pagina in cui è avvenuto l’evento
`user_data`	Informazioni sul cliente per l’associazione: email e telefono con hash, indirizzo IP, user agent, fbp, fbc
`custom_data`	Dettagli come `value`, `currency` e `content_ids`

Ogni evento della Conversions API ha la stessa forma: l’azione, le informazioni sul cliente e i dettagli.

Un evento Purchase semplificato si presenta così:

Conversions API: un evento Purchase (abbreviato)

{
  "data": [{
    "event_name": "Purchase",
    "event_time": 1792929600,
    "event_id": "order-1042",
    "action_source": "website",
    "event_source_url": "https://yourstore.com/checkouts/thank-you",
    "user_data": {
      "em": ["<SHA-256 of the normalized email>"],
      "ph": ["<SHA-256 of the normalized phone>"],
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (iPhone; ...)",
      "fbp": "fb.1.1792928400000.1234567890",
      "fbc": "fb.1.1792928400000.AbCdEf123"
    },
    "custom_data": { "value": 74.00, "currency": "USD" }
  }]
}

I campi di contatto come email e telefono vengono normalizzati e sottoposti a hash SHA-256 prima di lasciare il tuo server. L’indirizzo IP, lo user agent, fbp e fbc vengono inviati così come sono.

Perché usare la Conversions API insieme al pixel?

Meta consiglia di usare la Conversions API insieme al pixel e di inviare gli stessi eventi da entrambi. Ciascuno vede qualcosa che l’altro non vede, e insieme danno a Meta dati più completi.

Pixel Meta (browser)

Imposta il cookie _fbp e salva l’fbclid di un clic su un annuncio nel cookie _fbc
Vede la pagina e il browser mentre la visita è in corso
Si perde quando il browser lo blocca o la pagina non si carica

Conversions API (server)

Invia l’ordine pagato a partire dai dati del tuo negozio
Può aggiungere email, telefono e indirizzo con hash presi dall’ordine
Non dipende dal browser, quindi gli ad blocker non lo fermano

Il pixel porta gli identificatori del browser e il server porta l’ordine. Ciascuno da solo perde una parte del quadro.

Il prezzo di usarli entrambi è che Meta ora riceve due copie di ogni evento. La sezione successiva mostra come Meta ne tiene una sola.

Come funziona la deduplicazione con un solo event_id?

Meta tratta un evento del browser e un evento del server come lo stesso evento quando due cose coincidono: il nome dell’evento e l’event id. Nel pixel l’id va nell’opzione eventID. Nella Conversions API lo stesso valore va in event_id.

Pixel Meta: lo stesso Purchase con eventID

fbq('track', 'Purchase', { value: 74.00, currency: 'USD' }, { eventID: 'order-1042' });

L’acquirente pagaOrdine 1042, $74.00

Il pixel invia PurchaseeventID order-1042, dal browser

Il server invia Purchaseevent_id order-1042, dall’ordine

Meta ne conta unoStesso nome e stesso id entro 48 ore

Entrambe le copie portano lo stesso nome evento e lo stesso id, quindi Meta tiene un solo acquisto invece di due.

Meta deduplica una coppia corrispondente solo quando le due copie arrivano a meno di 48 ore l’una dall’altra. Alcune regole fanno funzionare tutto nella pratica:

Crea l’id una sola volta. Costruiscilo da qualcosa che entrambe le parti conoscono, come il numero d’ordine, e passalo sia al browser sia al server. Due sistemi che creano ciascuno il proprio id non coincideranno.
Usa un solo formato. order-1042 e 1042 sono id diversi.
Fai coincidere esattamente il nome dell’evento. Purchase e purchase sono eventi diversi.
Invia subito l’evento server. Un evento server che arriva più di 48 ore dopo l’evento del browser viene contato una seconda volta.

Meta descrive anche un secondo metodo che accoppia gli eventi tramite fbp o external_id. Meta dice che in genere funziona solo quando l’evento del browser arriva prima dell’evento server, quindi un event_id condiviso è la scelta più affidabile. Se Meta riporta comunque più acquisti di quelli del tuo negozio, la nostra guida agli eventi di acquisto duplicati elenca le cause più comuni.

Quali parametri sono obbligatori e quali consigliati?

I campi obbligatori rendono valido un evento. I campi consigliati decidono quanti dei tuoi eventi Meta riesce ad associare a una persona, e solo gli eventi associati possono essere usati per l’attribuzione e per la distribuzione degli annunci.

Parametro	Eventi del sito web	Cosa inviare
`event_name`	Obbligatorio	Un evento standard come Purchase, oppure un nome di evento personalizzato
`event_time`	Obbligatorio	Unix time in secondi, al massimo 7 giorni nel passato
`action_source`	Obbligatorio	`website` per gli eventi sul tuo negozio
`event_source_url`	Obbligatorio	L’URL della pagina in cui è avvenuto l’evento
`client_user_agent`	Obbligatorio	La stringa del browser dell’acquirente, non quella del tuo server
`user_data`	Obbligatorio	Almeno un parametro con informazioni sul cliente
`event_id`	Consigliato	Lo stesso id usato dal pixel, per la deduplicazione
`em`, `ph`	Consigliato	Email e telefono, normalizzati e sottoposti a hash con SHA-256
`client_ip_address`	Consigliato	L’indirizzo IP dell’acquirente, senza hash
`fbp`, `fbc`	Consigliato	I cookie dell’ID browser e del click id, senza hash
`external_id`	Consigliato	Il tuo customer id, lo stesso negli eventi del browser e del server
`value`, `currency`	Da inviare con Purchase	Il valore dell’ordine e un codice valuta di tre lettere

Meta indica action_source, event_source_url e client_user_agent come obbligatori per gli eventi del sito inviati tramite la Conversions API.

Tre dettagli causano la maggior parte dei problemi:

Normalizza prima di fare l’hash. Meta si aspetta email senza spazi e in minuscolo, e numeri di telefono come cifre con il prefisso internazionale. Anna@Example.com e anna@example.com danno hash diversi, e solo il secondo può corrispondere.
Non fare l’hash degli identificatori del browser. fbp, fbc, l’indirizzo IP e lo user agent vanno inseriti come valori in chiaro.
Conserva il click id esattamente com’è. Il valore fbc è fb.1., l’ora di creazione in millisecondi, un punto e l’fbclid dell’URL della landing page. L’fbclid distingue tra maiuscole e minuscole. Salvalo quando il visitatore arriva, perché al checkout non è più nell’URL.

Quanto bene questi campi corrispondono è ciò che misura il punteggio Event Match Quality di Meta. La nostra guida a Event Match Quality spiega ogni parametro, le regole per l’hash e il punteggio a cui puntare.

Come si testano gli eventi con Test events?

Events Manager ha una scheda Test events che mostra gli eventi mentre arrivano. Usala prima di fare affidamento su una nuova configurazione.

Apri Test events
In Events Manager seleziona il tuo dataset (pixel) e apri la scheda Test events. Copia il codice di test che mostra.
Aggiungi il codice ai tuoi eventi server
Invialo come test_event_code nella richiesta. In ROASaurus, incollalo nel campo Test event code del pixel Meta.
Fai un ordine di prova
Visita il negozio, aggiungi un prodotto e paga, così che sia il pixel sia il server inviino un Purchase.
Confronta le due copie
Entrambe le copie devono mostrare lo stesso nome evento, event id, valore e valuta.
Controlla le informazioni sul cliente
L’evento server deve portare email e telefono con hash, l’indirizzo IP, lo user agent e fbp, più fbc se la visita è iniziata con un clic su un annuncio.
Rimuovi il codice di test
Meta dice che il campo serve solo per i test, quindi rimuovilo prima di fare affidamento sugli eventi.

Purchase browser order-1042 74.00 USDDal pixel

Purchase server order-1042 74.00 USDDalla Conversions API

event_name + event_id matchContati come un solo acquisto

em ph fbp fbc client_ip_address client_user_agentInformazioni sul cliente nell’evento server

Cosa mostra un buon ordine di prova (valori di esempio): due copie, un solo id e informazioni sul cliente complete.

Errori comuni della Conversions API e come risolverli

Cosa vedi	Causa probabile	Soluzione
L’intera richiesta fallisce e nessun evento viene elaborato	Un evento del batch ha un event_time più vecchio di 7 giorni	Invia gli eventi quando accadono. Correggi o scarta gli eventi vecchi prima di riprovare.
Meta riporta più acquisti di quelli del tuo negozio	Event id diversi, un evento del pixel senza eventID, o una seconda app che invia lo stesso pixel	Usa un solo id per entrambe le copie e un solo mittente server per pixel.
Qualità di associazione bassa sugli eventi server	Il tuo server invia il proprio indirizzo IP e il proprio user agent	Inoltra l’indirizzo IP e lo user agent rilevati dal browser o dall’ordine dell’acquirente.
Pochi eventi con fbc	L’fbclid non è stato salvato sulla landing page, oppure è stato modificato	Salva l’fbclid esattamente com’è arrivato e costruisci fbc a partire da esso.
Email e telefono non corrispondono	Valori sottoposti ad hash senza normalizzazione, o inviati senza hash	Elimina gli spazi e metti in minuscolo l’email, tieni le cifre e il prefisso internazionale del telefono, poi fai l’hash con SHA-256.
Le richieste falliscono con un errore di token scaduto	Il token di accesso proviene da un login Facebook, e i token di login scadono	Ricollega l’account, oppure usa un token System User da Business Manager, che puoi creare senza data di scadenza.

La maggior parte dei problemi della Conversions API si manifesta come richieste rifiutate, doppi conteggi o bassa qualità di associazione.

Dopo qualche giorno di traffico reale, apri la scheda Diagnostics in Events Manager. Meta vi elenca i problemi con i consigli per risolverli. Poi confronta il numero giornaliero di Purchase in Events Manager con gli ordini pagati nel tuo negozio per gli stessi giorni. Se Meta è chiaramente più alta, la nostra pagina di aiuto su come evitare il doppio conteggio elenca le impostazioni da controllare.

Come configurare la Conversions API con ROASaurus

ROASaurus invia gli eventi della Conversions API dai dati dell’ordine del tuo negozio, quindi non devi costruire tu il lato server. In Tracking & platforms clicca su Connect with Facebook e scegli il tuo account pubblicitario e il tuo pixel, oppure incolla l’id del pixel (dataset) e un token della Conversions API. La guida alla configurazione di Meta illustra entrambe le opzioni, e la pagina dell’integrazione Meta elenca ogni campo inviato.

Un solo id su entrambi i lati. Gli eventi del browser e del server condividono un unico event id. Per un acquisto è order- seguito dall’id dell’ordine.
Una breve attesa prima dell’acquisto. Il Purchase server attende un breve momento dopo l’arrivo dell’ordine, così l’evento di acquisto del browser può essere collegato per primo. Il suo indirizzo IP, il suo user agent e l’URL della pagina partono poi con l’evento server, insieme a fbp e fbc salvati per il visitatore.
Informazioni sul cliente prese dall’ordine. Email, telefono, nome e indirizzo vengono normalizzati e sottoposti a hash con SHA-256. Il customer id del negozio e il visitor id di ROASaurus vengono inviati con hash come external_id.
Gli eventi che Meta non riesce ad associare vengono saltati. Un evento senza fbc, fbp, email, telefono o indirizzo IP non viene inviato.

L’Event log mostra ogni invio del server con la richiesta e la risposta di Meta. Se i tuoi margini differiscono molto da un prodotto all’altro, puoi anche inviare un valore di profitto accanto a ogni acquisto: la nostra guida all’ottimizzazione del valore su Meta per il profitto spiega come. Per il percorso completo dei dati dal clic all’ordine, vedi tracciamento server-side.

Fonti

In ROASaurus

Continua a leggere

Piattaforme pubblicitarie e negozi onlineTracciamento delle conversioni con pagamento alla consegna e checkout esterniTracciamento delle conversioni con pagamento alla consegna: perché i pixel perdono gli ordini COD e quelli dei checkout esterni, quando inviare l’acquisto e come gestire gli ordini rifiutati.Piattaforme pubblicitarie e negozi onlineTracciamento delle conversioni con CCV Shop: guida alla configurazioneTracciamento delle conversioni con CCV Shop: invia gli ordini pagati a Meta e TikTok con un webhook firmato, collegali ai clic sugli annunci, configura, testa e gestisci i pagamenti in ritardo.Piattaforme pubblicitarie e negozi onlineConversioni avanzate di Google Ads su ShopifyLe conversioni avanzate aggiungono dati dei clienti con hash agli acquisti di Google Ads su Shopify. Come funzionano, in cosa differiscono dalle importazioni offline e la configurazione.