Passa al contenuto principale

Next.js

Installa lo snippet di tracciamento Selgeo in un'applicazione Next.js usando il componente nativo del framework next/script. Questa guida copre sia l'App Router (app/layout.tsx) sia il Pages Router (pages/_app.tsx).

Versione API: v1

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

Perché next/script?​

Un tag <script> semplice in un componente React non si comporta come in HTML puro — Next.js raggruppa il JavaScript per rotta e idrata le pagine in modo incrementale. Il componente ufficiale next/script:

  • Carica lo snippet esattamente una volta tra le navigazioni lato client (nessuna esecuzione duplicata).
  • Rispetta una strategy di caricamento che controlli tu (noi usiamo afterInteractive).
  • Si integra bene con l'SSR in streaming di Next.js e il Partial Prerendering.

Usiamo strategy="afterInteractive" invece di lazyOnload in modo che lo snippet sia pronto prima di elaborare il primo parametro ?ref=. L'accuratezza dell'attribuzione vale più di un guadagno marginale di Lighthouse — lazyOnload rischia di mancare un clic precoce che converte subito.

Installazione — App Router (app/layout.tsx)​

Per progetti su Next.js 13+ che usano la directory app/.

Passaggio 1: aggiungi lo snippet al layout radice​

Apri app/layout.tsx e aggiungi l'import di Script e l'elemento JSX:

import Script from 'next/script';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          async
          src="https://cdn.selgeo.com/v1/selgeo.js"
          data-merchant="pk_test_YOUR_KEY"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

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

Scheda Settings &gt; API Keys nella dashboard Selgeo con le chiavi pubblicabili per le modalità Test e Live

Passaggio 2: salva ed esegui​

pnpm dev
# oppure
npm run dev

Apri il tuo sito nel browser. Lo snippet ora si carica su ogni pagina renderizzata dall'App Router.

Installazione — Pages Router (pages/_app.tsx)​

Per progetti sulla directory legacy pages/.

Passaggio 1: aggiungi lo snippet al componente App personalizzato​

Apri (o crea) pages/_app.tsx:

import type { AppProps } from 'next/app';
import Script from 'next/script';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        async
        src="https://cdn.selgeo.com/v1/selgeo.js"
        data-merchant="pk_test_YOUR_KEY"
        strategy="afterInteractive"
      />
    </>
  );
}

Passaggio 2: riavvia il server di sviluppo​

pnpm dev

I progetti Pages Router devono riavviare il server di sviluppo quando _app.tsx viene creato per la prima volta. Le modifiche successive si ricaricano a caldo normalmente.

Card Tracking Snippet in Settings che mostra il tab Next.js con i blocchi di import e componente pronti da copiare

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.
strategySìUsa "afterInteractive". Non passare a "lazyOnload" — i clic di referral precoci potrebbero essere persi.
data-debugNoAbilita il logging 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.

Verifica dell'installazione​

  1. Compila ed esegui il tuo progetto (pnpm dev o pnpm build && pnpm start).
  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. Visita il tuo sito con il link di tracciamento, ad esempio: 
    https://tuo-sito.com/?ref=TUO_REF_DI_TEST
  4. Apri gli Strumenti per sviluppatori (F12) e controlla la Console. Con data-debug aggiunto temporaneamente, dovresti vedere: 
    [selgeo] ref detected TUO_REF_DI_TEST
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  5. Nella console del browser, esegui: 
    __selgeo.getClickId()
    Questo dovrebbe restituire una stringa UUID. null significa che lo snippet non ha rilevato un parametro ?ref=.
  6. Apri la dashboard Selgeo. Il clic dovrebbe apparire in Analytics entro pochi secondi.

Vista Analytics di Selgeo che mostra l&#39;attività recente dei clic e i top partner

Risoluzione dei problemi​

Lo snippet non viene caricato​

  • Verifica che app/layout.tsx (App Router) o pages/_app.tsx (Pages Router) contengano effettivamente il blocco <Script> — la duplicazione accidentale in un singolo file di pagina è l'errore più comune.
  • Verifica che src sia esattamente https://cdn.selgeo.com/v1/selgeo.js. Un errore di battitura causa un fallimento silenzioso del caricamento dello script.
  • Apri la scheda Network e filtra per selgeo.js. Una voce in rosso con stato 0 o un errore CORS di solito indica una violazione CSP — vedi sotto.
  • Se stai eseguendo con un export statico (output: 'export'), verifica che lo snippet sia incluso nell'HTML esportato. next/script con strategy="afterInteractive" viene preservato dall'export statico.

Il clic non viene tracciato​

  • Il visitatore deve arrivare con ?ref=… al caricamento iniziale della pagina. Una volta che lo snippet cattura il clic, l'URL viene riscritto e il parametro non appare più. Ricarica la pagina con un link di tracciamento nuovo se hai già consumato quello attuale.
  • Verifica che data-merchant contenga una chiave pk_test_* o pk_live_* valida. Un valore troncato o con uno spazio iniziale causerà un no-op silenzioso.
  • Se usi React Strict Mode, assicurati che lo snippet sia in app/layout.tsx o pages/_app.tsx, non dentro un effetto che può eseguirsi due volte. next/script già deduplica correttamente.
  • Controlla la modalità della dashboard Selgeo (test vs. live). Una chiave pk_live_* su un link di tracciamento emesso in modalità test non registrerà il clic.

Blocco CSP​

Se il tuo progetto Next.js imposta un header Content-Security-Policy (next.config.js headers(), middleware o una voce vercel.json), 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. Se non puoi allentare la CSP, considera di instradare lo snippet attraverso la tua origine (avanzato, fuori scope per questa guida).

Passi successivi​