Monitoraggio delle vendite

Il tracciamento delle vendite è il collegamento tra ciò che Clerk mostra ai visitatori e gli ordini che essi effettuano. Senza di esso, Clerk non può apprendere dagli acquisti reali, personalizzare le recommendations o mostrare un’attribuzione accurata dei ricavi nella dashboard.

Questo articolo spiega come funziona il tracciamento a livello di API, come configurarlo e come eseguirne il debug quando gli ordini non vengono registrati correttamente.

Come Funziona #

Ogni ordine tracciato in Clerk passa attraverso una catena di tre componenti connesse.

Visitor ID #

Quando un visitatore arriva sul webshop, il tuo server genera un ID di sessione anonimo e lo include in ogni chiamata API effettuata durante quella sessione. Questo permette a Clerk di collegare l’attività di navigazione del visitatore — i prodotti che ha visto e su cui ha cliccato — all’ordine che infine effettua.

In una configurazione Clerk.js, il visitor ID viene generato e gestito automaticamente. In una configurazione API diretta, sei tu a doverlo creare, memorizzare (ad esempio in una variabile di sessione) e a trasmetterlo coerentemente in tutte le chiamate.

Labels #

Ogni chiamata API che restituisce risultati — risultati di search, recommendations, email — deve includere un parametro labels. Si tratta di un array contenente almeno una stringa descrittiva, come ["Homepage - Trending"] o ["Search - Predictive"], che identifica quale elemento ha mostrato quei prodotti.

Quando un visitatore clicca su un prodotto e successivamente effettua un ordine, Clerk utilizza la label dal click per risalire alla vendita fino all’elemento che l’ha generata. Questa è la base per l’attribuzione dei ricavi in analytics.

Labels mancanti, identiche su tutti gli elementi, o troppo generiche rendono impossibile per Clerk distinguere quale elemento ha influenzato la vendita. Questa è una delle cause più comuni per cui l’attribuzione risulta errata o manca del tutto.

Sale Call #

Quando il visitatore effettua un ordine, una richiesta POST a log/sale lega l’ordine al visitor ID. Clerk può ora collegare l’intera catena: questo visitatore ha visto i prodotti tramite l’elemento X (la label), ne ha cliccato uno e ha completato un acquisto.

Affinché questa catena funzioni, ogni click su un prodotto mostrato da Clerk deve anche essere registrato tramite log/click. In una configurazione Clerk.js ciò avviene automaticamente. In una configurazione API, devi chiamare log/click ogni volta che un visitatore clicca su un prodotto Clerk — vedi la guida API per i dettagli.

Questa catena — label → click → sale — alimenta sia la personalizzazione che le analytics dei ricavi in my.clerk.io.

Cosa viene memorizzato da Clerk #

Ogni vendita tracciata contiene:

• Un sale ID univoco
• ID prodotto, quantità e prezzo unitario
• Il visitor ID (lega la vendita alla sessione)
• Email cliente e customer ID — opzionali, abilitano la personalizzazione inter-sessione

Configurazione #

Inserisci la chiamata di tracciamento vendite nella pagina di conferma ordine, che viene caricata una sola volta dopo un acquisto andato a buon fine. Non inserirla nella pagina del carrello né in altri punti del flusso di checkout.

API #

Esegui una richiesta POST a log/sale dal tuo server quando un ordine è completato. Trasmetti lo stesso visitor ID usato durante tutta la sessione.

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_PUBLIC_API_KEY",
    "sale": 567,
    "products": [
      {"id": 12793, "price": 99.95, "quantity": 2},
      {"id": 1546, "price": 14.00, "quantity": 1}
    ],
    "email": "luke@skywalker.com",
    "customer": 1234,
    "visitor": "abc123"
  }' \
  https://api.clerk.io/v2/log/sale

price è sempre il prezzo unitario di un singolo articolo. Clerk lo moltiplica per quantity internamente quando calcola i ricavi. Non inviare il totale della riga.

