Come funziona
Poiché Zonos Checkout viene eseguito all'interno di un iframe su un'origine
diversa, non può accedere direttamente alla funzione fbq della tua pagina.
Il sistema di relay risolve questo problema con un handshake in due passaggi
(passaggi 1-2) seguito dal forwarding degli eventi (passaggio 3):
- Checkout invia un ping alla pagina principale -- Quando il checkout si carica all'interno dell'iframe, invia un messaggio alla finestra principale indicando che è pronto a trasmettere gli eventi, incluso l'ID del Pixel.
- La pagina principale conferma -- Lo script di relay sulla tua pagina riceve il ping, rileva (o inietta) il codice base di Meta Pixel e segnala che è pronto a ricevere eventi.
- Gli eventi vengono trasmessi -- Mentre gli acquirenti procedono nel
checkout, ogni evento di analytics viene inviato tramite
postMessagealla tua pagina, dove lo script di relay lo trasmette afbqcon la modalitàtrack/trackCustomappropriata.
Tutti i messaggi vengono validati rispetto a origini Zonos attendibili
(zonos.com e iglobalstores.com) esclusivamente tramite HTTPS.
Prerequisiti
- Un Meta Pixel con un ID Pixel (una stringa numerica, tipicamente di 15-16 cifre). Puoi crearne uno in Meta Events Manager.
- Un'integrazione legacy di Checkout che carica Zonos Checkout in un iframe sulla tua pagina.
- Facebook Pixel abilitato nelle impostazioni di Zonos Checkout (nel dashboard Zonos, in Impostazioni Checkout -> Tracciamento).
Configurazione
Passaggio 1: aggiungi il codice base di Meta Pixel alla tua pagina
Se non hai già installato Meta Pixel sul tuo sito, aggiungi il codice base
standard del Pixel nel <head> della pagina che ospita l'iframe di Checkout.
Sostituisci YOUR_PIXEL_ID con il tuo ID Pixel numerico.
<!-- Meta Pixel Code --> <script> !(function (f, b, e, v, n, t, s) { if (f.fbq) return; n = f.fbq = function () { n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments); }; if (!f._fbq) f._fbq = n; n.push = n; n.loaded = !0; n.version = '2.0'; n.queue = []; t = b.createElement(e); t.async = !0; t.src = v; s = b.getElementsByTagName(e)[0]; s.parentNode.insertBefore(t, s); })( window, document, 'script', 'https://connect.facebook.net/en_US/fbevents.js', ); fbq('init', 'YOUR_PIXEL_ID'); fbq('track', 'PageView');</script>Nota: se il tuo sito ha già Meta Pixel installato (ad esempio tramite Google Tag Manager, l'integrazione nativa di Shopify o uno snippet diretto), puoi saltare questo passaggio. Lo script di relay utilizzerà la tua funzione
fbqesistente.
Puoi trovare questo snippet nel tuo Meta Events Manager, nelle Impostazioni del tuo Pixel -> Continua configurazione Pixel -> Installa codice manualmente.
Passaggio 2: passa il tuo ID Pixel a Zonos Checkout
Indica a Zonos Checkout quale ID Pixel utilizzare impostando
window.Zonos.facebookPixelId all'interno del customHTML del tuo Checkout.
Il dashboard Zonos espone un editor customHTML nelle impostazioni Checkout --
aggiungi un tag <script> come questo:
<script> window.Zonos.facebookPixelId = 'YOUR_PIXEL_ID';</script>Questo valore viene inviato alla pagina principale durante l'handshake del
relay. Se la tua pagina principale non ha già fbq caricato, lo script di
relay inietterà il codice base di Meta Pixel per te utilizzando questo ID.
Passaggio 3: aggiungi lo script di relay analytics di Zonos
Aggiungi il seguente tag script alla stessa pagina che carica l'iframe di Checkout, dopo il codice base di Meta Pixel. Questo è lo stesso script utilizzato per Google Analytics 4 -- un unico relay gestisce entrambi i provider, quindi se lo hai già aggiunto per GA4, salta questo passaggio.
<script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"></script>Esempio completo
Ecco come si presenta la configurazione completa nel <head> della tua
pagina:
<head> <!-- ... your existing head tags ... --> <!-- Meta Pixel Code --> <script> !(function (f, b, e, v, n, t, s) { if (f.fbq) return; n = f.fbq = function () { n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments); }; if (!f._fbq) f._fbq = n; n.push = n; n.loaded = !0; n.version = '2.0'; n.queue = []; t = b.createElement(e); t.async = !0; t.src = v; s = b.getElementsByTagName(e)[0]; s.parentNode.insertBefore(t, s); })( window, document, 'script', 'https://connect.facebook.net/en_US/fbevents.js', ); fbq('init', 'YOUR_PIXEL_ID'); fbq('track', 'PageView'); </script> <!-- Zonos analytics relay for iframe checkout --> <script async src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js" ></script></head>Tutto qui. Una volta che entrambi gli script sono sulla tua pagina, Facebook
Pixel è abilitato nel tuo dashboard Zonos e customHTML imposta l'ID del
Pixel, il relay trasmette automaticamente tutti gli eventi del funnel di
checkout a Meta.
Riferimento eventi Meta Pixel
Per ogni passaggio del funnel, Zonos Checkout genera sia un evento
personalizzato (per creare pubblici precisi) sia l'evento standard Meta
corrispondente (in modo che appaia nell'ottimizzazione e nel reporting delle
conversioni di Meta). Tutti gli eventi includono un flag isTestMode e il
checkoutSessionId.
| Trigger↕ | Evento personalizzato (fbq('trackCustom', ...))↕ | Evento standard (fbq('track', ...))↕ | Metadati aggiuntivi↕ |
|---|---|---|---|
| Il checkout si apre | zonos-checkout-start | InitiateCheckout | -- |
| L'acquirente inserisce le informazioni cliente | zonos-checkout-customer-info | nessuno | -- |
| L'acquirente seleziona un metodo di spedizione | zonos-checkout-shipping-info | nessuno | serviceLevelId |
| L'acquirente inserisce i dettagli di pagamento | zonos-checkout-payment-info | AddPaymentInfo | paymentMethod |
| Il tentativo di pagamento fallisce | zonos-checkout-payment-fail | nessuno | -- |
| L'ordine si completa con successo | zonos-checkout-success | nessuno | order_id, currency, value, contents, content_ids |
| L'ordine si completa (evento e-commerce) | purchase | Purchase | order_id, currency, value, contents, content_ids |
| L'acquirente chiude il checkout | zonos-checkout-close | nessuno | -- |
I passaggi senza un equivalente standard Meta (ad es. informazioni cliente, informazioni di spedizione) generano solo l'evento personalizzato
zonos-checkout-.... Puoi indirizzarli in Meta Ads Manager tramite pubblici personalizzati usando "Event =zonos-checkout-customer-info", ecc.
Metadati dell'evento Purchase
L'evento standard Purchase segue lo schema
dell'evento Purchase di Meta Pixel.
Gli articoli del carrello vengono mappati dall'array items in stile GA
nell'array contents di Meta:
| Campo↕ | Descrizione↕ |
|---|---|
value | Valore totale dell'ordine |
currency | Codice valuta a tre lettere (ad es. USD) |
order_id | ID ordine Zonos o ID sessione di checkout |
contents | Array di articoli del carrello, ciascuno con id, quantity e item_price |
content_ids | Array di ID articolo (SKU, ID prodotto o nome prodotto come fallback) |
content_type | Sempre "product" |
num_items | Quantità totale di tutti gli articoli |
Debug
Per abilitare il logging di debug per lo script di relay, aggiungi il
parametro di query zonosDebug=1 all'URL della tua pagina:
https://www.yourstore.com/checkout?zonosDebug=1Apri la console per sviluppatori del tuo browser per vedere i log dettagliati dell'handshake del relay e degli eventi trasmessi. Questo è utile per verificare che:
- Lo script di relay riceva il ping dall'iframe di checkout.
- Meta Pixel sia configurato con l'ID Pixel corretto.
- Gli eventi vengano trasmessi a
fbqcon la modalitàtrack/trackCustomattesa.
L'estensione Chrome Meta Pixel Helper è anche utile per ispezionare le chiamate al Pixel in tempo reale.
Domande frequenti
Perché vengono generati due eventi per lo stesso passaggio (ad es. zonos-checkout-start e InitiateCheckout)?
Gli eventi standard di Meta alimentano l'ottimizzazione delle conversioni, il
reporting degli annunci e i pubblici simili fin da subito. Gli eventi
personalizzati zonos-checkout-... ti permettono di creare pubblici
personalizzati più granulari sull'esatto passaggio del funnel, anche quando
non esiste un equivalente standard Meta (ad es. informazioni cliente,
informazioni di spedizione). Generare entrambi ti offre il meglio di entrambi
i mondi senza perdere alcun segnale.
Cosa succede se utilizzo sia Google Analytics che Facebook Pixel?
Non hai bisogno di due script di relay -- lo stesso analyticsRelayOnInit.js
gestisce entrambi i provider in un unico handshake. Aggiungi il tag base GA4 e
il codice base di Meta Pixel al tuo <head>, imposta sia
window.Zonos.googleAnalyticId che window.Zonos.facebookPixelId in
customHTML e abilita entrambi i provider nel tuo dashboard Zonos. Ogni
evento viene distribuito a tutti i provider abilitati.
Cosa succede se la mia pagina principale non ha Meta Pixel installato?
Se il tuo customHTML imposta window.Zonos.facebookPixelId e lo script di
relay non rileva fbq sulla pagina, inietterà il codice base di Meta Pixel
per te durante l'handshake utilizzando l'ID Pixel fornito. Puoi anche
preinstallare tu stesso il codice base di Meta Pixel se desideri generare
PageView e altri eventi al di fuori del funnel di checkout.
Gli ordini di test vengono tracciati?
Tutti gli eventi includono un campo isTestMode. Quando Checkout è in
modalità test, gli eventi vengono comunque trasmessi a Meta ma contrassegnati
con isTestMode: true. Puoi filtrarli in Meta Ads Manager o escluderli con
regole di conversione personalizzate.
La Conversions API (CAPI) sostituisce questo sistema?
No -- questa è un'integrazione Pixel lato browser che viene eseguita nei browser degli acquirenti. La Meta Conversions API è un canale server-to-server separato che alcuni merchant utilizzano insieme al Pixel per ridondanza. I due sistemi sono complementari e il relay di Zonos gestisce solo il Pixel lato browser.
Facebook Pixel per Checkout con iframe
Traccia l'intero funnel di checkout con Meta (Facebook) Pixel quando utilizzi un'integrazione legacy di Checkout basata su iframe.
I merchant che utilizzano l'integrazione legacy di Checkout (iframe ospitato su
iglobalstores.com) possono tracciare gli eventi di Meta Pixel in tutto il funnel di checkout. Zonos Checkout trasmette automaticamente gli eventi di analytics dall'iframe alla pagina principale utilizzando lo stesso script di relay leggero usato per Google Analytics 4, così gli eventi appaiono nel tuo Meta Events Manager come se provenissero dal tuo sito.Per ogni passaggio del funnel vengono emessi due eventi:
zonos-checkout-...(tramitefbq('trackCustom', ...)) per segmenti di pubblico personalizzati sull'intero funnel.fbq('track', ...)) per l'ottimizzazione integrata, ad es.InitiateCheckout,AddPaymentInfoePurchase.