Next.js

Installieren Sie das Selgeo-Tracking-Snippet in einer Next.js-Anwendung mit der nativen next/script-Komponente des Frameworks. Diese Anleitung deckt sowohl den App Router (app/layout.tsx) als auch den Pages Router (pages/_app.tsx) ab.

API-Version: v1

Wenn Sie kein Next.js verwenden, lesen Sie stattdessen die HTML- / einfache-Script-Anleitung, die React-(Vite)-Anleitung oder die WordPress-Anleitung.

Warum `next/script`?

Ein einfaches <script>-Tag in einer React-Komponente verhält sich nicht so wie in reinem HTML — Next.js bündelt JavaScript pro Route und hydratisiert Seiten inkrementell. Die offizielle next/script-Komponente:

Lädt das Snippet bei clientseitigen Navigationen genau einmal (keine doppelte Ausführung).
Berücksichtigt eine von Ihnen kontrollierte Lade-strategy (wir verwenden afterInteractive).
Funktioniert gut mit Next.js' Streaming-SSR und Partial Prerendering.

Wir verwenden strategy="afterInteractive" statt lazyOnload, damit das Snippet bereit ist, bevor der erste ?ref=-Parameter verarbeitet wird. Attributionsgenauigkeit ist wichtiger als marginale Lighthouse-Punkte — lazyOnload riskiert, einen frühen Klick zu verpassen, der sofort konvertiert.

Installation — App Router (`app/layout.tsx`)

Für Projekte auf Next.js 13+ mit dem app/-Verzeichnis.

Schritt 1: Snippet zum Root-Layout hinzufügen

Öffnen Sie app/layout.tsx und fügen Sie den Script-Import und das JSX-Element hinzu:

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

Ersetzen Sie pk_test_YOUR_KEY durch Ihren öffentlichen API-Schlüssel aus Einstellungen > API-Schlüssel im Selgeo-Dashboard.

Seite „Settings > API Keys" im Selgeo-Dashboard mit hervorgehobenem Feld für den öffentlichen Schlüssel

Schritt 2: Speichern und ausführen

pnpm dev
# oder
npm run dev

Öffnen Sie Ihre Website im Browser. Das Snippet wird jetzt auf jeder Seite geladen, die vom App Router gerendert wird.

Installation — Pages Router (`pages/_app.tsx`)

Für Projekte mit dem klassischen pages/-Verzeichnis.

Schritt 1: Snippet zur benutzerdefinierten App-Komponente hinzufügen

Öffnen Sie (oder erstellen Sie) 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"
      />
    </>
  );
}

Schritt 2: Dev-Server neu starten

pnpm dev

Pages-Router-Projekte müssen den Dev-Server beim erstmaligen Anlegen von _app.tsx neu starten. Nachfolgende Änderungen werden normal per Hot-Reload übernommen.

Die Tracking-Snippet-Karte in Settings mit dem Next.js-Tab und den kopierfertigen Import- und Komponentenblöcken

Erforderliche und optionale Attribute

Attribut	Erforderlich	Beschreibung
`src`	Ja	CDN-URL. Immer `https://cdn.selgeo.com/v1/selgeo.js`.
`data-merchant`	Ja	Ihr öffentlicher API-Schlüssel (`pk_test_` oder `pk_live_`).
`async`	Ja	Asynchrones Laden; blockiert die Hydration nicht.
`strategy`	Ja	Verwenden Sie `"afterInteractive"`. Wechseln Sie nicht zu `"lazyOnload"` — frühe Empfehlungsklicks könnten verpasst werden.
`data-debug`	Nein	Aktiviert ausführliches Konsolen-Logging. Vor dem Go-Live entfernen.
`data-api-url`	Nein	Überschreibt den API-Endpunkt. Nur in Staging- / Entwicklungs-Workspaces vorhanden — das Selgeo-Dashboard fügt ihn bei Bedarf automatisch ein.

Installation überprüfen

