# live-chat auf einer next.js-seite
Bau den Chat von Spookat in eine Next.js-App ein, im App Router oder Pages Router, mit Look und optional eingeloggtem Nutzer, und prüf, dass vor einem Klick keine Anfrage an unsere API geht.
2026-11-04 · Kuba
Live-Chat in Next.js ist ein Script-Tag im Root-Layout. Dieser Guide zeigt, wo er im App Router und im Pages Router hingehört, wie du den Look des Widgets und den eingeloggten Nutzer übergibst, ohne die Ladereihenfolge zu zerschießen, was in eine Content Security Policy gehört und wie du das Ergebnis in einem Produktions-Build prüfst.
## die kurzfassung
Im App Router kommt der Tag in `app/layout.tsx`, innerhalb von ``:
```tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
Ersetz `YOUR_SITE_KEY` durch den Key von der Install-Seite im Dashboard. Das ist die ganze Installation, wenn der Look im Dashboard liegt, und das ist der Standard. Der Rest dieses Guides ist für den Fall, dass du mehr Kontrolle willst. Wenn du bei null anfängst, erklärt der [Grundlagen-Guide](/de/blog/add-live-chat-to-your-website/) die Kontoseite.
## warum das root-layout
Das Root-Layout umschließt jede Route und bleibt gemountet, während der Nutzer navigiert. Der Launcher hängt sich einmal an die Seite. Client-seitige Navigation lädt die Seite nicht neu, also auch den Launcher nicht, und ein Besucher kann ein Gespräch offen halten, während er herumklickt.
Setzt du den Tag in eine Seitenkomponente, gibt es den Chat nur auf dieser Seite. Setzt du ihn in eine Komponente, die auf mehreren Seiten rendert, bekommst du bei harten Reloads Duplikate (der Launcher ignoriert seine eigene zweite Kopie, aber es ist trotzdem ein verschwendeter Request).
## mit next/script
`next/script` ist der Next.js-Weg, Scripts von Dritten zu laden, und funktioniert hier gut:
```tsx
import Script from "next/script";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
`afterInteractive` lädt den Launcher direkt nach der Hydration. `lazyOnload` wartet, bis der Browser idle ist, was das Erscheinen des Buttons auf langsamen Handys etwas nach hinten schiebt. Beides ist für einen 2-kb-Launcher in Ordnung; `afterInteractive` zeigt den Button früher. Nimm für den Launcher nicht `beforeInteractive`: Er würde für nichts mit deinem eigenen Code konkurrieren.
## den look im code setzen
Der Look, den du im Dashboard veröffentlichst, steckt im Launcher. Wenn du ihn lieber im Repo hältst, setz `window.Spookat`, bevor der Launcher läuft. Die Konfiguration der Seite schlägt die des Dashboards.
Die Ladereihenfolge zählt: Die Konfiguration muss existieren, wenn der Launcher ausgeführt wird. Mit `next/script` gibst du der Konfiguration `beforeInteractive` (im Root-Layout erlaubt) und dem Launcher `afterInteractive`:
```tsx
import Script from "next/script";
const spookat = { style: "clean", font: "system", accent: "#2F6FEB", side: "right" };
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
`beforeInteractive`-Scripts laufen vor der Hydration, `afterInteractive`-Scripts danach, die Reihenfolge ist also garantiert. Die Keys sind dieselben wie überall: `style` (einer von 8), `font`, `accent`, `side`, `greeting`, `label`, `lang`. Die [Docs](/de/docs/) listen sie alle.
## der pages router
Im Pages Router ist der gemeinsame Wrapper `pages/_app.tsx`:
```tsx
import type { AppProps } from "next/app";
import Script from "next/script";
export default function App({ Component, pageProps }: AppProps) {
return (
<>
);
}
```
Für eine Konfiguration gehören `beforeInteractive`-Scripts im Pages Router in `pages/_document.tsx`. Setz das `window.Spookat`-Script dort hinein, innerhalb von ``, mit derselben `id` und `strategy` wie oben, und lass den Launcher in `_app.tsx`.
## der eingeloggte nutzer
Ab pro kannst du dem Chat sagen, wer eingeloggt ist. Dein Team sieht dann `logged in as 42` auf der Slack-Karte, und Webhooks, der Export und `read_convo` deines Agenten tragen die ID. Die ID wird mit einem Secret signiert, das nur dein Server kennt, damit niemand sich als jemand anderes ausgeben kann.
Erstell das Identity-Secret auf der Install-Seite im Dashboard, pack es in eine Umgebungsvariable und signier auf dem Server. Im App Router ist das Root-Layout eine Server-Komponente, was das einfach macht:
```tsx
import { createHmac } from "node:crypto";
import Script from "next/script";
import { getSession } from "@/lib/auth"; // yours
const sign = (id: string) => createHmac("sha256", process.env.SPOOKAT_IDENTITY_SECRET!).update(id).digest("hex");
export default async function RootLayout({ children }: { children: React.ReactNode }) {
const session = await getSession();
const user = session ? { id: String(session.userId), sig: sign(String(session.userId)) } : undefined;
return (
{children}
{user && (
)}
);
}
```
Berechne die Signatur nie in einer Client-Komponente: Das Secret würde im Browser landen. Eine fehlende oder falsche Signatur ist kein Fehler; der Chat sagt dann einfach nicht, wer es ist. Wenn du die Session im Root-Layout liest, rendert jede Seite pro Request. Ist dein Layout heute statisch, wäg das ab, bevor du es hinzufügst.
## content security policy
Wenn deine App einen `Content-Security-Policy`-Header schickt, braucht das Widget:
- `script-src` und `style-src`: `https://cdn.spookat.com`
- `font-src`: `https://cdn.spookat.com`, wenn du einen gehosteten Font gewählt hast
- `connect-src`: `wss://api.spookat.com`, für die Chat-Verbindung nach einem Klick
- `img-src`: `data:`, für Logos und Profilbilder deines Teams
- `style-src`: Der Launcher fügt einen kleinen `