# next.js 사이트에 라이브 채팅 넣기
Spookat 채팅을 Next.js 앱에 넣어 보세요. App Router든 Pages Router든, 디자인과 로그인한 사용자까지 넘기고, 클릭 전에 저희 API로 요청이 0건인지 확인하는 방법을 정리했어요.
2026-11-04 · Kuba
Next.js에서 라이브 채팅은 루트 레이아웃의 script 태그 하나예요. 이 가이드에서는 App Router와 Pages Router에서 태그를 어디에 넣는지, 로드 순서를 깨지 않고 위젯 디자인과 로그인한 사용자를 넘기는 방법, Content Security Policy에 추가할 것, 그리고 프로덕션 빌드에서 결과를 확인하는 방법을 보여드려요.
## 짧게 말하면
App Router에서는 `app/layout.tsx`의 `` 안에 태그를 넣으세요.
```tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
`YOUR_SITE_KEY`는 대시보드 설치 페이지의 키로 바꾸세요. 디자인을 대시보드에서 관리한다면(기본값이에요) 설치는 이걸로 끝이에요. 이 가이드의 나머지는 더 세밀하게 제어하고 싶을 때를 위한 거예요. 처음부터 시작한다면 계정 쪽 내용은 [기본 가이드](/ko/blog/add-live-chat-to-your-website/)에 있어요.
## 왜 루트 레이아웃일까
루트 레이아웃은 모든 라우트를 감싸고, 사용자가 이동하는 동안에도 마운트된 상태로 남아요. 런처는 페이지에 한 번만 붙어요. 클라이언트 측 이동은 페이지를 새로고침하지 않으니 런처도 다시 로드되지 않고, 방문자는 여기저기 클릭하면서도 대화를 열어 둘 수 있어요.
태그를 페이지 컴포넌트에 넣으면 채팅은 그 페이지에만 있어요. 여러 페이지에서 렌더링되는 컴포넌트에 넣으면 강력 새로고침 때 중복이 생겨요(런처는 자기 두 번째 복사본을 무시하지만, 낭비되는 요청인 건 똑같아요).
## next/script로 넣기
`next/script`는 Next.js에서 서드파티 스크립트를 불러오는 방법이고, 여기서도 잘 동작해요.
```tsx
import Script from "next/script";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
`afterInteractive`는 하이드레이션 직후에 런처를 불러와요. `lazyOnload`는 브라우저가 한가해질 때까지 기다려서, 느린 휴대폰에서는 버튼이 조금 늦게 나타나요. 2 kb 런처라면 둘 다 괜찮지만, `afterInteractive`가 버튼을 더 빨리 보여줘요. 런처에 `beforeInteractive`는 쓰지 마세요. 괜히 여러분 코드와 경쟁하게 돼요.
## 코드에서 디자인 설정하기
대시보드에서 게시한 디자인은 런처 안에 담겨 와요. 저장소에서 관리하고 싶다면 런처가 실행되기 전에 `window.Spookat`을 설정하세요. 페이지 설정이 대시보드 설정보다 우선해요.
로드 순서가 중요해요. 런처가 실행될 때 설정이 이미 있어야 해요. `next/script`에서는 설정에 `beforeInteractive`(루트 레이아웃에서 허용돼요)를, 런처에 `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` 스크립트는 하이드레이션 전에, `afterInteractive` 스크립트는 그 후에 실행되니까 순서가 보장돼요. 키는 다른 곳과 같아요. `style`(8가지 중 하나), `font`, `accent`, `side`, `greeting`, `label`, `lang`. 전부 [문서](/ko/docs/)에 있어요.
## pages router
Pages Router에서 공통 래퍼는 `pages/_app.tsx`예요.
```tsx
import type { AppProps } from "next/app";
import Script from "next/script";
export default function App({ Component, pageProps }: AppProps) {
return (
<>
);
}
```
설정을 쓴다면, Pages Router에서 `beforeInteractive` 스크립트는 `pages/_document.tsx`에 들어가요. `window.Spookat` 스크립트를 그곳의 `` 안에, 위와 같은 `id`와 `strategy`로 넣고, 런처는 `_app.tsx`에 그대로 두세요.
## 로그인한 사용자
pro 이상에서는 누가 로그인했는지 채팅에 알려줄 수 있어요. 그러면 팀은 Slack 카드에서 `logged in as 42`를 보고, 웹후크, 내보내기, 에이전트의 `read_convo`에도 그 ID가 담겨요. ID는 여러분 서버만 아는 시크릿으로 서명되기 때문에, 누구도 다른 사람인 척할 수 없어요.
대시보드 설치 페이지에서 아이덴티티 시크릿을 만들고, 환경 변수에 넣고, 서버에서 서명하세요. App Router에서는 루트 레이아웃이 서버 컴포넌트라서 간단해요.
```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 && (
)}
);
}
```
서명은 절대 클라이언트 컴포넌트에서 계산하지 마세요. 시크릿이 브라우저로 넘어가요. 서명이 없거나 틀려도 오류는 아니고, 채팅이 누구인지 표시하지 않을 뿐이에요. 루트 레이아웃에서 세션을 읽으면 모든 페이지가 요청마다 렌더링돼요. 지금 레이아웃이 정적이라면 추가하기 전에 따져 보세요.
## content security policy
앱이 `Content-Security-Policy` 헤더를 보낸다면, 위젯에는 이게 필요해요.
- `script-src`와 `style-src`: `https://cdn.spookat.com`
- `font-src`: 호스팅된 폰트를 골랐다면 `https://cdn.spookat.com`
- `connect-src`: 클릭 후 채팅 연결을 위한 `wss://api.spookat.com`
- `img-src`: 로고와 팀원 사진을 위한 `data:`
- `style-src`: 런처는 자기 shadow root에 작은 `