Configurazione snippet

Questa pagina è la guida all'installazione HTML / script semplice per lo snippet di tracciamento Selgeo (selgeo.js) — un file JavaScript leggero che viene eseguito sul tuo sito web, registra i clic di referral dei partner e memorizza i dati di attribuzione nel browser del visitatore per la corrispondenza delle conversioni successiva. Usa questa guida se controlli direttamente l'HTML grezzo del tuo sito (siti statici, Webflow, Shopify Liquid, pagine personalizzate renderizzate dal server o un tag manager).

Usi un framework?

• Next.js — consulta la guida Next.js per il pattern del componente next/script.
• React (Vite) — consulta la guida React (Vite) per il posizionamento in index.html e il fallback useEffect.
• WordPress — consulta la guida WordPress per il posizionamento tramite Editor del sito, footer.php e plugin per intestazione e piè di pagina.

Versione API: v1

Installazione di base

Aggiungi il seguente tag <script> a ogni pagina del tuo sito web, appena prima del tag di chiusura </body>:

<script
  async
  src="https://cdn.selgeo.com/v1/selgeo.js"
  data-merchant="pk_test_YOUR_KEY"
></script>

Attributi richiesti

Attributo	Descrizione
src	URL CDN dello snippet. Usa sempre https://cdn.selgeo.com/v1/selgeo.js.
data-merchant	La tua chiave API pubblica (pk_test_* per la modalità test, pk_live_* per la modalità live).
async	Carica lo snippet in modo asincrono per non bloccare il rendering della pagina.

Attributi opzionali

Attributo	Descrizione
data-debug	Abilita la registrazione di debug nella console del browser. Rimuovere prima di andare in produzione.
data-api-url	Sostituisce l'URL dell'endpoint API. Solo per uso avanzato.

Come funziona

Quando un visitatore arriva sul tuo sito con un parametro ?ref= nell'URL, lo snippet:

1. Rileva il parametro di query ref.
2. Registra il clic con l'API Selgeo usando la tua chiave pubblica.
3. Memorizza il click_id restituito dall'API nel sessionStorage del browser.
4. Rimuove ?ref= dall'URL usando history.replaceState.
5. Riscrive i Stripe Payment Links sulla pagina per includere client_reference_id=CLICK_ID.

Meccanismo di archiviazione

Chiave	Valore	Durata
__selgeo_cid	Il click_id (UUID)	Fino alla chiusura della scheda del browser
__selgeo_vtk	Un token visitatore (UUID)	Fino alla chiusura della scheda del browser

Implicazioni per la privacy:

• sessionStorage è limitato alla scheda — non è condiviso tra schede o finestre.
• I dati vengono cancellati automaticamente quando la scheda viene chiusa.
• Non vengono impostati cookie. Non è richiesto il banner di consenso ai cookie per il tracciamento Selgeo.

Lettura dell'ID clic

const clickId = __selgeo.getClickId();
// Restituisce una stringa UUID o null se non è stato registrato alcun clic di referral

Metodi disponibili

Metodo	Restituisce	Descrizione
__selgeo.getClickId()	string | null	L'ID clic corrente, o null se non esiste
__selgeo.getVisitorToken()	string | null	Il token visitatore corrente, o null
__selgeo.checkUrl()	void	Controlla manualmente l'URL corrente per un parametro ?ref=

Applicazioni a pagina singola (SPA)

Lo snippet monitora automaticamente le modifiche URL nelle applicazioni a pagina singola ascoltando gli eventi popstate e le chiamate history.pushState/history.replaceState.

Riscrittura automatica dei Stripe Payment Links

Se la tua pagina contiene link a Stripe Payment Links (https://buy.stripe.com/...), lo snippet aggiunge automaticamente ?client_reference_id=CLICK_ID quando è attivo un clic di referral.

<!-- Prima dell'esecuzione dello snippet -->
<a href="https://buy.stripe.com/test_abc123">Abbonati</a>

<!-- Dopo l'esecuzione dello snippet (quando è memorizzato un click_id) -->
<a href="https://buy.stripe.com/test_abc123?client_reference_id=CLICK_ID">Abbonati</a>

Raccomandazioni sul posizionamento

Scenario	Raccomandazione
Sito web standard	Aggiungi a ogni pagina tramite il layout/template globale
SPA (React, Vue, ecc.)	Aggiungi una volta a index.html — lo snippet gestisce i cambiamenti di route
Solo landing page	Aggiungi solo alle pagine dove atterra il traffico partner
Solo pagina di checkout	Non consigliato — lo snippet deve essere sulla landing page

Lo snippet deve essere sulla landing page

Il parametro ?ref= è presente solo nell'URL iniziale quando il visitatore fa clic su un link partner. Se lo snippet non è caricato su quella pagina, il clic non verrà registrato.

Passaggi successivi

• Stripe Payment Links — integrazione Stripe senza backend
• Stripe Checkout — passare click_id alle Sessioni di pagamento
• Stripe Metadata — passare click_id tramite i metadati
• API di conversione — tracciare le conversioni non-Stripe