Consulta la guida API per dettagli completi su come generare e mantenere il visitor ID per tutta la sessione.

Clerk.js #

Clerk.js gestisce automaticamente il visitor ID ed effettua per te la chiamata log/sale. Aggiungi il seguente snippet nella pagina di conferma d’ordine e sostituisci i valori segnaposto con le variabili della tua piattaforma:

<span
  class="clerk"
  data-api="log/sale"
  data-sale="ORDER_ID"
  data-email="CUSTOMER_EMAIL"
  data-customer="CUSTOMER_ID"
  data-products='[{"id": 12, "quantity": 1, "price": 99.95}, {"id": 54, "quantity": 2, "price": 9.50}]'>
</span>

Clerk.js rileva lo snippet al caricamento della pagina e invia i dati della vendita all’API, utilizzando lo stesso visitor ID tracciato per tutta la sessione.

Verifica del Funzionamento #

Controlla questi tre punti dopo aver effettuato un ordine di test.

Developers > Logs — Qui appaiono in tempo reale eventuali errori dalla chiamata di tracciamento. È il punto più rapido per individuare una richiesta configurata male.

Data > Orders — Qui appaiono gli ordini tracciati confermati. Clicca su un ordine per vedere quali prodotti sono stati tracciati e se Clerk riesce a identificarli. Se un prodotto mostra un’immagine segnaposto, l’ID del prodotto nella chiamata di vendita non corrisponde ad alcun prodotto nel tuo catalogo.

Data > Visitors — Cerca un visitor ID per ispezionare l’intera sessione: quali prodotti ha visualizzato, su quali elementi Clerk ha cliccato e quali ordini ha effettuato. In una configurazione Clerk.js puoi forzare un visitor ID specifico durante i test aggiungendo ?clerk_visitor=VISITOR_ID a qualsiasi URL della pagina — Clerk.js userà quell’ID per la sessione, rendendo facile tracciare tutto il flusso di test dall’inizio alla fine.

La dashboard Health mostra un indicatore di stato di alto livello per il tracciamento delle vendite. Uno stato rosso significa che non sono stati ricevuti ordini tracciati recentemente.

Debug #

Segui questi passaggi quando le vendite non vengono tracciate correttamente.

Controlla i Log #

Vai su Developers > Logs e cerca eventuali errori provenienti dall’endpoint log/sale. Questo vale sia per configurazioni API sia Clerk.js — qualsiasi richiesta rifiutata appare qui immediatamente con un messaggio di errore esplicativo.

Per configurazioni Clerk.js, esegui anche Clerk("debug") nella console del browser prima di effettuare un ordine di test. Questo attiva la modalità debug e fa sì che Clerk.js registri in console dettagli su ogni chiamata di tracciamento — incluso il visitor ID utilizzato, le labels associate alle chiamate di risultato ed eventuali errori riscontrati. Cerca le voci che iniziano con [Clerk] nell’output della console.

Verifica la Risposta API #

L’endpoint log/sale restituisce sempre una risposta. Una risposta di successo appare così:

{"status": "ok"}

Una risposta di errore restituisce una descrizione del problema, ad esempio:

{"status": "error", "error": "Missing required argument: sale"}

Leggi il messaggio di errore — solitamente indica direttamente il problema.

Configurazione API: Registra la risposta HTTP grezza della chiamata log/sale nel codice lato server. Se non lo fai già, testa la chiamata direttamente con un payload noto e valido:

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_PUBLIC_API_KEY",
    "sale": 999,
    "products": [{"id": 12793, "price": 99.95, "quantity": 1}],
    "visitor": "test-visitor-1"
  }' \
  https://api.clerk.io/v2/log/sale

Se questa ha successo ma quelle in produzione no, confronta attentamente i due payload — la differenza rivelerà il problema.

Configurazione Clerk.js: Apri DevTools del browser, vai nella scheda Network e filtra per clerk. Effettua un ordine di prova e cerca una richiesta che inizia con sale?key=.... Cliccaci sopra e controlla la risposta.

