Tracciamento delle conversioni con Lightspeed per i negozi online eCom

Il tracciamento delle conversioni Lightspeed significa segnalare a piattaforme pubblicitarie come Meta e TikTok ogni ordine pagato nel tuo negozio online Lightspeed eCom, così che possano attribuire il merito agli annunci giusti e ottimizzare le tue campagne. Il modo affidabile è inviare ogni acquisto dal server a partire dai dati dell’ordine di Lightspeed, e aggiungere alla pagina di ringraziamento un breve snippet che collega l’ordine al clic sull’annuncio.

Questa guida spiega a quale prodotto Lightspeed si applica, come arrivano gli ordini a ROASaurus, cosa viene letto da ogni ordine, come gli acquisti arrivano a Meta e TikTok, la configurazione, i test e i limiti da conoscere.

Quale prodotto Lightspeed copre questa guida?

Lightspeed vende più di un prodotto di e-commerce, quindi controlla prima il tuo. ROASaurus si collega a Lightspeed eCom (C-Series), la piattaforma di negozi online il cui back office ha Settings › Website Settings › Web Extras. La sua API funziona su due cluster:

Ogni indirizzo API contiene anche un codice lingua di due lettere, per esempio /nl/ o /en/. ROASaurus lo chiede come lingua del negozio e usa nl quando lo lasci vuoto.

Lightspeed offre anche eCom (E-Series). Lightspeed descrive il passaggio a E-Series come un upgrade a un prodotto separato, attualmente offerto a determinati commercianti nordamericani. Il connettore Lightspeed di ROASaurus legge gli ordini solo tramite l’API C-Series, quindi non copre i negozi E-Series.

Perché gli acquisti Lightspeed spariscono in Meta e TikTok?

Un pixel nel browser segnala un acquisto solo quando il browser dell’acquirente carica la pagina di ringraziamento e lo script del pixel viene eseguito. Questo non funziona in diverse situazioni comuni:

• Un acquirente paga con un reindirizzamento, per esempio con iDEAL o PayPal, e chiude la scheda prima che si carichi la pagina di ringraziamento.
• 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, per esempio con bonifico bancario, quando non è coinvolto nessun browser.
• Safari limita per quanto tempo durano i cookie impostati dagli script, quindi il browser può dimenticare un clic su un annuncio più vecchio.

Come arrivano a ROASaurus gli ordini di Lightspeed?

Quando premi Create webhook, ROASaurus registra in Lightspeed un webhook per il gruppo orders e l’azione updated, in formato JSON. Da quel momento, Lightspeed chiama ROASaurus quando un ordine cambia.

Perché ROASaurus rilegge l’ordine

Lightspeed aggiunge un header x-signature a un webhook solo quando lo ha creato un’app. Un webhook creato con una semplice chiave API, come qui, non è firmato. Per questo l’indirizzo del webhook contiene un token unico per il tuo negozio, e ROASaurus non si fida del payload. Legge l’ordine e i suoi prodotti dall’API di Lightspeed e controlla da sé lo stato di pagamento.

Il controllo ogni 5 minuti

Ogni 5 minuti, ROASaurus chiede inoltre a Lightspeed gli ordini aggiornati dall’ultimo controllo, con 30 minuti di sovrapposizione, e registra gli ordini pagati che non ha ancora. Poiché questo controllo usa l’orario di aggiornamento, un ordine pagato giorni dopo essere stato effettuato viene intercettato anche se l’invio del suo webhook è fallito. Gli ordini che ROASaurus ha già vengono ignorati, quindi il webhook e il controllo non creano mai due acquisti.

Dal lato di Lightspeed, un webhook deve ricevere una risposta 2xx entro 5 secondi. Gli invii falliti vengono ritentati, fino a 10 tentativi in totale, e un webhook il cui rapporto di errori resta sopra il 50% per 50 ore viene disattivato. Il controllo ogni 5 minuti mantiene il flusso degli ordini durante un simile intervallo.

Cosa legge ROASaurus da un ordine Lightspeed?

Il valore dell’acquisto include l’IVA

priceIncl di Lightspeed è il prezzo dell’ordine imposte incluse, ed è il valore che ROASaurus invia. Le tue piattaforme pubblicitarie quindi riportano ricavi con IVA inclusa. Ecco l’effetto con il 21% di IVA:

Un ROAS di pareggio usa i ricavi senza IVA. Dividi il ROAS della piattaforma per 1 più la tua aliquota IVA prima di confrontare i due.

Come viene collegato un ordine Lightspeed al clic sull’annuncio?

Per attribuire il merito a un annuncio, la piattaforma ha bisogno degli identificatori di clic del visitatore che ha ordinato: il click id e il browser id di Meta (fbc, fbp), il click id di TikTok (ttclid) e il cookie di TikTok (ttp). Lo script di ROASaurus li salva per ogni visitatore quando atterra da un annuncio. ROASaurus non ottiene quell’id del visitatore dall’ordine Lightspeed, quindi collega ogni ordine a un visitatore in un altro modo. Prova tre metodi, in quest’ordine:

