Come configuro Facebook Pixel con Zonos legacy iframe Checkout?

Aggiungi il codice base standard di Meta Pixel alla pagina che ospita l'iframe di Checkout, imposta window.Zonos.facebookPixelId nel customHTML del tuo Checkout, abilita Facebook Pixel nel tuo dashboard Zonos e aggiungi lo script Zonos analyticsRelayOnInit.js. Lo script di relay gestisce automaticamente la comunicazione cross-iframe e trasmette gli eventi di checkout a Meta.

Quali eventi Facebook Pixel traccia Zonos Checkout?

Per ogni passaggio del funnel, Zonos genera sia un evento personalizzato (zonos-checkout-start, zonos-checkout-customer-info, zonos-checkout-shipping-info, zonos-checkout-payment-info, zonos-checkout-payment-fail, zonos-checkout-success, zonos-checkout-close) sia l'evento standard Meta corrispondente quando esiste: InitiateCheckout per l'avvio del checkout, AddPaymentInfo per le informazioni di pagamento e Purchase per il completamento dell'ordine.

Posso usare contemporaneamente Google Analytics e Facebook Pixel?

Sì. Lo stesso script analyticsRelayOnInit.js gestisce entrambi i provider in un unico handshake. Aggiungi entrambi i tag base alla tua pagina, imposta window.Zonos.googleAnalyticId e window.Zonos.facebookPixelId in customHTML e abilita entrambi i provider nel tuo dashboard Zonos.

Checkout•

HomeRiferimento API Checkout REST API Facebook Pixel

Facebook Pixel per Checkout con iframe

Q: Come eseguo il debug degli eventi Facebook Pixel da Zonos Checkout?

Aggiungi il parametro di query zonosDebug=1 all'URL della tua pagina e apri la console per sviluppatori del tuo browser per vedere i log dettagliati dell'handshake del relay e degli eventi trasmessi. L'estensione Chrome Meta Pixel Helper è utile anche per ispezionare le chiamate al Pixel in tempo reale.

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:

Un evento personalizzato denominato zonos-checkout-... (tramite fbq('trackCustom', ...)) per segmenti di pubblico personalizzati sull'intero funnel.
L'evento standard Meta corrispondente (tramite fbq('track', ...)) per l'ottimizzazione integrata, ad es. InitiateCheckout, AddPaymentInfo e Purchase.

Le integrazioni native non necessitano di questa guida. Se <zonos-checkout> viene renderizzato direttamente sul tuo sito (senza iframe), Zonos chiama direttamente window.fbq della tua pagina -- basta abilitare Facebook Pixel nel dashboard Zonos in Impostazioni Checkout → Tracciamento e assicurarsi che il codice base di Meta Pixel abituale sia caricato sulla pagina. La configurazione del relay descritta di seguito è necessaria solo quando Checkout è ospitato in un iframe su un'origine diversa.

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 postMessage alla tua pagina, dove lo script di relay lo trasmette a fbq con la modalità track / trackCustom appropriata.

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.

1

3<script>

4 !(function (f, b, e, v, n, t, s) {

5 if (f.fbq) return;

6 n = f.fbq = function () {

7 n.callMethod ? n.callMethod.apply(n, arguments) : n.queue.push(arguments);

8 };

9 if (!f._fbq) f._fbq = n;

10 n.push = n;

11 n.loaded = !0;

12 n.version = '2.0';

13 n.queue = [];

14 t = b.createElement(e);

15 t.async = !0;

16 t.src = v;

17 s = b.getElementsByTagName(e)[0];

18 s.parentNode.insertBefore(t, s);

19 })(

20 window,

21 document,

22 'script',

23 'https://connect.facebook.net/en_US/fbevents.js',

24 );

25 fbq('init', 'YOUR_PIXEL_ID');

26 fbq('track', 'PageView');

27</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 fbq esistente.

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:

1<script>

2 window.Zonos.facebookPixelId = 'YOUR_PIXEL_ID';

3</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.

1<script

2 async

3 src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"

4></script>

Esempio completo

Ecco come si presenta la configurazione completa nel <head> della tua pagina:

1<head>

2 

4 

6 <script>

7 !(function (f, b, e, v, n, t, s) {

8 if (f.fbq) return;

9 n = f.fbq = function () {

10 n.callMethod

11 ? n.callMethod.apply(n, arguments)

12 : n.queue.push(arguments);

13 };

14 if (!f._fbq) f._fbq = n;

15 n.push = n;

16 n.loaded = !0;

17 n.version = '2.0';

18 n.queue = [];

19 t = b.createElement(e);

20 t.async = !0;

21 t.src = v;

22 s = b.getElementsByTagName(e)[0];

23 s.parentNode.insertBefore(t, s);

24 })(

25 window,

26 document,

27 'script',

28 'https://connect.facebook.net/en_US/fbevents.js',

29 );

30 fbq('init', 'YOUR_PIXEL_ID');

31 fbq('track', 'PageView');

32 </script>

34 

36 <script

37 async

38 src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/analyticsRelayOnInit.js"

39 ></script>

40</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:

1https://www.yourstore.com/checkout?zonosDebug=1

Apri 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 fbq con la modalità track / trackCustom attesa.

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.

Prenota una demo