Collegamento del sito
Il tracker è un piccolo script inserito nelle pagine del Suo sito. Conta le visualizzazioni di pagina, trasmette le azioni dei clienti (visualizzazione di un prodotto, carrello, ordine, accesso), mostra i widget di raccomandazione e iscrive i visitatori al Web Push. Tutto ciò che serve per il collegamento si trova nella pagina Sito → Collegamento, mentre il Web Push si configura nella pagina Sito → Web Push.
La sezione è aperta a tutti i membri del progetto. Domini del sito e widget possono essere modificati da «Proprietario», «Amministratore» e «Manager». Possono creare una chiave per il sito il «Proprietario» e l'«Amministratore».
Installazione del tracker
Nella scheda Installazione ci sono tre passaggi.
1. Codice per ogni pagina
- Nel campo Chiave di scrittura scelga una chiave. Se non ci sono chiavi, faccia clic su Crea una chiave per il sito web.
- Copi il codice con il pulsante di copia.
- Lo inserisca nel
<head>di tutte le pagine del sito, di solito nel modello comune dell'intestazione.
Il codice ha questo aspetto (nella sezione indirizzo e chiave sono già inseriti):
<script>
!function(w,d,u){var c=w.cdp=w.cdp||[];if(c.version)return;['init','page','track','identify','alias','reset','setLanguage','widgets','renderRecommendations'].forEach(function(m){c[m]=c[m]||function(){c.push([m].concat([].slice.call(arguments)))}});var s=d.createElement('script');s.async=1;s.src=u;d.head.appendChild(s)}(window,document,'https://cdp.onetrace.pro/tracker/cdp.js');
cdp.init('cdp_wk_…', { host: 'https://cdp.onetrace.pro' });
cdp.page();
</script>
Lo script viene caricato in modo asincrono e non rallenta il sito. Le chiamate a cdp.track() si possono fare subito dopo il codice: attenderanno il caricamento del tracker. A ogni browser il tracker assegna un identificatore permanente del visitatore (cookie cdp_aid di durata annuale) e salva i parametri UTM della visita.
La chiave di scrittura è visibile nel codice delle pagine, ed è normale: può solo inviare eventi. Se nell'elenco le chiavi non sono disponibili, sono state create prima dell'introduzione della sezione e non possono essere mostrate per intero. Crei una nuova chiave per il sito o usi la chiave del codice già installato sul sito.
![]()
2. Verifica
Dopo l'installazione apra una pagina qualsiasi del sito. Dopo qualche secondo, nel blocco Verifica compare una tabella: Dominio, Eventi in 7 giorni e ora dell'ultimo evento. Finché non ci sono eventi, la sezione mostra «In attesa dei primi eventi». La verifica si aggiorna da sola ogni 10 secondi finché la sezione è aperta.
3. Domini del sito web
Per impedire a un sito altrui di inviare eventi a nome del Suo progetto e di prelevare le raccomandazioni, indichi i domini del Suo sito:
- Inserisca il dominio, ad esempio
shop.example.com, e faccia clic su +. Un dominio della tabella di verifica si aggiunge con il pulsante Aggiungi ai domini. - Faccia clic su Salva.
Un dominio autorizza anche i propri sottodomini: shop.ru consente www.shop.ru. Finché l'elenco è vuoto, la chiave funziona su qualsiasi sito («Nessuna restrizione»). Le richieste dal Suo server non sono soggette a questa limitazione. Si possono indicare fino a 20 domini.
App a pagina singola (SPA e PWA)
Nelle app con React, Vue, Angular e simili la pagina non si ricarica, quindi le visualizzazioni le invia l'app: chiami cdp.page() dopo ogni cambio di schermata, ma non due volte per il primo caricamento: l'ha già inviato il codice di installazione. Se l'hook del router si attiva anche al primo caricamento (afterEach in Vue Router, useEffect in React), tolga invece cdp.page() dal codice di installazione: un esempio è nella scheda Installazione.
// dopo ogni cambio di schermata, quando il router ha già aggiornato l'indirizzo
cdp.page();
// una schermata senza indirizzo proprio, o l'indirizzo non è ancora cambiato
cdp.page('Carrello', { path: '/cart', title: 'Carrello' });
Se una schermata non ha un indirizzo proprio (una finestra modale, un passaggio del checkout, una PWA senza indirizzi) o il router cambia l'indirizzo più tardi, passi la pagina esplicitamente: path o url (anche relativo) e il titolo. Questa pagina finisce nella visualizzazione e nel contesto degli eventi successivi, ad esempio un'aggiunta al carrello viene legata alla schermata del carrello, fino alla successiva chiamata di cdp.page(). Il tracker considera la schermata precedente come referrer della seconda e delle successive e conserva i parametri UTM della visita fino alla chiusura della scheda.
Accesso e uscita del cliente
Dopo l'accesso o la registrazione, chiami cdp.identify() con l'id dell'utente nel Suo sistema: la cronologia delle visite verrà collegata al profilo del cliente:
cdp.identify('user-42', { email: '[email protected]' });
Trasmetta lo User ID solo per gli utenti che hanno effettuato l'accesso e non usi valori comuni come 0 o guest: i profili con lo stesso User ID verranno uniti. All'uscita dall'account chiami cdp.reset(), così la persona successiva allo stesso computer riceverà un nuovo identificatore.
La tabella Identificazione del cliente nella scheda Eventi dei prodotti mostra quali identificatori servono a ciascun canale e come arrivano nel profilo: email per le campagne email, phone in formato internazionale per SMS, WhatsApp e Viber per numero, e per i bot Telegram e Viber il collegamento della chat tramite un link creato dal Suo server. Passi tutto ciò che sa del cliente: più identificatori ci sono, più canali sono disponibili.
Firma dell'accesso
Il codice del tracker con la chiave di scrittura è visibile a tutti: senza verifica, qualsiasi visitatore può chiamare cdp.identify() con lo User ID di un'altra persona. Il suo browser verrebbe collegato al profilo di un altro cliente: consigli, messaggi sul sito e bot della chat mostrerebbero dati altrui, e un'iscrizione alle notifiche riceverebbe le notifiche di un altro. La firma dell'accesso lo impedisce: il server del Suo sito firma lo User ID del cliente che ha effettuato l'accesso e OneTrace.pro verifica la firma.
-
Apra Sito → Collegamento, la scheda Server, e faccia clic su Crea chiave di firma. La chiave viene mostrata una sola volta: la salvi nella variabile d'ambiente del server
CDP_IDENTITY_KEYe non la inserisca nel codice delle pagine. -
Sul server del Suo sito calcoli la firma — HMAC-SHA256 dello User ID con questa chiave — e la passi al tracker come terzo argomento di
cdp.identify():<?php $userHash = hash_hmac('sha256', (string) $user->id, getenv('CDP_IDENTITY_KEY')); ?> <script>cdp.identify(<?= json_encode((string) $user->id) ?>, {}, { userHash: <?= json_encode($userHash) ?> });</script>Trova esempi in Go, Node.js e Python nella stessa scheda. Il tracker ricorda la firma e la invia con gli eventi, i messaggi della chat, i moduli e l'iscrizione alle notifiche.
-
Segua i contatori della scheda Firma dell'accesso: quanti messaggi con User ID sono arrivati nelle ultime 24 ore con e senza firma. Quando non arrivano più messaggi senza firma, attivi Richiedi la firma. Da quel momento uno User ID senza firma valida non viene accettato e queste visite restano anonime.
Plugin e librerie inviano la firma da soli quando hanno la chiave di firma (le impostazioni dei plugin sono in inglese):
- WooCommerce 1.15 o successivo: WooCommerce → Settings → OneTrace.pro → Identity key, oppure la costante
ONETRACE_IDENTITY_KEYinwp-config.php; - Magento 2 1.12 o successivo: Stores → Configuration → OneTrace.pro → Connection → Identity key;
- 1C-Bitrix 1.11 o successivo: Identity key nella scheda del sito delle impostazioni del modulo OneTrace.pro;
- pacchetto Laravel 1.14 o successivo: la variabile
ONETRACE_IDENTITY_KEY; PHP SDK 1.17 o successivo: l'opzioneidentity_keye il metodouserHash(); - app mobili con SDK 1.1 o successivo: il server della sua app calcola la firma dopo l'accesso e l'app la passa a
identifyinsieme allo User ID.
Attivi la firma obbligatoria quando sito e app sono aggiornati e il contatore dei messaggi senza firma mostra zero. Un server che invia eventi con la chiave segreta non deve inviare la firma.
Può cambiare la chiave con Cambia chiave: quella precedente viene accettata ancora per 24 ore; la sostituisca sul sito e nelle app in questo intervallo. Possono creare e cambiare la chiave e attivare la firma obbligatoria il Proprietario e l'Amministratore.
Lingua del cliente
Il tracker invia la lingua del browser, che viene salvata nel profilo del cliente (l'attributo language) finché la lingua non viene impostata esplicitamente. In base a questa lingua i percorsi e le campagne scelgono la versione linguistica del modello. Le lingue del progetto sono visibili nel blocco Lingua del cliente della scheda Installazione.
Se il sito ha un selettore di lingua, comunichi la scelta del visitatore: viene ricordata e salvata nel profilo:
cdp.setLanguage('de');
Un'altra fonte della lingua si imposta all'inizializzazione: language: 'page' — l'attributo lang di <html>, un codice lingua — una lingua per tutto il sito, false — non inviare la lingua. Una lingua nota nel Suo sistema si può passare come attributo: cdp.identify('user-42', { language: 'de' }).
Eventi dei prodotti
La scheda Eventi dei prodotti mostra le chiamate pronte per cinque azioni: Visualizzazione prodotto, Aggiunta al carrello, Ordine, Preferiti e Accesso e registrazione. I nomi degli eventi e la proprietà con l'id del prodotto (per impostazione predefinita product_id) vengono presi dalle impostazioni della sezione Raccomandazioni. Se lì non sono stati scelti gli eventi, vedrà un avviso e negli esempi compariranno i nomi predefiniti: product_viewed, add_to_cart, order_completed.
Esempio di ordine, con tutti i prodotti trasmessi nell'array products:
cdp.track('order_completed', {
order_id: 'A-1001',
amount: 9980,
products: [{ product_id: 'SKU-1', quantity: 2, price: 4990 }],
});
Preferiti è facoltativo: gli eventi add_to_wishlist e remove_from_wishlist servono ai percorsi che annunciano ribassi di prezzo e il ritorno disponibile dei prodotti preferiti. Chiami cdp.addToWishlist('SKU-1') e cdp.removeFromWishlist('SKU-1') oppure faccia a meno del codice: aggiunga al pulsante l’attributo data-cdp-wishlist="SKU-1" (aggiungere) o data-cdp-wishlist-remove="SKU-1" (rimuovere) e il tracker invierà l’evento al clic.
Domande sul prodotto: <div data-cdp-ask data-product-id="SKU-1"></div> nella pagina del prodotto è il blocco in cui il cliente fa domande sul prodotto all'IA, veda Domande sul prodotto.
Ogni passaggio ha un'indicazione: quanti eventi sono arrivati negli ultimi 7 giorni e quando l'ultimo, oppure «Nessun evento in 7 giorni». Così si vede quali chiamate non funzionano ancora. L'id del prodotto deve coincidere con l'id nel catalogo prodotti.
![]()
Ordini e registrazioni è più affidabile inviarli dal Suo server: vedi Integrazione lato server.
Link di invito
Se nel programma fedeltà sono attivi gli inviti, ogni membro ha un link al Suo sito con il parametro ?ref=CODICE. Il tracker rileva automaticamente questo parametro: salva il codice per 30 giorni nel cookie cdp_ref e invia una sola volta l'evento referral_visited. L'amico viene conteggiato quando si registra o accede al sito. I plugin dei negozi trasmettono il codice dal cookie alla registrazione, un sito proprio tramite l'API.
Web Push
La pagina Sito → Web Push mostra se il canale è collegato e quante iscrizioni ci sono. Se il canale non c'è, lo crei tramite il link Apri integrazioni: le chiavi verranno generate automaticamente (vedi Integrazioni e canali). Quindi:
- File del service worker. Crei nella radice del sito il file
cdp-sw.jscon una sola riga:importScripts('https://cdp.onetrace.pro/tracker/cdp-sw.js'); - Pulsante di iscrizione. Aggiunga al sito un pulsante che al clic chiama
cdp.push.subscribe(). Il browser chiede il permesso per le notifiche solo in seguito a un'azione del visitatore.
Le notifiche funzionano solo su siti con HTTPS. L'iscrizione viene collegata al profilo del visitatore.
![]()
CMS e Google Tag Manager
Nella scheda CMS e GTM si trovano istruzioni passo passo per il Suo sito, Google Tag Manager, 1C-Bitrix, Tilda, WordPress e WooCommerce, InSales: dove inserire il codice di installazione, gli eventi e i widget.
Ad esempio, in Google Tag Manager crei un tag «HTML personalizzato» con il codice di installazione e l'attivatore «Tutte le pagine». Per gli eventi dei prodotti servono tag separati con la chiamata cdp.track e attivatori sugli eventi del dataLayer (view_item, add_to_cart, purchase). Dopo aver pubblicato il contenitore, verifichi nella scheda Installazione che gli eventi arrivino.
Integrazione con un agente IA
Se uno sviluppatore realizza il Suo sito con un agente IA (Claude Code, Codex, Cursor e altri), dia all'agente uno skill già pronto. Nella scheda Agente IA faccia clic su Scarica SKILL.md. Il file contiene istruzioni per l'agente in inglese con i dati del Suo progetto: l'indirizzo di OneTrace.pro, la chiave di scrittura selezionata, i nomi degli eventi dei prodotti, i widget e lo stato di Web Push. Con esse l'agente aggiunge da solo il codice di installazione, gli eventi dei prodotti, l'accesso e l'uscita, i widget e l'iscrizione alle notifiche.
- Se ci sono più chiavi di scrittura, selezioni quella necessaria.
- Scarichi il file e lo inserisca nel progetto del sito: per Claude Code in
.claude/skills/<nome dello skill>/SKILL.md, per gli altri agenti che supportano Agent Skills nella loro cartella degli skill, ad esempio.agents/skills/<nome dello skill>/SKILL.md. Il percorso esatto è indicato nella scheda. Può anche semplicemente allegare il file al Suo messaggio per l'agente. - Scriva all'agente il compito: nella scheda c'è un testo di esempio.

Le chiavi segrete non finiscono mai nello skill. Se modifica gli eventi nelle impostazioni delle raccomandazioni o aggiunge widget, scarichi di nuovo lo skill.
Da sapere
- I crawler dei motori di ricerca, le anteprime dei link nei messenger, i servizi di verifica dei siti e i browser automatizzati non vengono conteggiati: il tracker non invia i loro eventi e non imposta cookie, ma mostra i widget di raccomandazioni. Per conteggiare tutti i visitatori, aggiunga l'opzione al codice di installazione:
cdp.init('…', { host: '…', ignoreBots: false }). - Il tracker memorizza gli ID dei clic pubblicitari (
gclid,yclid,fbclid,rb_clickide altri) e i cookie dei pixel di Meta e Metrica: grazie a questi le conversioni pubblicitarie trovano il clic dopo il quale la persona ha acquistato. - Il tracker accumula gli eventi e li invia in blocchi. Se la rete si interrompe, gli eventi vengono conservati nel browser e inviati più tardi.
- Tutti gli eventi del sito sono visibili in tempo reale nella sezione Eventi.
- I widget di raccomandazione si configurano nella sezione Sito → Widget: vedi Widget di raccomandazione sul sito.