Lo snippet passa anche il totale dell’ordine, la valuta e l’email del cliente. ROASaurus salva sul visitatore un hash di quell’email, che aiuta ad associare l’ordine successivo dello stesso acquirente. ROASaurus aspetta brevemente prima di inviare ogni acquisto, così l’evento della pagina di ringraziamento può arrivare per primo, e riprova l’associazione al momento dell’invio.

Lightspeed variables used by the ROASaurus snippet (Tracking box)

order.information.number      order id and event id order-<number>
order.information.price_incl  value
order.information.currency    currency
order.customer.email          email, hashed on the visitor

La pagina Orders mostra come ogni ordine è stato collegato, nella colonna Matched by: thank_you, email, ip o not matched. Un ordine non associato va comunque alle tue piattaforme pubblicitarie con i suoi dati d’ordine, ma senza identificatori di clic, e l’attribuzione di ROASaurus lo mostra come diretto o sconosciuto.

Invio degli acquisti Lightspeed a Meta e TikTok

Ogni ordine pagato diventa un evento server per ogni piattaforma collegata: un Purchase per la Conversions API di Meta e un CompletePayment per l’Events API di TikTok, entrambi con l’event id order-ORD01042. TikTok ora mostra CompletePayment come Purchase nei suoi report. Quando spunti l’opzione per caricare anche il pixel del browser, lo snippet della pagina di ringraziamento attiva gli stessi eventi nel browser con lo stesso event id. Meta e TikTok tengono poi 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 Lightspeed. Per la parte di configurazione lato Meta, vedi la guida alla Meta Conversions API.

Come configurare il tracciamento delle conversioni Lightspeed

1. Aggiungi il negozio in ROASaurus

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

2. Aggiungi lo script a ogni pagina

   Nel back office di Lightspeed, vai su Settings › Website Settings › Web Extras › Custom JavaScript e incolla lo script tag. Lightspeed esegue questo codice su tutte le pagine.

3. Aggiungi lo snippet della pagina di ringraziamento

   Nella stessa pagina, nell’area Tracking, attiva Status e incolla lo snippet. Lightspeed lo esegue sulla pagina Thank You dopo un ordine.

4. Crea una chiave API

   Vai su Settings › Store Settings › Developers › New API key. Attiva la chiave, spunta l’accesso in lettura agli ordini, salva e seleziona Show per vedere il secret.

5. Collega l’API

   Nella scheda Connection, inserisci la chiave, il secret, la regione e la lingua 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 con il codice del pixel e un access token dell’Events API. Spunta l’opzione per caricare anche il pixel del browser.

API key          (Settings › Store Settings › Developers)
API secret       (select Show next to the key)
Region           eu  →  api.webshopapp.com
                 us  →  api.shoplightspeed.com
Shop language    nl, en, de ...  (the code in your API addresses)

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 e con l’indirizzo IP e il browser dell’ordine. La pagina di aiuto sul consenso spiega i dettagli.

Come si testa il tracciamento delle conversioni Lightspeed?

• 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.
• Fai un ordine e assicurati che il suo stato di pagamento sia paid. In Collected events, l’Event log dovrebbe poi mostrare un Purchase con il tuo numero d’ordine nei suoi dati. Se manca, controlla che Status sia attivo nell’area Tracking.
• Nella scheda Connection, Last order received mostra l’ordine e Last sync mostra l’ultimo controllo ogni 5 minuti, con l’eventuale errore di Lightspeed.
• 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. Le impostazioni del pixel TikTok in ROASaurus hanno lo stesso campo.

Limiti e casi particolari

• Solo C-Series. I negozi Lightspeed eCom E-Series non possono usare questo connettore.
• Solo ordini pagati. Un ordine partially paid viene inviato quando il suo stato di pagamento cambia in paid.
• Pagamenti in ritardo e il limite di 7 giorni di Meta. Meta accetta eventi server fino a 7 giorni dopo l’orario dell’evento. ROASaurus usa l’orario di creazione dell’ordine, quindi un ordine pagato più di 7 giorni dopo essere stato effettuato viene rifiutato da Meta.
• Acquisti dal browser prima del pagamento. Lo snippet della pagina di ringraziamento viene eseguito quando l’ordine viene effettuato, quindi i pixel del browser riportano un ordine con bonifico prima che sia pagato. Se il pagamento arriva più di 48 ore dopo, Meta e TikTok non possono unire le copie del browser e del server.
• 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 Lightspeed, uno sviluppatore può inviarle con una chiamata di tracciamento tlq.
• Limiti dell’API. Lightspeed consente 300 richieste ogni 5 minuti, 3,000 all’ora e 12,000 al giorno per chiave API. Se un altro strumento usa la stessa chiave, condividono questi limiti. Lightspeed chiede di contattarli per una seconda chiave.

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

Fonti

1. Lightspeed eCom (C-Series) Help Center: Adding a web tracking code
2. Lightspeed eCom (C-Series) Help Center: Creating API keys
3. Lightspeed eCom developers: Webhooks
4. Lightspeed eCom developers: Order
5. Lightspeed eCom developers: Rate limiting

In ROASaurus

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

Continua a leggere