Controlla i Parametri della Richiesta #

Se gli ordini non vengono tracciati o attribuiti correttamente, verifica i seguenti aspetti nella tua configurazione:

API key — Controlla che key corrisponda alla Public API Key trovata su Developers > API Keys. Un’API key errata genera subito un errore di autenticazione.

Visitor ID — Controlla che visitor sia presente e sia lo stesso valore usato nelle chiamate di risultato precedenti nella sessione. Se generi un nuovo ID ad ogni richiesta, o lo memorizzi in una posizione che viene cancellata prima del checkout, l’ID nella call di vendita non corrisponderà a quello collegato ai click.

Labels — Assicurati che ogni chiamata di risultato precedente nella sessione includesse un array labels con una label unica per ogni elemento. Se le labels sono mancanti o identiche tra gli elementi, Clerk registra la vendita ma non può attribuirla ad alcun elemento specifico.

Product IDs — Verifica che gli ID nell’array products corrispondano agli ID che Clerk ha nel suo catalogo. Cerca uno degli ID in Data > Products per esserne sicuro. Se non lo trovi, probabilmente stai inviando ID variante o SKU invece degli ID prodotto padre.

Sale ID — Assicurati che il valore sale sia univoco per ogni ordine e che non venga riutilizzato tra più richieste. Clerk ignora silenziosamente sale ID duplicati.

Nessuna Chiamata Effettuata #

Configurazione API: La chiamata non parte dal server. Controlla il gestore di completamento ordine — verifica che venga effettivamente raggiunto dopo un acquisto riuscito e che nessuna eccezione stia silenziosamente annullando la chiamata di tracciamento. Aggiungi del logging temporaneo attorno alla chiamata log/sale per assicurarti che venga eseguita.

Configurazione Clerk.js: La libreria Clerk.js non è in esecuzione sulla pagina di conferma. Apri la console del browser e digita Clerk. Se compare il seguente errore, la libreria non è stata caricata:

Uncaught ReferenceError: Clerk is not defined

Verifica che lo script di tracking Clerk.js sia presente nel template della pagina di conferma e che non sia bloccato da altri script o strumenti di consenso cookie.

Nessun Impatto Clerk #

Se la chiamata di vendita ha successo ma nessun ordine compare come influenzato da Clerk nelle analytics, Clerk ha registrato l’ordine ma non è riuscito ad associarlo a una sessione o ad attribuirlo a un elemento.

log/click non chiamato — La causa più comune. Clerk non può attribuire una vendita a un elemento se non è stato registrato un click prima dell’acquisto. In una configurazione Clerk.js il tracciamento click è automatico — verifica che la libreria sia caricata nelle pagine in cui vengono mostrati i risultati Clerk. In una configurazione API, controlla che il tuo codice chiami log/click ogni volta che un visitatore clicca su un prodotto mostrato da Clerk e che la chiamata raggiunga effettivamente l’API (controlla i log server o la risposta).

Labels mancanti o non valide — Verifica che ogni chiamata di risultato e ogni chiamata log/click includano un array labels valido. Se le labels sono mancanti, vuote o contengono solo spazi bianchi, Clerk non può determinare con quale elemento il visitatore ha interagito e la vendita non verrà attribuita.

Configurazione API: Controlla che il visitor ID nella chiamata log/sale corrisponda esattamente a quello inviato nella chiamata log/click quando il visitatore ha cliccato il prodotto. Anche una piccola differenza — formato diverso, carattere in più o un ID rigenerato — rompe il collegamento.

Configurazione Clerk.js: I visitor ID sono gestiti automaticamente, ma il collegamento può rompersi se lo script di tracking è assente da una o più pagine del flusso di checkout. Controlla che Clerk.js sia caricato su ogni pagina tra la pagina prodotto e la pagina di conferma.

Errori Comuni #

Questi sono i motivi più frequenti per cui il tracciamento delle vendite fallisce o l’attribuzione non funziona correttamente.

Sintassi Prodotto Non Valida #

