# Integration in Next.js und React-SPAs

FlowConsent in Next.js (App Router oder Pages Router) installieren und den SPA-Modus aktivieren, damit die Einwilligung bei jeder Navigation neu 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 Code 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 Code 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 Code (mit Ihrer Bereitstellungs-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 unter 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

## Mit Ihrem KI-Agenten erledigen (MCP)

FlowConsent bietet einen offiziellen MCP-Server, `https://mcp.flowconsent.com`, nutzbar aus Claude, ChatGPT oder jedem MCP-Client. Die Verbindung erfolgt per OAuth 2.0 mit Ihrem FlowConsent-Konto, ohne API-Schlüssel. Ihr Agent ruft den Code und die Platzierungsanweisungen ab (Tools `get_banner_snippet` und `get_setup_instructions`), prüft die Installation mit einem echten Scan (`verify_consent_compliance`) und kann eine wiederkehrende Überwachung einrichten (`monitor_compliance`). Ihre Next.js-App ändert er nicht: Das Einfügen bleibt Ihre Aufgabe.

Beispielanfrage: „Gib mir den Code meines Banners für meine Next.js-App und prüfe, ob er auf https://meineseite.de korrekt installiert ist.“

Siehe [MCP-Server-Anleitung](/de/doc/mcp-server) und die Seite [FlowConsent MCP](/de/mcp).