Tracciamento delle conversioni con CCV Shop: guida alla configurazione

Il tracciamento delle conversioni con CCV Shop significa segnalare alle piattaforme pubblicitarie come Meta e TikTok ogni ordine pagato nel tuo negozio online CCV Shop, così che attribuiscano gli annunci giusti e ottimizzino sulle vendite reali. Il modo più completo è inviare ogni acquisto dai dati d’ordine di CCV sul server, e aggiungere un breve snippet alla pagina di conferma dell’ordine che collega l’ordine al clic sull’annuncio.

CCV Shop è una piattaforma di negozi online in hosting dell’azienda olandese CCV, che dichiara di gestire 17,000 negozi online. Questa guida spiega come si collega ROASaurus a CCV Shop, come gli ordini vengono collegati ai clic sugli annunci, cosa arriva a Meta e TikTok, la configurazione, i test e come funzionano i pagamenti in ritardo. Per l’idea generale, leggi cos’è il tracciamento server-side.

Come si collega ROASaurus a CCV Shop?

ROASaurus usa tre parti di CCV Shop, tutte descritte nella documentazione API di CCV:

Perché i pixel del browser perdono gli acquisti di CCV Shop?

Un pixel del browser riporta un acquisto solo quando il browser dell’acquirente carica la pagina di conferma dell’ordine e lo script del pixel viene eseguito. Diverse situazioni comuni lo impediscono:

• L’acquirente paga con un reindirizzamento, per esempio con iDEAL, e chiude la scheda prima che la pagina di conferma si carichi.
• Un ad blocker o un’impostazione di privacy del browser blocca lo script del pixel.
• Il visitatore rifiuta i cookie di marketing, quindi il pixel non deve caricarsi.
• L’ordine viene pagato più tardi, con bonifico bancario o alla consegna, quando non c’è alcun browser coinvolto.

In ogni caso CCV Shop segna comunque l’ordine come pagato. ROASaurus invia quell’ordine dal server, quindi l’acquisto viene riportato qualunque cosa sia successa nel browser. Lo snippet nella pagina di conferma ha un compito diverso: dice a ROASaurus a quale visitatore, e quindi a quale clic sull’annuncio, appartiene l’ordine.

Il webhook dell’ordine pagato e il controllo ogni 5 minuti

Cosa fa Create webhook

Quando premi Create webhook, ROASaurus registra un webhook CCV per l’evento orders.updated.ispaid, che CCV fa scattare quando cambia la proprietà «pagato» di un ordine. L’indirizzo è l’URL del webhook del tuo negozio in ROASaurus, che contiene la tua store key e un token privato. CCV non aggiunge a un webhook nulla che identifichi il negozio, e la sua documentazione consiglia di mettere un identificatore nell’indirizzo. La store key svolge questo compito.

CCV assegna a ogni webhook una propria chiave segreta di 32 caratteri. Quando CCV restituisce quella chiave, ROASaurus la salva e da quel momento ogni invio deve portare un header x-hash valido. Ogni invio deve portare anche il token del tuo negozio. Quando riceve un invio, ROASaurus ignora gli ordini non pagati, legge dall’API l’ordine completo e le sue righe, e invia l’ordine solo quando CCV dice che è pagato.

Chiamate API firmate

CCV richiede che ogni chiamata API sia firmata. ROASaurus invia tre header: x-public con la tua chiave pubblica, x-date con l’ora corrente e x-hash. CCV rifiuta un timestamp che differisce di più di 5 minuti dall’ora del suo server. La tua chiave segreta non viene mai inviata.

API call (ROASaurus → CCV)
x-hash = HMAC-SHA512( public_key|METHOD|uri|body|timestamp , secret_key )

Webhook (CCV → ROASaurus)
x-hash = HMAC-SHA512( address|payload , webhook_key )

Il controllo ogni 5 minuti

