Ga naar hoofdinhoud

Next.js

Installeer het Selgeo-trackingsnippet in een Next.js-applicatie met de eigen next/script-component van het framework. Deze handleiding behandelt zowel de App Router (app/layout.tsx) als de Pages Router (pages/_app.tsx).

API-versie: v1

Als u geen Next.js gebruikt, raadpleeg dan in plaats daarvan de HTML- / eenvoudige-script-handleiding, de React-(Vite)-handleiding of de WordPress-handleiding.

Waarom next/script?​

Een gewone <script>-tag in een React-component gedraagt zich niet zoals in puur HTML — Next.js bundelt JavaScript per route en hydrateert pagina's incrementeel. De officiële next/script-component:

  • Laadt het snippet precies één keer over client-side navigaties (geen dubbele uitvoering).
  • Respecteert een strategy voor laden die u zelf bepaalt (wij gebruiken afterInteractive).
  • Werkt goed samen met de streaming SSR van Next.js en Partial Prerendering.

We gebruiken strategy="afterInteractive" in plaats van lazyOnload zodat het snippet gereed is voordat de eerste ?ref=-parameter wordt verwerkt. Attributienauwkeurigheid weegt zwaarder dan een marginale Lighthouse-score — lazyOnload riskeert een vroege klik te missen die direct converteert.

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

Voor projecten op Next.js 13+ die de app/-map gebruiken.

Stap 1: Voeg het snippet toe aan het hoofdlayout​

Open app/layout.tsx en voeg de Script-import en het JSX-element toe:

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>
  );
}

Vervang pk_test_YOUR_KEY door uw publieke API-sleutel uit Instellingen > API-sleutels in het Selgeo-dashboard.

Pagina Settings &gt; API Keys in het Selgeo-dashboard met het veld voor de publieke sleutel gemarkeerd

Stap 2: Opslaan en uitvoeren​

pnpm dev
# of
npm run dev

Open uw site in de browser. Het snippet laadt nu op elke pagina die door de App Router wordt gerenderd.

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

Voor projecten op de oudere pages/-map.

Stap 1: Voeg het snippet toe aan de aangepaste App-component​

Open (of maak) 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"
      />
    </>
  );
}

Stap 2: Herstart de ontwikkelserver​

pnpm dev

Pages-Router-projecten moeten de ontwikkelserver herstarten als _app.tsx voor het eerst wordt aangemaakt. Latere bewerkingen worden normaal hot-reloaded.

De Tracking Snippet-kaart in Settings met het Next.js-tabblad en de kopieer-klare import- en componentblokken

Verplichte en optionele attributen​

AttribuutVerplichtBeschrijving
srcJaCDN-URL. Altijd https://cdn.selgeo.com/v1/selgeo.js.
data-merchantJaUw publieke API-sleutel (pk_test_* of pk_live_*).
asyncJaAsynchroon laden; blokkeert de hydratatie niet.
strategyJaGebruik "afterInteractive". Schakel niet over op "lazyOnload" — vroege referralklikken kunnen worden gemist.
data-debugNeeSchakelt uitgebreide consolelogging in. Verwijderen voor go-live.
data-api-urlNeeOverschrijft het API-eindpunt. Alleen aanwezig in staging- / ontwikkelworkspaces — het Selgeo-dashboard voegt dit automatisch in waar nodig.

Uw installatie verifiëren​

  1. Bouw en start uw project (pnpm dev of pnpm build && pnpm start).
  2. Maak een trackinglink aan in het Selgeo-dashboard onder Programma's > Trackinglinks.
  3. Bezoek uw site met de trackinglink, bijvoorbeeld: 
    https://uw-site.com/?ref=UW_TEST_REF
  4. Open de Developer Tools (F12) en controleer de Console. Met tijdelijk toegevoegde data-debug zou u moeten zien: 
    [selgeo] ref detected UW_TEST_REF
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  5. Voer in de browserconsole uit: 
    __selgeo.getClickId()
    Dit zou een UUID-string moeten teruggeven. null betekent dat het snippet geen ?ref=-parameter heeft gedetecteerd.
  6. Open het Selgeo-dashboard. De klik zou binnen enkele seconden moeten verschijnen onder Analytics.

Selgeo Analytics-weergave met recente klikactiviteit en toppartners

Probleemoplossing​

Snippet niet geladen​

  • Bevestig dat app/layout.tsx (App Router) of pages/_app.tsx (Pages Router) daadwerkelijk het <Script>-blok bevat — onbedoelde duplicatie naar een afzonderlijk paginabestand is de meest voorkomende fout.
  • Verifieer dat src exact https://cdn.selgeo.com/v1/selgeo.js is. Een typefout laat het laden stilzwijgend mislukken.
  • Open het Network-tabblad en filter op selgeo.js. Een rode regel met status 0 of een CORS-fout duidt meestal op een CSP-overtreding — zie hieronder.
  • Als u draait met statische export (output: 'export'), bevestig dat het snippet in de geëxporteerde HTML is opgenomen. next/script met strategy="afterInteractive" blijft behouden bij statische export.

Klik niet getraceerd​

  • De bezoeker moet aankomen met ?ref=… bij de initiële paginalading. Zodra het snippet de klik vastlegt, wordt de URL herschreven en verschijnt de parameter niet meer. Laad de pagina opnieuw met een nieuwe trackinglink als u de huidige al hebt verbruikt.
  • Bevestig dat data-merchant een geldige pk_test_*- of pk_live_*-sleutel bevat. Een afgekapte of met spatie voorafgegane waarde leidt stilzwijgend tot geen-effect.
  • Als u React Strict Mode gebruikt, zorg ervoor dat het snippet in app/layout.tsx of pages/_app.tsx staat, niet binnen een effect dat twee keer kan worden uitgevoerd. next/script dedupliceert al correct.
  • Controleer de Selgeo-dashboardmodus (test vs. live). Een pk_live_*-sleutel op een in testmodus uitgegeven trackinglink registreert de klik niet.

CSP-blokkering​

Als uw Next.js-project een Content-Security-Policy-header instelt (via next.config.js headers(), middleware of een vercel.json-vermelding), sta dan de Selgeo-oorsprongen toe:

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

Voeg voor staging- / dev-workspaces waar data-api-url naar een andere oorsprong wijst, die oorsprong ook toe aan connect-src. Als u de CSP niet kunt versoepelen, overweeg dan het snippet via uw eigen oorsprong te routeren (geavanceerd, buiten de scope van deze handleiding).

Volgende stappen​