Monitoraggio

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

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

Come Funziona #

Ogni ordine tracciato in Clerk passa attraverso una catena di tre elementi collegati.

Visitor ID #

Quando un visitatore arriva sul webshop, il 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 di un visitatore — i prodotti che ha visualizzato e cliccato — all’ordine che alla fine effettua.

In una configurazione Clerk.js, il visitor ID viene generato e gestito automaticamente. In una configurazione API diretta, sei tu responsabile di crearlo, memorizzarlo (ad esempio in una variabile di sessione) e passarlo in modo coerente in tutte le chiamate.

Etichette #

Ogni chiamata API che restituisce risultati — search matches, recommendations, email results — deve includere un parametro labels. Si tratta di un array contenente almeno una stringa descrittiva, ad esempio ["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 l’etichetta del click per tracciare la vendita all’elemento che l’ha generata. Questa è la base per l’attribuzione dei ricavi nelle analytics.

Etichette mancanti, identiche in tutti gli elementi o troppo generiche rendono impossibile per Clerk distinguere quale elemento ha influenzato una vendita. Questa è una delle cause più comuni per cui l’attribuzione sembra errata o manca completamente.

Chiamata di Vendita #

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

Affinché questa catena funzioni, ogni click su un prodotto mostrato da Clerk deve essere anch’esso 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 di Clerk — consulta la guida API per i dettagli.

Questa catena — etichetta → click → vendita — alimenta sia la personalizzazione che le revenue analytics in my.clerk.io.

Cosa Memorizza Clerk #

Ogni vendita tracciata contiene:

• Un ID di vendita univoco
• ID prodotto, quantità e prezzi unitari
• Il visitor ID (collega la vendita alla sessione)
• Email cliente e customer ID — opzionali, abilitano la personalizzazione cross-session

Configurazione #

Colloca la chiamata di tracciamento vendite nella pagina di conferma ordine, che si carica una sola volta dopo un acquisto effettuato con successo. Non inserirla nella pagina carrello o in altri punti del processo di checkout.

API #

Effettua una richiesta POST a log/sale dal tuo server quando un ordine viene completato. Passa 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 internamente per quantity quando calcola i ricavi. Non inviare il totale della riga.

Consulta la guida API per tutti i dettagli sulla generazione e la persistenza dei visitor ID durante una sessione.

Clerk.js #

Clerk.js gestisce automaticamente il visitor ID e effettua la chiamata log/sale per te. Aggiungi il seguente snippet nella tua pagina di conferma 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 di vendita alla API, utilizzando lo stesso visitor ID tracciato durante la sessione.

Verifica del Funzionamento #

Controlla queste tre sezioni dopo aver effettuato un ordine di prova.

Developers > Logs — Eventuali errori dalla chiamata di tracciamento compaiono qui in tempo reale. Questo è il modo più rapido per individuare una richiesta configurata male.

Data > Orders — Gli ordini tracciati e confermati compaiono qui. 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 prodotto nella chiamata di vendita non corrisponde a nessun prodotto nel tuo catalogo.

Data > Visitors — Cerca un visitor ID per ispezionare l’intera sessione: quali prodotti ha visto, su quali elementi Clerk ha cliccato e quali ordini ha effettuato. In una configurazione Clerk.js, puoi forzare uno specifico visitor ID durante i test aggiungendo ?clerk_visitor=VISITOR_ID a qualsiasi URL di pagina — Clerk.js utilizzerà quell’ID per la sessione, rendendo facile tracciare un intero 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 di recente.

Debug #

Segui questi passaggi quando le vendite non vengono tracciate correttamente.

Controlla i Log #

Vai su Developers > Logs e cerca eventuali errori dall’endpoint log/sale. Questo vale sia per configurazioni API che Clerk.js — ogni richiesta rifiutata compare immediatamente qui con un messaggio di errore che spiega il problema.

Per configurazioni Clerk.js, esegui anche Clerk("debug") nella console del browser prima di effettuare un ordine di prova. Si attiverà la modalità di debug, che farà sì che Clerk.js logghi informazioni dettagliate su ogni chiamata di tracciamento — compreso il visitor ID utilizzato, le etichette associate alle chiamate di risultato e ogni errore riscontrato. Cerca le voci con prefisso [Clerk] nell’output della console.

Verifica la Risposta dell’API #

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

{"status": "ok"}

Una risposta fallita restituisce un errore con una descrizione del problema, ad esempio:

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

Leggi il messaggio d’errore — di solito indica direttamente il problema.

Configurazione API: Registra la risposta HTTP grezza della chiamata log/sale nel tuo codice lato server. Se non lo fai già, testa la chiamata direttamente con un payload sicuramente 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 le chiamate in produzione no, confronta attentamente i due payload — la differenza farà emergere il problema.

Configurazione Clerk.js: Apri gli strumenti di sviluppo del browser, vai alla scheda Network e filtra per clerk. Effettua un ordine di prova e cerca una richiesta che inizi con sale?key=.... Selezionala e ispeziona la risposta.

Controlla i Parametri della Richiesta #

Se gli ordini non vengono tracciati o non vengono attribuiti correttamente, verifica quanto segue nella tua configurazione:

API key — Controlla che il campo key corrisponda alla Public API Key che trovi in Developers > API Keys. Una chiave errata dà immediatamente errore di autenticazione.

Visitor ID — Verifica che il campo visitor sia presente e che abbia lo stesso valore usato nelle chiamate di risultato precedenti nella sessione. Se generi un nuovo ID a ogni richiesta, o lo memorizzi in un luogo che viene azzerato prima del checkout, l’ID nella chiamata di vendita non corrisponderà a quello dei click.

Etichette — Conferma che ogni chiamata che restituisce risultati abbia incluso precedentemente un array labels con un’etichetta unica per ogni elemento. Se le etichette mancano o sono identiche tra gli elementi, Clerk registra comunque la vendita ma non può attribuirla a uno specifico elemento.

ID prodotto — Verifica che gli ID nell’array products coincidano con gli ID che Clerk ha nel suo catalogo. Cerca uno degli ID in Data > Products per conferma. Se non lo trovi, probabilmente stai inviando ID di varianti o SKU invece di ID prodotto principali.

Sale ID — Verifica che il campo sale sia univoco per ogni ordine e non venga riutilizzato in più richieste. Clerk ignora silenziosamente i sale ID duplicati.

Nessuna Chiamata Eseguita #

Configurazione API: La chiamata non parte dal tuo server. Controlla il gestore di completamento ordine — assicurati che venga effettivamente raggiunto dopo un acquisto riuscito e che nessuna eccezione sopprima la chiamata di tracciamento. Aggiungi log temporanei intorno alla chiamata log/sale per assicurarti che venga eseguita.

Configurazione Clerk.js: La libreria Clerk.js non è in esecuzione nella pagina di conferma. Apri la console del browser e digita Clerk. Se vedi questo errore, la libreria non è caricata:

Uncaught ReferenceError: Clerk is not defined

Controlla che lo script di tracciamento Clerk.js sia presente nel template della pagina di conferma e non sia bloccato da un altro script o da uno strumento di consenso cookie.

Nessun Impatto Clerk #

Se la chiamata di vendita va a buon fine ma nessun ordine risulta come influenzato da Clerk nelle analytics, Clerk ha registrato l’ordine ma non ha potuto collegarlo a una sessione o attribuirlo a un elemento.

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

Etichette mancanti o non valide — Verifica che ogni chiamata che restituisce risultati e ogni chiamata log/click includa un array labels valido. Se le etichette sono assenti, vuote o contengono solo spazi, Clerk non può determinare con quale elemento il visitatore abbia interagito e la vendita non verrà attribuita.

Configurazione API: Controlla che il visitor ID nella chiamata log/sale coincida esattamente con 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 — interrompe la connessione.

Configurazione Clerk.js: I visitor ID sono gestiti automaticamente, ma il collegamento può rompersi se lo script di tracciamento manca in una o più pagine del checkout. Assicurati che Clerk.js sia caricato in ogni pagina tra la pagina prodotto e quella di conferma.

Errori Comuni #

Queste sono le cause più frequenti per cui il tracciamento delle vendite fallisce o l’attribuzione non funziona correttamente.

Sintassi Prodotto Non Valida #

Gli ID prodotto devono essere inviati nello stesso formato utilizzato nel feed dati. Se lì usi gli interi, devono essere interi anche nella chiamata di vendita — non stringhe. Inviare "id": "123" quando Clerk si aspetta "id": 123 fa fallire la chiamata.

Il valore products deve anche essere JSON valido. Stringhe escape o doppiamente codificate come "products": "[{\"id\":\"123\"}]" non verranno lette correttamente.

Argomenti Mancanti #

I parametri key, sale e products sono tutti obbligatori. Ometterne uno restituisce errore. L’array products deve contenere almeno un elemento.

Clerk.js Non Caricato #

Se la libreria Clerk.js manca dalla pagina di conferma o viene bloccata, nessuna chiamata di vendita viene fatta. Due cause comuni:

• Lo script di tracciamento non è incluso nel template della pagina di conferma.
• Uno strumento di consenso cookie (ad esempio iubenda in modalità blocco automatico) blocca cdn.clerk.io o api.clerk.io. Inserisci entrambi i domini nella allowlist così il tracciamento non viene interrotto in caso di rifiuto dei cookie non essenziali da parte dei visitatori.

ID Prodotto Errati #

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

Cambiamento Visitor ID #

In una configurazione API, il visitor ID deve rimanere lo stesso dalla prima visualizzazione fino alla chiamata di vendita. Se lo rigeneri ad ogni caricamento di pagina, il click e la vendita saranno associati a sessioni diverse e Clerk non potrà collegarli.

In una configurazione Clerk.js questo è gestito automaticamente, ma può rompersi se lo script di tracciamento manca in una o più pagine del checkout.

Incoerenza Prezzo Unitario #

price nell’array products deve essere il prezzo unitario di un singolo articolo. Clerk lo moltiplica per quantity per calcolare il ricavo. Inviare un totale riga già moltiplicato produce dati gonfiati nei ricavi delle analytics.

Sale ID Riutilizzato #

Clerk memorizza solo la prima chiamata per un sale ID dato. Se la pagina di conferma ordine può essere aggiornata o rivista, la chiamata di tracciamento viene ripetuta con lo stesso sale ID. La seconda chiamata viene ignorata silenziosamente.

Usa un flag lato server o un marcatore di sessione per assicurarti che la chiamata parta una sola volta per ordine.

Dati Visitatore Mancanti #

Se né visitor né email sono inclusi nella chiamata di vendita, Clerk registra l’ordine ma non può associarlo a una sessione o a un profilo cliente. L’ordine appare in Data > Orders ma non mostra mai impatti nelle analytics come influenzato da Clerk.

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

Disattivare il Tracciamento Visitatore #

Per interrompere il tracciamento per uno specifico visitatore — ad esempio quando questo ha rifiutato ogni tracciamento tramite un banner cookie — passa "visitor": null in tutte le chiamate API di quella sessione. Clerk elabora comunque le richieste normalmente ma non registra attività su alcun profilo visitatore.

In una configurazione Clerk.js, imposta questo nel config:

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

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