Ogni 5 minuti ROASaurus chiede anche a CCV gli ordini pagati creati dall’ultimo controllo, con 30 minuti di sovrapposizione, e registra quelli che non ha ancora. CCV filtra gli ordini solo per data di creazione. Quindi il controllo trova gli ordini pagati poco dopo essere stati effettuati, mentre un ordine pagato giorni dopo arriva a ROASaurus solo tramite il webhook.

CCV considera una risposta 200, 201, 202 o 204 un successo. Tiene aperto un invio e lo ritenta alla successiva occorrenza dopo una risposta 307, 408, 503 o 504, e segna qualsiasi altra risposta come fallita. Aspetta 2 secondi per una connessione e 5 secondi per la risposta.

Come viene collegato un ordine di CCV Shop al clic sull’annuncio?

Per attribuire un annuncio, la piattaforma ha bisogno degli identificatori del clic del visitatore che ha ordinato, come il click id di Meta (fbc) e il click id di TikTok (ttclid). Lo script di ROASaurus li memorizza per ogni visitatore quando arriva da un annuncio. ROASaurus non ottiene quel visitor id dall’ordine CCV, quindi collega gli ordini ai visitatori in altri modi:

ROASaurus aspetta un attimo prima di inviare ogni acquisto, così l’evento della pagina di conferma può arrivare per primo, e riprova l’associazione al momento dell’invio. La pagina Orders mostra il risultato per ogni ordine nella colonna Matched by: thank_you, email o not matched.

Un ordine non associato va comunque alle tue piattaforme pubblicitarie con i dati del cliente con hash presi dall’ordine. Non ha identificatori del clic e, poiché gli ordini CCV non portano né indirizzo IP né browser, non ha nemmeno quelli. Questo riduce la quota di eventi che Meta riesce ad associare a una persona; Event Match Quality spiega come Meta la valuta. Nell’attribuzione di ROASaurus, un ordine non associato compare come diretto o sconosciuto.

Cosa arriva a Meta e TikTok da un ordine CCV?

Meta riceve un Purchase tramite la sua Conversions API, e TikTok un CompletePayment tramite la sua Events API, entrambi con l’event id order-58213. TikTok ora mostra CompletePayment come Purchase nei suoi report. Quando selezioni l’opzione per caricare anche il pixel del browser, lo snippet della pagina di conferma fa scattare gli stessi eventi nel browser con lo stesso event id, e Meta e TikTok ne tengono una sola copia. Gli stessi ordini vanno a Snapchat, Pinterest, Reddit, X, Microsoft Ads, Taboola, LinkedIn e alle altre piattaforme pubblicitarie quando le colleghi. Le conversioni di acquisto di Google Ads vengono inviate solo dal checkout di Shopify, quindi ROASaurus non le invia da CCV Shop.

Come configurare il tracciamento delle conversioni con CCV Shop

1. Aggiungi il negozio in ROASaurus

   Vai su Add a store, scegli CCV Shop e inserisci l’indirizzo del tuo negozio. La scheda Connection mostra poi il tuo script tag e lo snippet della pagina di conferma.

2. Trova le tue chiavi API

   In CCV Shop, vai su My webshop › Settings › General › API settings e fai clic su New API key. Se non vedi questa opzione, installa prima l’app API dal CCV App Store.

3. Aggiungi lo script a ogni pagina

   Incolla lo script tag nell’Header HTML del tuo negozio. Il centro assistenza di CCV lo colloca sotto Mijn webshop › Instellingen › Lay-out › Layout, in fondo alla pagina. Funziona anche un blocco di codice di un’app nell’header.

4. Aggiungi lo snippet alla pagina di conferma

   Vai su Mijn webshop › Instellingen › Algemeen › Teksten, apri il testo mostrato dopo l’invio di un ordine, passa a Source e incolla lì lo snippet. CCV Shop lo esegue poi nella pagina di conferma dell’ordine.

5. Collega l’API

   Nella scheda Connection, inserisci la chiave pubblica e la chiave segreta. Compila Shop URL solo se la tua API gira su un dominio diverso da quello del negozio. Salva, premi Test connection, poi Create webhook.

