Passa al contenuto principale

React (Vite)

Installa lo snippet di tracciamento Selgeo in una single-page application React costruita con Vite. Il percorso consigliato è un semplice tag <script> in index.html — la stessa riga unica che la dashboard renderizza. Un fallback basato su useEffect è documentato alla fine di questa pagina per progetti che non possono modificare index.html.

Versione API: v1

Se non usi Vite + React, consulta invece la guida HTML / script semplice, la guida Next.js o la guida WordPress.

Perché index.html?​

In una SPA Vite, index.html è il punto di ingresso canonico: viene inviato al browser prima che venga eseguito qualunque codice React, ogni rotta viene servita dallo stesso file e il browser gestisce automaticamente la deduplicazione dei <script>. Posizionare lo snippet qui significa:

  • Lo snippet è disponibile prima che React idrati, quindi un ?ref=… iniziale viene catturato anche a cache freddo.
  • Niente useEffect, nessun rischio di doppio mount, nessuna sorpresa con React Strict Mode.
  • Un'unica fonte di verità — non serve ricordarsi di iniettare lo snippet in ogni componente di layout.

Poiché lo snippet è senza cookie e basato su sessionStorage, è sicuro caricarlo su ogni pagina di una SPA Vite senza alterare il comportamento della tua app React.

Installazione — percorso consigliato​

Passaggio 1: apri index.html​

I progetti Vite mantengono index.html nella radice del progetto (accanto a vite.config.ts), non dentro public/. Aprilo nel tuo editor.

Passaggio 2: aggiungi lo snippet prima del modulo dell'app​

Posiziona il <script> di Selgeo prima di <script type="module" src="/src/main.tsx"></script>, in modo che la richiesta async dello snippet sia già in volo prima che il modulo dell'app React inizi a essere valutato. È ciò che permette a Selgeo di vedere il ?ref=… iniziale al primo paint, prima che React, il router o qualsiasi riscrittura lato client tocchino l'URL.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Your App</title>
  </head>
  <body>
    <div id="root"></div>

    <script
      async
      src="https://cdn.selgeo.com/v1/selgeo.js"
      data-merchant="pk_test_YOUR_KEY"
    ></script>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Sostituisci pk_test_YOUR_KEY con la tua chiave API pubblica da Impostazioni > Chiavi API nella dashboard Selgeo.

index.html aperto nell&#39;editor con il tag script Selgeo aggiunto sopra il script del modulo dell&#39;app

Passaggio 3: riavvia il server di sviluppo​

pnpm dev
# oppure
npm run dev

Vite recepisce le modifiche di index.html all'avvio a freddo. L'hot-module-reload occasionalmente manca le modifiche all'HTML, quindi un riavvio è l'opzione più sicura.

Attributi obbligatori e opzionali​

AttributoObbligatorioDescrizione
srcSìURL del CDN. Sempre https://cdn.selgeo.com/v1/selgeo.js.
data-merchantSìLa tua chiave API pubblica (pk_test_* o pk_live_*).
asyncSìCaricamento asincrono; non blocca l'idratazione di React.
data-debugNoLogging verboso nella console. Rimuovi prima del go-live.
data-api-urlNoSovrascrive l'endpoint API. Presente solo nei workspace staging / sviluppo — la dashboard Selgeo lo inietta automaticamente quando necessario.

Navigazione single-page​

Lo snippet ascolta gli eventi popstate, history.pushState e history.replaceState. Se usi TanStack Router, React Router o qualsiasi altro router lato client, non serve ulteriore configurazione — un parametro ?ref=… introdotto su qualsiasi rotta viene catturato automaticamente.

Verifica dell'installazione​

  1. Avvia il server di sviluppo (pnpm dev).
  2. Ottieni un link di referral. I link di tracciamento vengono creati dai partner nel portale partner (nella sezione Link), non nella dashboard del merchant. Per un rapido test personale, accedi al portale partner come partner di test e creane uno, oppure chiedi a un partner esistente il suo link.
  3. Apri il link di tracciamento in una nuova scheda del browser: 
    http://localhost:5173/?ref=TUO_REF_DI_TEST
  4. Apri gli Strumenti per sviluppatori (F12) e controlla la Console. Con data-debug aggiunto temporaneamente, vedrai: 
    [selgeo] ref detected TUO_REF_DI_TEST
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  5. Esegui nella console: 
    __selgeo.getClickId()
    Questo dovrebbe restituire una stringa UUID.
  6. Apri la dashboard Selgeo. Il clic dovrebbe apparire in Analytics entro pochi secondi.