Bauen und starten Sie Ihr Projekt (pnpm dev oder pnpm build && pnpm start).
Erstellen Sie einen Tracking-Link im Selgeo-Dashboard unter Programme > Tracking-Links.
Besuchen Sie Ihre Website mit dem Tracking-Link, zum Beispiel:
```
https://ihre-website.com/?ref=IHR_TEST_REF
```
Öffnen Sie die Developer Tools (F12) und prüfen Sie die Konsole. Mit temporär hinzugefügtem data-debug sollten Sie sehen:
```
[selgeo] ref detected IHR_TEST_REF
[selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
```
Führen Sie in der Browser-Konsole aus:
```
__selgeo.getClickId()
```
Dies sollte einen UUID-String zurückgeben. null bedeutet, dass das Snippet keinen ?ref=-Parameter erkannt hat.
Öffnen Sie das Selgeo-Dashboard. Der Klick sollte innerhalb weniger Sekunden unter Analytics erscheinen.

Selgeo-Analytics-Ansicht mit den letzten Klick-Aktivitäten und Top-Partnern

Fehlerbehebung

Snippet wird nicht geladen

Überprüfen Sie, dass app/layout.tsx (App Router) oder pages/_app.tsx (Pages Router) tatsächlich den <Script>-Block enthält — versehentliche Duplizierung in eine einzelne Seitendatei ist der häufigste Fehler.
Stellen Sie sicher, dass src exakt https://cdn.selgeo.com/v1/selgeo.js lautet. Ein Tippfehler führt zu einem stillen Ladefehler.
Öffnen Sie den Netzwerk-Tab und filtern Sie nach selgeo.js. Ein roter Eintrag mit Status 0 oder ein CORS-Fehler weist meist auf einen CSP-Verstoß hin — siehe unten.
Wenn Sie hinter einem statischen Export (output: 'export') laufen, prüfen Sie, dass das Snippet im exportierten HTML enthalten ist. next/script mit strategy="afterInteractive" bleibt beim statischen Export erhalten.

Klick wird nicht verfolgt

Der Besucher muss mit ?ref=… auf der ersten Seitenansicht ankommen. Sobald das Snippet den Klick erfasst hat, wird die URL umgeschrieben und der Parameter erscheint nicht mehr. Laden Sie die Seite mit einem frischen Tracking-Link neu, wenn Sie den aktuellen bereits verwendet haben.
Stellen Sie sicher, dass data-merchant einen gültigen pk_test_*- oder pk_live_*-Schlüssel enthält. Ein abgeschnittener oder mit Leerzeichen beginnender Wert führt zu einem stillen No-Op.
Wenn Sie React Strict Mode verwenden, stellen Sie sicher, dass das Snippet in app/layout.tsx oder pages/_app.tsx steht, nicht in einem Effekt, der zweimal ausgeführt werden kann. next/script dedupliziert bereits korrekt.
Überprüfen Sie den Selgeo-Dashboard-Modus (Test vs. Live). Ein pk_live_*-Schlüssel auf einem im Testmodus ausgestellten Tracking-Link registriert den Klick nicht.

CSP-Blockierung

Wenn Ihr Next.js-Projekt einen Content-Security-Policy-Header setzt (next.config.js headers(), Middleware oder ein vercel.json-Eintrag), erlauben Sie die Selgeo-Ursprünge:

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

Bei Staging- / Dev-Workspaces, in denen data-api-url auf einen anderen Ursprung zeigt, fügen Sie diesen Ursprung ebenfalls zu connect-src hinzu. Wenn Sie die CSP nicht lockern können, leiten Sie das Snippet ggf. über Ihren eigenen Ursprung (fortgeschritten, außerhalb des Umfangs dieser Anleitung).

Nächste Schritte

Stripe Payment Links — Stripe-Integration ohne Backend.
Stripe Checkout — click_id von Ihrem Server an Checkout Sessions übergeben.
Conversion API — Nicht-Stripe-Konversionen verfolgen.
Snippet-Setup — vollständige Attributreferenz und das zugrunde liegende HTML-Script-Tag.

Warum next/script?​

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

Schritt 1: Snippet zum Root-Layout hinzufügen​

Schritt 2: Speichern und ausführen​

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

Schritt 1: Snippet zur benutzerdefinierten App-Komponente hinzufügen​

Schritt 2: Dev-Server neu starten​

Erforderliche und optionale Attribute​

Installation überprüfen​

Fehlerbehebung​

Snippet wird nicht geladen​

Klick wird nicht verfolgt​

CSP-Blockierung​

Nächste Schritte​