Next.js- & React-SPA-Integration

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`)

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`)

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.

// 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:

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