Console DevTools del browser che mostra le righe di debug selgeo ref detected e selgeo click_id stored

Alternativa: iniezione tramite useEffect​

Usa questo percorso solo se non puoi modificare index.html — ad esempio, se il tuo index.html è generato da un framework di livello superiore, o se stai incorporando lo snippet in un micro-frontend del quale non possiedi il layer HTML.

Questo pattern porta con sé una preoccupazione aggiuntiva: in React 18+ Strict Mode (predefinito nei template Vite), gli effetti vengono eseguiti due volte in sviluppo. Senza una protezione, lo snippet verrebbe iniettato due volte e potrebbe essere registrato un clic duplicato. Usa un id stabile dell'elemento più un cortocircuito document.getElementById:

// src/components/SelgeoSnippet.tsx
import { useEffect } from 'react';

const SELGEO_SCRIPT_ID = 'selgeo-snippet';

export function SelgeoSnippet() {
  useEffect(() => {
    if (document.getElementById(SELGEO_SCRIPT_ID)) {
      return;
    }

    const script = document.createElement('script');
    script.id = SELGEO_SCRIPT_ID;
    script.async = true;
    script.src = 'https://cdn.selgeo.com/v1/selgeo.js';
    script.setAttribute('data-merchant', 'pk_test_YOUR_KEY');
    document.body.appendChild(script);
  }, []);

  return null;
}

Monta <SelgeoSnippet /> una sola volta vicino alla radice del tuo albero di componenti (tipicamente in App.tsx, accanto al tuo router provider).

Perché la protezione è importante:

  • React 18+ Strict Mode invoca intenzionalmente gli effetti due volte in sviluppo per far emergere bug di effetti collaterali.
  • Senza il cortocircuito document.getElementById, verrebbero aggiunti due elementi <script>, entrambi eseguirebbero, e lo snippet registrerebbe due clic per lo stesso visitatore.
  • L'id="selgeo-snippet" stabile permette alla protezione di funzionare attraverso hot-reload, cambi di rotta e remount dei componenti.

Questo pattern è utile anche quando la gestione del consenso o i feature flag devono condizionare il caricamento dello snippet — racchiudi il corpo dell'effetto nella tua condizione.

Risoluzione dei problemi​

Lo snippet non viene caricato​

  • Verifica che il <script> sia all'interno di <body>, non in <head> (l'index.html di Vite dovrebbe già avere <body>).
  • Esegui pnpm build e ispeziona dist/index.html. Lo snippet dovrebbe apparire nell'HTML compilato.
  • Se usi un plugin Vite personalizzato che riscrive index.html, assicurati che preservi i tag <script> aggiunti dall'utente.
  • Controlla nella scheda Network del browser la richiesta selgeo.js — un errore CORS o CSP indica un problema di configurazione (vedi sotto).

Il clic non viene tracciato​

  • Il visitatore deve arrivare con ?ref=… al caricamento iniziale della pagina. I ricaricamenti rimuovono il parametro (lo snippet riscrive l'URL alla cattura) — emetti un link di tracciamento nuovo se hai già consumato quello attuale.
  • Verifica che data-merchant contenga una chiave pk_test_* o pk_live_* valida.
  • Se usi l'alternativa useEffect, conferma che la protezione document.getElementById sia in atto e che SELGEO_SCRIPT_ID sia univoco nella pagina.
  • Verifica la modalità della dashboard (test vs. live) — un disallineamento scarta silenziosamente il clic.

Blocco CSP​

Se imposti una Content-Security-Policy tramite un plugin Vite, un meta tag o il server di origine, consenti le origini Selgeo:

script-src 'self' https://cdn.selgeo.com;
connect-src 'self' https://app.selgeo.com;

Per i workspace staging / dev dove data-api-url punta altrove, aggiungi anche quell'origine a connect-src.

Passi successivi​