# aggiungi una live chat a un sito next.js
Aggiungi la chat di Spookat a un’app Next.js, con app router o pages router, con il suo aspetto e, se vuoi, l’utente connesso, e verifica che non parta nessuna richiesta alla nostra API prima di un clic.
2026-11-04 · Kuba
La live chat in Next.js è un tag script nel layout principale. Questa guida mostra dove va con l’app router e con il pages router, come passare l’aspetto del widget e l’utente connesso senza rompere l’ordine di caricamento, cosa aggiungere a una Content Security Policy e come controllare il risultato in una build di produzione.
## la versione breve
Con l’app router, aggiungi il tag in `app/layout.tsx`, dentro ``:
```tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
Sostituisci `YOUR_SITE_KEY` con la chiave della pagina di installazione nella dashboard. È tutta l’installazione quando l’aspetto sta nella dashboard, che è il caso predefinito. Il resto della guida serve quando vuoi più controllo. Se parti da zero, la [guida principale](/it/blog/add-live-chat-to-your-website/) copre la parte dell’account.
## perché il layout principale
Il layout principale avvolge ogni route e resta montato mentre l’utente naviga. Il launcher si aggancia alla pagina una sola volta. La navigazione lato client non ricarica la pagina, quindi non ricarica nemmeno il launcher, e un visitatore può tenere aperta una conversazione mentre clicca in giro.
Metti il tag in un componente di pagina e la chat esiste solo su quella pagina. Mettilo in un componente che viene renderizzato su più pagine e avrai duplicati nei ricaricamenti completi (il launcher ignora la propria seconda copia, ma resta una richiesta sprecata).
## con next/script
`next/script` è il modo di Next.js per caricare script di terze parti, e qui funziona bene:
```tsx
import Script from "next/script";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
`afterInteractive` carica il launcher subito dopo l’idratazione. `lazyOnload` aspetta che il browser sia inattivo, e sui telefoni lenti fa comparire il pulsante un po’ più tardi. Vanno bene entrambi per un launcher da 2 kb; `afterInteractive` mostra il pulsante prima. Non usare `beforeInteractive` per il launcher: entrerebbe in competizione con il tuo codice per niente.
## impostare l’aspetto nel codice
L’aspetto che pubblichi nella dashboard viaggia dentro il launcher. Se preferisci tenerlo nel repository, imposta `window.Spookat` prima che il launcher venga eseguito. La configurazione della pagina vince su quella della dashboard.
L’ordine di caricamento conta: la configurazione deve esistere quando il launcher parte. Con `next/script`, dai `beforeInteractive` alla configurazione (consentito nel layout principale) e `afterInteractive` al launcher:
```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}
);
}
```
Gli script `beforeInteractive` girano prima dell’idratazione, quelli `afterInteractive` dopo, quindi l’ordine è garantito. Le chiavi sono le stesse di ovunque: `style` (uno dei 8), `font`, `accent`, `side`, `greeting`, `label`, `lang`. La [documentazione](/it/docs/) le elenca tutte.
## il pages router
Con il pages router, il wrapper condiviso è `pages/_app.tsx`:
```tsx
import type { AppProps } from "next/app";
import Script from "next/script";
export default function App({ Component, pageProps }: AppProps) {
return (
<>
);
}
```
Per una configurazione, nel pages router gli script `beforeInteractive` vanno in `pages/_document.tsx`. Metti lì lo script di `window.Spookat`, dentro ``, con lo stesso `id` e la stessa `strategy` di sopra, e lascia il launcher in `_app.tsx`.
## l’utente connesso
Da pro in su, puoi dire alla chat chi ha effettuato l’accesso. Il tuo team vedrà `logged in as 42` sulla scheda di Slack, e i webhook, l’export e il `read_convo` del tuo agente porteranno l’id. L’id viene firmato con un segreto che conosce solo il tuo server, così nessuno può fingersi qualcun altro.
Crea il segreto di identità nella pagina di installazione della dashboard, mettilo in una variabile d’ambiente e firma sul server. Con l’app router il layout principale è un componente server, il che rende tutto semplice:
```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 && (
)}
);
}
```
Non calcolare mai la firma in un componente client: il segreto finirebbe nel browser. Una firma mancante o sbagliata non è un errore; semplicemente la chat non dice chi è. Leggere la sessione nel layout principale fa renderizzare ogni pagina a ogni richiesta, quindi se oggi il tuo layout è statico, valutalo prima di aggiungerlo.
## content security policy
Se la tua app invia un header `Content-Security-Policy`, il widget ha bisogno di:
- `script-src` e `style-src`: `https://cdn.spookat.com`
- `font-src`: `https://cdn.spookat.com`, se hai scelto un font ospitato
- `connect-src`: `wss://api.spookat.com`, per la connessione della chat dopo un clic
- `img-src`: `data:`, per i loghi e le foto del team
- `style-src`: il launcher inietta un piccolo blocco `