Tracciamento del commercio elettronico

Questa guida descrive come integrare manualmente il tracking e-commerce di Trackboxx in un negozio, indipendentemente dal fatto che si utilizzi un sistema personalizzato, Shopify, Shopware, Magento o un altro negozio. Per WooCommerce è disponibile un plugin ufficiale che attiva automaticamente tutti gli eventi qui descritti.

Logica di base: che cosa significa trackboxx('Purchase', [...])?

Prima di passare ai singoli eventi, è importante capire un punto che, secondo l'esperienza, viene interpretato molto spesso in modo errato:

Importante: trackboxx('Purchase', [...]) non è un singolo evento, ma la chiamata generica per tutte le interazioni di e-commerce. Il primo oggetto dell'array determina quale evento viene tracciato tramite il suo campo type:

• { type: 'ViewProduct' } - Pagina di dettaglio del prodotto
• { type: 'AddToCart' } - Prodotto aggiunto al carrello
• { type: 'ViewCart' } - Visualizza la pagina del carrello
• { type: 'order' } - Ordine completato

Il 'Purchase' nella chiamata di funzione indica soltanto la categoria di azione “e-commerce” e rimane invariato, sia che tu stia tracciando una visualizzazione del prodotto, un'aggiunta al carrello o un acquisto effettivo.

I quattro eventi di e-commerce in sintesi

1. ViewProduct – Pagina di dettaglio del prodotto

Innesco: Quando si richiama la pagina di dettaglio di un prodotto.
Dati minimi: Nome del prodotto e prezzo unitario.

<script>
trackboxx('Purchase', [
  { type: 'ViewProduct' },
  { type: 'product', name: '%%PRODUCT_NAME%%', price: 99.90 }
]);
</script>Lingua del codice: HTML, XML (xml)

Note:

• price = Prezzo unitario del prodotto (numerico, punto come separatore decimale).
• Campi aggiuntivi facoltativi: sku, category.
• Per le varianti o i pacchetti, trasmetti il nome completo della variante con i suoi attributi (ad esempio “T-shirt — rosso, L”), affinché i report siano aggregati in modo coerente.

2. AddToCart – Prodotto aggiunto al carrello

Attivazione: Dopo il completamento riuscito dell'azione “Aggiungi al carrello”, non al semplice clic.
Dati minimi: Nome del prodotto e prezzo unitario.

<script>
trackboxx('Purchase', [
  { type: 'AddToCart' },
  { type: 'product', name: '%%PRODUCT_NAME%%', price: 19.99 }
]);
</script>Lingua del codice: HTML, XML (xml)

Note sulla tempistica - a seconda del tipo di negozio:

• Negozi personalizzati e cestini della spesa AJAX: L'evento viene generato nel callback di successo dell'azione Aggiungi al carrello, non nel gestore del clic. Ciò significa che non viene generato alcun evento di tracciamento se l'articolo non finisce nel carrello a causa di controlli di magazzino, errori di convalida o di rete.
• Negozi lato server con redirect: Attivare l'evento una volta nella pagina seguente dopo un'aggiunta riuscita.
• Integrazioni semplici con un clic: consentite, ma solo se il clic porta effettivamente a un'aggiunta riuscita, ad esempio verificando che il pulsante sia disabilitato per i prodotti esauriti.
• Deduplicazione: Inviare AddToCart una sola volta per azione, senza duplicazioni per il ricaricamento o la navigazione a ritroso.

3. ViewCart – Pagina del carrello

Innesco: Quando si richiama la pagina del carrello.
Dati minimi: Totale carrello (amount). Opzionale: tutti i prodotti inclusi come oggetti separati.