6. Collega le tue piattaforme pubblicitarie

   In Tracking & platforms, usa Connect with Facebook o Add pixel per Meta, e Add pixel per TikTok. Seleziona l’opzione per caricare anche il pixel del browser.

Consenso

Fuori da Shopify, lo script di ROASaurus legge la scelta del visitatore dagli strumenti per il consenso più comuni: Cookiebot, OneTrust, banner IAB TCF e Google consent mode. Con un altro banner dei cookie, chiama tlq('consent', true) quando il visitatore accetta i cookie di marketing e tlq('consent', false) quando li rifiuta. Finché il visitatore non accetta, non ha alcun visitor id né click id e non scatta alcun pixel del browser. L’ordine pagato viene comunque inviato dal server con i dati del cliente sottoposti ad hash presi dall’ordine. La pagina di aiuto sul consenso spiega i dettagli.

Come si testa il tracciamento delle conversioni con CCV Shop?

• Apri il tuo negozio con ?roasaurus=connected nell’indirizzo. Un avviso conferma che lo script è in esecuzione. ?roasaurus=debug registra nella console del browser ciò che invia.
• Nell’Event log, sotto Collected events, le visualizzazioni di pagina dovrebbero mostrare un visitor id.
• Effettua un ordine e pagalo, oppure segnalo come pagato. Sotto Collected events, l’Event log dovrebbe mostrare un Purchase con l’order id di CCV nei suoi dati. Se manca, lo snippet della pagina di conferma non è stato eseguito.
• Nella scheda Connection, Last order received mostra l’ordine e Last sync l’ultimo controllo da 5 minuti, con l’eventuale errore di CCV.
• Sotto Server deliveries nell’Event log, ogni piattaforma collegata ottiene una riga con lo stato sent e la risposta della piattaforma.

Per vedere l’evento in Meta, incolla il codice da Events Manager › Test events nel campo Test event code del tuo pixel Meta in ROASaurus, e rimuovilo quando hai finito.

Pagamenti in ritardo e altri limiti

I bonifici bancari e i pagamenti alla consegna vengono pagati dopo che l’ordine è stato effettuato. Ecco cosa succede a un ordine di esempio con bonifico bancario, dal giorno in cui viene effettuato:

• Pagamento alla consegna. ROASaurus invia questi ordini quando CCV li segna come pagati, di solito dopo la consegna. Vedi il tracciamento con pagamento alla consegna per sapere quando conteggiare questi ordini.
• Acquisti del browser prima del pagamento. Lo snippet della pagina di conferma viene eseguito quando l’ordine è effettuato, quindi i pixel del browser riportano un ordine con bonifico bancario prima che sia pagato. Se il pagamento arriva dopo più di 48 ore, Meta e TikTok non riescono a unire le copie del browser e del server.
• Nessun ripiego sull’IP. Aggiungi lo snippet della pagina di conferma e, dove puoi, raccogli le email prima sul tuo sito.
• Annullamenti e rimborsi non vengono inviati. Una volta inviato, un acquisto resta nella piattaforma pubblicitaria.
• Solo visualizzazioni di pagina, senza codice. Le visualizzazioni di prodotto e le aggiunte al carrello vengono rilevate automaticamente solo su Shopify. Su CCV Shop, uno sviluppatore può inviarle con una chiamata di tracciamento tlq.

La pagina di integrazione con CCV Shop riunisce in un unico posto i dati sulla connessione, e la pagina di aiuto per gli altri negozi online confronta CCV Shop con le altre piattaforme a cui si collega ROASaurus, come Lightspeed.

Fonti

1. CCV Shop: API Documentatie
2. CCV: Webshop API
3. Meta for Developers: Server Event Parameters
4. Meta for Developers: Handling Duplicate Pixel and Conversions API Events
5. TikTok Ads Manager: About Event Deduplication

In ROASaurus

• Integrazione CCV Shop
• Assistenza: Wix, Lightspeed e altri negozi online
• Tracciamento server-side
• Integrazione Meta

Continua a leggere