# 위젯 설치 가이드 > 피드백 위젯의 허용 도메인을 설정하고 사이트에 설치하는 방법을 안내합니다. ## 준비 위젯을 연결할 프로젝트가 필요합니다. CRM에서 해당 조직의 관리자 권한으로 로그인하세요. ## 위젯 켜고 허용 도메인 등록 프로젝트의 **피드백 → 위젯 설정**으로 이동해 위젯을 켜고 사이트 도메인을 추가합니다. `example.com`을 허용하면 하위 도메인도 허용됩니다. 포트 번호는 비교에서 무시됩니다. 도메인은 최대 20개까지 등록할 수 있습니다. 로컬에서 시험하려면 `localhost`도 추가하세요. ## 미리보기로 확인 미리보기는 저장하지 않은 변경 사항을 반영합니다. 데스크톱과 모바일 폭을 바꾸어 확인할 수 있습니다. 미리보기에서 보낸 피드백은 저장되지 않습니다. ## 스니펫 복사 설정을 저장한 뒤 설치 스니펫을 복사하세요. 스니펫은 저장된 표시 방식에 맞춰 생성됩니다. 모든 페이지에서 공유하는 레이아웃의 `` 직전에 추가하는 것이 좋습니다. ## 표시 방식별 설치 ### 떠 있는 버튼 화면 가장자리에 위젯 버튼을 표시합니다. ```html ``` ### 인라인 위젯을 렌더링할 요소를 만들고 `data-target`으로 선택자를 지정합니다. ```html ``` ### 수동 열기 떠 있는 버튼 대신 직접 만든 버튼으로 위젯을 엽니다. ```html ``` 코드에서 `TheSeekerFeedback.open()`을 호출해 열 수도 있습니다. ## 프레임워크별 설치 ### 일반 HTML 공유 레이아웃의 닫는 `` 태그 바로 앞에 스크립트를 넣습니다. ### Next.js App Router `app/layout.tsx`의 `body` 안에 `next/script`의 `Script`를 추가합니다. `data-*` 속성은 스크립트 요소에 전달됩니다. ```tsx import Script from "next/script"; export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) { return ( {children} ``` ## 언어 위젯 문구는 한국어(`ko`)와 영어(`en`)를 지원합니다. 스크립트 태그의 `data-locale` 속성으로 언어를 고릅니다. 속성이 없으면 한국어로 표시해 기존 설치는 그대로 동작합니다. | 값 | 동작 | | --- | --- | | `ko` | 한국어로 표시합니다. 기본값입니다. | | `en` | 영어로 표시합니다. | | `auto` | 페이지 ``이 `en`으로 시작하면 영어, `ko`로 시작하면 한국어로 표시합니다. 둘 다 아니면 브라우저 언어를 보고, 그래도 정하지 못하면 한국어로 표시합니다. `lang` 속성이 바뀌면 바로 따라갑니다. | ```html ``` 사이트가 언어를 직접 바꾼다면 그 시점에 `setLocale()`을 호출합니다. `ko`, `en`, `auto`를 받습니다. ```js window.TheSeekerFeedback?.setLocale(isEnglish ? "en" : "ko"); ``` 한국어 문구는 **위젯 설정 → 문구와 연락처**의 기본 문구를 씁니다. 영어 문구는 같은 화면의 **문구 언어**를 English로 바꿔 입력합니다. 비워 둔 영어 문구와 첨부·오류 같은 내장 문구는 영어 기본 문구로 표시합니다. 미리보기의 언어 전환으로 두 언어를 모두 확인할 수 있습니다. ## 모양 맞추기 CRM의 **피드백 → 위젯 설정**에서 테마별 색상, 세부 팔레트, 모서리 반경, 글꼴, 문구와 연락처 입력 방식을 설정하고 미리보기에서 확인합니다. 코딩 에이전트에 사이트 디자인 분석과 설정을 맡기려면 [AI 에이전트로 위젯 디자인 맞추기](/feedback/ai-agent-setup#사이트-디자인에-맞추기)를 참고하세요. ## 로그인 사용자 연결과 가리기 로그인한 사용자를 식별하려면 `data-user-id`에 애플리케이션의 사용자 ID를 지정하거나 `TheSeekerFeedback.setUser(id)`를 호출합니다. ```html ``` 위젯의 스크린샷 캡처·업로드는 종료되었습니다. multipart `screenshot` 파트나 JSON `screenshot` 필드를 보내면 `400 SCREENSHOT_DISABLED`를 반환합니다. 기존 스크린샷은 갤러리에서 계속 확인할 수 있습니다. `data-feedback-mask`는 analytics 스크립트의 에러 트래킹 breadcrumb에서 해당 요소 내부의 클릭 텍스트를 제외하는 데 계속 사용합니다. 입력 필드의 값은 수집하지 않습니다. 자세한 동작은 [에러 트래킹](/analytics/errors#breadcrumbs와-개인정보)을 참고하세요. ```html 민감한 정보 ``` ## 동작 확인과 문제 해결 브라우저 개발자 도구의 콘솔에서 `[theseeker feedback] 위젯을 불러오지 못했습니다:`로 시작하는 경고를 확인하세요. | 콘솔 메시지 | 원인 | 해결 방법 | | --- | --- | --- | | `data-key 속성이 없습니다` | 스크립트에 키 속성이 없습니다. | CRM에서 복사한 스니펫에 `data-key`가 있는지 확인합니다. | | `HTTP 403` | 현재 페이지의 Origin이 허용 도메인에 없습니다. | 설정에 현재 호스트를 추가합니다. | | `HTTP 404` | 잘못된 키, 재발급된 키 또는 위젯이 꺼져 있습니다. | 현재 프로젝트의 키를 확인하고 위젯 활성 상태를 확인합니다. | | `인라인 위젯을 넣을 요소를 찾지 못했습니다` | 컨테이너가 없거나 `data-target` 선택자가 맞지 않습니다. | 컨테이너가 스크립트 실행 전에 존재하는지, 선택자가 실제 요소와 일치하는지 확인합니다. | 설정 변경은 서버 캐시로 최대 약 30초 뒤 반영될 수 있습니다. 스크립트 파일 변경은 브라우저 캐시로 최대 5분이 걸릴 수 있습니다. ## AI 에이전트·API·MCP로 설치 [AI 에이전트로 위젯 설치](/feedback/ai-agent-setup) 문서의 프롬프트를 사용하거나 [Feedback API 레퍼런스](/api-reference/feedback)에서 REST 설정 방법을 확인하세요. ## 모바일 앱에 설치 React Native·Expo 앱에는 [앱 위젯 설치 가이드](/feedback/app-install)를 따라 SDK를 설치하고 앱 ID를 등록하세요.