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 sezione Coinvolgimento → Sito web.

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

1. Nel campo Chiave di scrittura scelga una chiave. Se non ci sono chiavi, faccia clic su Crea una chiave per il sito web.
2. Copi il codice con il pulsante di copia.
3. 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.ru/tracker/cdp.js');
cdp.init('cdp_wk_…', { host: 'https://cdp.onetrace.ru' });
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:

1. 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.
2. 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: 'anna@example.com' });

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.

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.

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 scheda 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:

1. File del service worker. Crei nella radice del sito il file cdp-sw.js con una sola riga:

   importScripts('https://cdp.onetrace.ru/tracker/cdp-sw.js');
   

2. 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.ru, 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.

1. Se ci sono più chiavi di scrittura, selezioni quella necessaria.
2. 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.
3. 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 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 scheda Widget: vedi Widget di raccomandazione sul sito.