I product ID devono essere inviati come lo stesso tipo usato nel tuo data feed. Se lì usi interi, devono essere interi anche nella chiamata di vendita — non stringhe. Inviare "id": "123" quando Clerk si aspetta "id": 123 farà fallire la chiamata.

Il valore products deve anche essere JSON valido. Stringhe escaped o doppio-encode come "products": "[{\"id\":\"123\"}]" non verranno lette correttamente.

Argomenti Mancanti #

Gli argomenti key, sale e products sono tutti obbligatori. Ometterne uno comporta un errore. L’array products deve contenere almeno un elemento.

Clerk.js Non Caricato #

Se la libreria Clerk.js non è presente nella pagina di conferma, o è bloccata, non viene effettuata alcuna chiamata di vendita. Due cause comuni:

• Lo script di tracking non è incluso nel template della pagina di conferma.
• Uno strumento di consenso cookie (come iubenda in modalità blocco automatico) sta bloccando cdn.clerk.io o api.clerk.io. Inserisci entrambi i domini nella allowlist per evitare che il tracciamento venga silenziosamente interrotto quando i visitatori rifiutano i cookie non essenziali.

Product ID Sbagliati #

Traccia l’ID del prodotto padre, non quello variante. Se un visitatore acquista una t-shirt rossa, taglia M, traccia l’ID padre — non l’ID della variante specifica. Lo stesso ID deve essere usato sia nel tracciamento click che nella chiamata di vendita. ID non corrispondenti rompono l’attribuzione anche se entrambe le chiamate vanno a buon fine.

Cambiamenti del Visitor ID #

In una configurazione API, il visitor ID deve restare invariato dalla prima visualizzazione fino alla chiamata di vendita. Se rigeneri l’ID a ogni caricamento pagina, click e vendita vengono associati a sessioni diverse e Clerk non può collegarli.

In una configurazione Clerk.js questo avviene automaticamente, ma può rompersi se lo script di tracking manca da una o più pagine del flusso di checkout.

Mismatch Prezzo Unitario #

price nell’array products deve essere il prezzo unitario di un singolo articolo. Clerk lo moltiplica per quantity per calcolare i ricavi. Inviare un totale di riga già moltiplicato genera valori di ricavo gonfiati nelle analytics.

Sale ID Riutilizzati #

Clerk memorizza solo la prima chiamata per un sale ID specifico. Se la pagina di conferma ordine può essere ricaricata o rivisitata, la chiamata viene effettuata nuovamente con lo stesso sale ID. La seconda chiamata viene ignorata silenziosamente.

Utilizza un flag lato server o un marcatore di sessione per assicurarti che la chiamata di tracciamento venga effettuata una sola volta per ogni ordine.

Dati Visitatore Mancanti #

Se né visitor né email vengono inclusi nella chiamata di vendita, Clerk registra l’ordine ma non può collegarlo a una sessione o a un profilo cliente. L’ordine appare su Data > Orders ma non risulta mai influenzato da Clerk nelle analytics.

Includi sempre il parametro visitor. Aggiungere anche email e customer quando disponibili migliora la personalizzazione delle sessioni future per quel cliente.

Disabilitare il Tracciamento Visitatore #

Per interrompere il tracciamento per un visitatore specifico — ad esempio, se rifiuta tutti i tracciamenti tramite un banner di consenso cookie — passa "visitor": null in tutte le chiamate API per quella sessione. Clerk elabora normalmente le richieste ma non registra alcuna attività sul profilo visitatore.

In una configurazione Clerk.js, impostalo invece nella config:

Clerk('config', {
  key: 'YOUR_API_KEY',
  visitor: null
});

Le vendite vengono comunque registrate anche se il tracciamento visitatore è disabilitato. Clerk riceve i dati dell’ordine e li include nelle analytics, ma senza alcun contesto di sessione — nessuna cronologia click, nessun prodotto visualizzato, nessuna attribuzione elementi. Clerk sa solo cosa è stato acquistato, non come il visitatore è arrivato lì.