<script>
trackboxx('Purchase', [
  { type: 'ViewCart' },
  { type: 'cart', amount: 149.70 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Lingua del codice: HTML, XML (xml)

Note:

• amount = importo totale del carrello. Standard: netto (corrisponde al comportamento del plugin ufficiale di WooCommerce).
• Se il tuo negozio utilizza prezzi lordi, sono ammessi anche i valori lordi. È essenziale la coerenza all'interno di un evento: cart.amount e tutti i valori product.price devono essere calcolati sulla stessa base, tutti al netto oppure tutti al lordo.
• Aggiungi un oggetto product separato per ogni riga del carrello.
• Il valore price per prodotto corrisponde qui al totale della riga (prezzo unitario × quantità); vedi la sezione “Logica dei prezzi e quantità”.

4. Purchase – Completamento dell'ordine (pagina di ringraziamento)

Innesco: Nella pagina di conferma dell'ordine dopo l'esito positivo del pagamento - esattamente una volta per ordine.
Dati minimi: ID ordine, importo totale, tutti i prodotti acquistati.

<script>
trackboxx('Purchase', [
  { type: 'order', id: 'ORDER_ID', total: 149.70 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Lingua del codice: HTML, XML (xml)

Opzionale — con buono sconto: Aggiungi un oggetto coupon per ogni buono utilizzato.

<script>
trackboxx('Purchase', [
  { type: 'order', id: '12345', total: 149.70 },
  { type: 'coupon', name: 'SUMMER10', discount: 10.00 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Lingua del codice: HTML, XML (xml)

Note:

• L'evento Purchase non ha un marcatore di evento iniziale come ViewProduct o AddToCart: è l'oggetto order a identificare l'evento stesso.
• order.id = ID unico dell'ordine dal sistema del negozio.
• order.total = valore totale dell'ordine (si consiglia l'importo finale lordo comprensivo di spese di spedizione e tasse, ma deve essere coerente con i valori di product.price).
• product.price = Totale articolo (prezzo unitario × quantità), non prezzo unitario.
• Evita attivazioni ripetute in caso di ricaricamento, ad esempio tramite un flag lato server o un marcatore di sessione.

Logica di prezzo e quantità

Trackboxx non utilizza un campo quantity separato. Le quantità sono rappresentate implicitamente dal prezzo. Questa regola è vincolante e va applicata allo stesso modo in ogni integrazione:

Esempio: Tre articoli identici da 19,99 € ciascuno nel carrello vengono inviati per ViewCart e Purchase come un unico oggetto product con price: 59.97, non come tre oggetti separati e senza un campo quantity.

Sequenza di oggetti nell'array

Per un'integrazione pulita e coerente, si consiglia la seguente sequenza di oggetti:

1. Marcatore di evento oppure oggetto order (ViewProduct / AddToCart / ViewCart / order)
2. Oggetto cart (solo per ViewCart)
3. Oggetti coupon (solo per Purchase, se presenti)
4. Oggetti product

Best Practice

• Deduplicazione: Invia ogni evento una sola volta per ogni azione effettiva: evita il doppio tracciamento in caso di ricaricamento, navigazione indietro o nuovi tentativi AJAX.
• Momento di attivazione: Attiva ViewProduct e ViewCart al caricamento della pagina, AddToCart dopo la conferma dell'aggiunta al carrello e Purchase una sola volta nella pagina di ringraziamento.
• Prezzi e importi: Trasmettili come Number, non come stringa, con un punto come separatore decimale (ad esempio 19.99, non "19,99").
• Coerenza: Scegli valori netti o lordi per il tuo negozio e applica la stessa scelta a cart.amount, product.price e order.total.
• Protezione dei dati: Non trasmettere mai dati personali: niente indirizzi e-mail, nomi, numeri cliente o indirizzi. Rispetta il consenso.

Lista di controllo rapida per sistema di negozio

• WooCommerce: Utilizzare il plugin ufficiale Trackboxx. Innesca tutti e quattro gli eventi (ViewProduct, AddToCart, ViewCart, Purchase) automaticamente, senza necessità di integrazione manuale.
• Negozi personalizzati: Sul lato server, inserire il nome del prodotto, il prezzo e il totale come variabili nei rispettivi script inline.
• Shopify: Inserisci gli snippet nei template (product.liquid, cart.liquid, pagina di ringraziamento dopo il checkout). Per AddToCart, usa il callback di successo AJAX.
• Shopware / Magento: Collegati agli eventi o agli hook corrispondenti nel tema o nel plugin: pagina del prodotto, pagina del carrello, evento di aggiunta al carrello ed evento di completamento dell'ordine.

Riferimento: Varianti minimali

ViewProduct (minimo)

trackboxx('Purchase', [
  { type: 'ViewProduct' },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Lingua del codice: JavaScript (javascript)

AddToCart (minimo)

trackboxx('Purchase', [
  { type: 'AddToCart' },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Lingua del codice: JavaScript (javascript)

ViewCart (minimo)

trackboxx('Purchase', [
  { type: 'ViewCart' },
  { type: 'cart', amount: 19.99 }
]);Lingua del codice: JavaScript (javascript)

Purchase (minimo)

trackboxx('Purchase', [
  { type: 'order', id: 'ORDER_ID', total: 19.99 },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Lingua del codice: JavaScript (javascript)

Breve panoramica: Le regole più importanti

• trackboxx('Purchase', [...]) è una chiamata e-commerce generica, non un evento.
• Il tipo di evento si trova nel payload, nel campo type del primo oggetto, non nella chiamata di funzione.
• Attiva AddToCart dopo un'aggiunta al carrello andata a buon fine, non al semplice clic.
• cart.amount è un valore netto per impostazione predefinita; sono ammessi valori lordi, purché coerenti all'interno dell'evento.
• price corrisponde al prezzo unitario per ViewProduct e AddToCart, e al totale della riga per ViewCart e Purchase.
• Nessun campo quantity separato: le quantità sono rappresentate dal prezzo.
• L'evento Purchase si basa su { type: 'order' }, senza un marcatore di evento iniziale.
• Trasmetti i prezzi come Number con un punto come separatore decimale, mai come String.
• Nessun dato personale nel payload.