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.

Pagina Settings &gt; API Keys nella dashboard Selgeo con il campo della chiave pubblica evidenziato

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. Crea un link di tracciamento nella dashboard Selgeo sotto Programmi > Link di tracciamento.
  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://api.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​