# Next.js- & React-SPA-Integration

Installieren Sie das FlowConsent-Banner in einer Next.js-App (App Router oder Pages Router) und aktivieren Sie den SPA-Modus, damit die Einwilligung bei jeder clientseitigen Navigation erneut geprüft wird.

> Canonical: https://www.flowconsent.com/de/doc/nextjs-integration
> Last updated: 2026-05-31
Das FlowConsent-Banner ist ein einzelnes, eigenständiges `<script>` — derselbe Snippet funktioniert auf Next.js, Nuxt, SvelteKit und jeder Custom-Code-App, genauso wie auf Webflow, Framer oder WordPress. Für Single-Page-Apps gibt es **einen zusätzlichen Schritt**: Aktivieren Sie den **SPA-Modus**, damit die Einwilligung bei clientseitiger Navigation erneut geprüft wird.

## Warum eine SPA einen zusätzlichen Schritt braucht

Auf einer klassischen Multi-Page-Website ist jede Navigation ein vollständiger Seiten-Reload, sodass das Banner auf jeder Seite erneut läuft und Tracking-Skripte erneut blockiert. Eine Single Page Application (Next.js, React, Vue…) navigiert mit `history.pushState` — **ohne Seiten-Reload** — daher würden ohne SPA-Modus nach der ersten Seite eingefügte Skripte auf Folgeseiten nicht erneut blockiert.

Der SPA-Modus hängt sich in `pushState`, `replaceState` und `popstate` ein, um die Einwilligung bei jeder clientseitigen Navigation erneut zu prüfen.

## Schritt 1 — Skript hinzufügen

Das Banner liefert die Google-Consent-Mode-v2-Standardwerte bereits im Bundle mit, sodass der Snippet minimal bleibt: Laden Sie das Skript einfach so früh wie möglich.

### App Router (`app/layout.tsx`)

```tsx
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        {/* FlowConsent CMP */}
        <Script
          src="https://IHR-WORKSPACE.consent.flowconsent.com/cookie-manager.js?code=IHR_LIZENZCODE"
          strategy="beforeInteractive"
        />
      </body>
    </html>
  )
}
```

`strategy="beforeInteractive"` lädt das Skript vor der Hydration, sodass das vorherige Blockieren aktiv ist, bevor Tracking ausgelöst wird.

### Pages Router (`pages/_document.tsx`)

```tsx
import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head>
        {/* FlowConsent CMP — als Erstes in <Head> platzieren */}
        <script src="https://IHR-WORKSPACE.consent.flowconsent.com/cookie-manager.js?code=IHR_LIZENZCODE" />
      </Head>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
```

Ihren genauen Snippet (mit Ihrer Deployment-URL und Ihrem Lizenzcode) finden Sie unter **Builder → Deployment → Integration**, wo ein **Next.js**-Tab diesen Code für Sie generiert.

## Schritt 2 — SPA-Modus aktivieren

Öffnen Sie im Builder den Tab **Einstellungen** und aktivieren Sie den **SPA-Modus**. Stellen Sie Ihr Banner erneut bereit, damit die Änderung wirksam wird.

Mit aktiviertem SPA-Modus wird FlowConsent:

- `history.pushState` und `history.replaceState` abfangen
- auf `popstate`-Ereignisse hören
- nicht abgedeckte Tracking-Skripte bei jeder Navigation erneut blockieren
- ein `flowconsent:navigation`-Ereignis auslösen, das Sie abonnieren können

## Schritt 3 — FlowConsent die Tracking-Skripte verwalten lassen

Laden Sie Tracking-Skripte (Google Analytics, Meta Pixel…) **nicht** mit `next/script`. Deklarieren Sie sie stattdessen unter **Builder → Services** und lassen Sie FlowConsent sie nach erteilter Einwilligung einfügen.

```tsx
// Vermeiden — Tracking-Skript außerhalb der Kontrolle von FlowConsent
<Script src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" strategy="afterInteractive" />

// Bevorzugen — Google Analytics unter Builder → Services konfigurieren
```

## Optional — Auf die Einwilligung in Ihrer App reagieren

FlowConsent löst Ereignisse aus, die Sie abonnieren können:

```tsx
import { useEffect } from 'react'

export function useConsentListener() {
  useEffect(() => {
    const onConsent = (event) => {
      const { preferences } = event.detail
      if (preferences?.analytics) {
        // Analytics-Einwilligung erteilt — eigene Analytics initialisieren
      }
    }
    window.addEventListener('flowconsent:consent', onConsent)
    return () => window.removeEventListener('flowconsent:consent', onConsent)
  }, [])
}
```

## Prüf-Checkliste

- [ ] Skript ist in `app/layout.tsx` (App Router) oder `pages/_document.tsx` (Pages Router)
- [ ] App Router verwendet `strategy="beforeInteractive"`
- [ ] **SPA-Modus** ist im Builder aktiviert und das Banner neu bereitgestellt
- [ ] Kein `next/script` für Tracking-Skripte — sie sind in Services konfiguriert
- [ ] Banner erscheint beim ersten Laden
- [ ] Keine Tracking-Anfragen im Netzwerk-Tab vor dem Klick auf **Akzeptieren**
- [ ] Einwilligung bleibt über clientseitige Navigationen hinweg erhalten
