위젯 설치 가이드

준비

위젯을 연결할 프로젝트가 필요합니다. CRM에서 해당 조직의 관리자 권한으로 로그인하세요.

위젯 켜고 허용 도메인 등록

프로젝트의 피드백 → 위젯 설정으로 이동해 위젯을 켜고 사이트 도메인을 추가합니다. example.com을 허용하면 하위 도메인도 허용됩니다. 포트 번호는 비교에서 무시됩니다. 도메인은 최대 20개까지 등록할 수 있습니다. 로컬에서 시험하려면 localhost도 추가하세요.

미리보기로 확인

미리보기는 저장하지 않은 변경 사항을 반영합니다. 데스크톱과 모바일 폭을 바꾸어 확인할 수 있습니다. 미리보기에서 보낸 피드백은 저장되지 않습니다.

스니펫 복사

설정을 저장한 뒤 설치 스니펫을 복사하세요. 스니펫은 저장된 표시 방식에 맞춰 생성됩니다. 모든 페이지에서 공유하는 레이아웃의 </body> 직전에 추가하는 것이 좋습니다.

표시 방식별 설치

떠 있는 버튼

화면 가장자리에 위젯 버튼을 표시합니다.

<script src="https://crm.theseeker.io/js/feedback.js" data-key="fbw_공개키" defer></script>

인라인

위젯을 렌더링할 요소를 만들고 data-target으로 선택자를 지정합니다.

<div id="feedback-widget"></div>
<script src="https://crm.theseeker.io/js/feedback.js" data-key="fbw_공개키" data-target="#feedback-widget" defer></script>

수동 열기

떠 있는 버튼 대신 직접 만든 버튼으로 위젯을 엽니다.

<script src="https://crm.theseeker.io/js/feedback.js" data-key="fbw_공개키" defer></script>
<button type="button" data-theseeker-feedback-open>피드백 보내기</button>

코드에서 TheSeekerFeedback.open()을 호출해 열 수도 있습니다.

프레임워크별 설치

일반 HTML

공유 레이아웃의 닫는 </body> 태그 바로 앞에 스크립트를 넣습니다.

Next.js App Router

app/layout.tsx의 body 안에 next/script의 Script를 추가합니다. data-* 속성은 스크립트 요소에 전달됩니다.

import Script from "next/script";

export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
  return (
    <html lang="ko">
      <body>
        {children}
        <Script src="https://crm.theseeker.io/js/feedback.js" data-key="fbw_공개키" strategy="afterInteractive" />
      </body>
    </html>
  );
}

React와 Vite SPA

프로젝트 루트의 index.html에서 </body> 바로 앞에 스크립트를 넣습니다.

테마와 다크 모드

theme은 light, dark, system, auto 중 하나입니다. light와 dark는 해당 테마를 고정하고, system은 방문자의 운영체제 설정을 따릅니다. auto는 호스트 페이지의 테마를 감지합니다. 감지 순서는 <html> 또는 <body>의 dark·light 클래스, data-theme·data-color-scheme·data-mode 속성, 계산된 color-scheme, 운영체제의 prefers-color-scheme입니다. 페이지 속성 변경은 실시간으로 감지합니다.

next-themes에서 attribute="class"를 사용하면 <html>의 dark·light 클래스 변경을 감지하므로 위젯 테마를 auto로 두면 됩니다. 별도 연동 코드는 필요하지 않습니다.

사이트가 자체 테마 토글을 쓰고 있고 auto 감지 대상인 클래스나 속성을 바꾸지 않는다면, 테마를 바꾸는 시점에 setTheme()을 호출합니다.

// 사이트 테마 토글 핸들러 안에서 호출합니다.
window.TheSeekerFeedback?.setTheme(isDark ? "dark" : "light");

setTheme()은 light, dark, system, auto를 받습니다. 스크립트 태그의 data-theme 속성으로 초기 테마를 덮어쓸 수도 있습니다.

<script src="https://crm.theseeker.io/js/feedback.js" data-key="fbw_공개키" data-theme="dark" defer></script>

언어

위젯 문구는 한국어(ko)와 영어(en)를 지원합니다. 스크립트 태그의 data-locale 속성으로 언어를 고릅니다. 속성이 없으면 한국어로 표시해 기존 설치는 그대로 동작합니다.

<script src="https://crm.theseeker.io/js/feedback.js" data-key="fbw_공개키" data-locale="auto" defer></script>

사이트가 언어를 직접 바꾼다면 그 시점에 setLocale()을 호출합니다. ko, en, auto를 받습니다.

window.TheSeekerFeedback?.setLocale(isEnglish ? "en" : "ko");

한국어 문구는 위젯 설정 → 문구와 연락처의 기본 문구를 씁니다. 영어 문구는 같은 화면의 문구 언어를 English로 바꿔 입력합니다. 비워 둔 영어 문구와 첨부·오류 같은 내장 문구는 영어 기본 문구로 표시합니다. 미리보기의 언어 전환으로 두 언어를 모두 확인할 수 있습니다.

모양 맞추기

CRM의 피드백 → 위젯 설정에서 테마별 색상, 세부 팔레트, 모서리 반경, 글꼴, 문구와 연락처 입력 방식을 설정하고 미리보기에서 확인합니다. 코딩 에이전트에 사이트 디자인 분석과 설정을 맡기려면 AI 에이전트로 위젯 디자인 맞추기를 참고하세요.

로그인 사용자 연결과 가리기

로그인한 사용자를 식별하려면 data-user-id에 애플리케이션의 사용자 ID를 지정하거나 TheSeekerFeedback.setUser(id)를 호출합니다.

<script src="https://crm.theseeker.io/js/feedback.js" data-key="fbw_공개키" data-user-id="user-123" defer></script>

위젯의 스크린샷 캡처·업로드는 종료되었습니다. multipart screenshot 파트나 JSON screenshot 필드를 보내면 400 SCREENSHOT_DISABLED를 반환합니다. 기존 스크린샷은 갤러리에서 계속 확인할 수 있습니다.

data-feedback-mask는 analytics 스크립트의 에러 트래킹 breadcrumb에서 해당 요소 내부의 클릭 텍스트를 제외하는 데 계속 사용합니다. 입력 필드의 값은 수집하지 않습니다. 자세한 동작은 에러 트래킹을 참고하세요.

<span data-feedback-mask>민감한 정보</span>

동작 확인과 문제 해결

브라우저 개발자 도구의 콘솔에서 [theseeker feedback] 위젯을 불러오지 못했습니다:로 시작하는 경고를 확인하세요.

설정 변경은 서버 캐시로 최대 약 30초 뒤 반영될 수 있습니다. 스크립트 파일 변경은 브라우저 캐시로 최대 5분이 걸릴 수 있습니다.

AI 에이전트·API·MCP로 설치

AI 에이전트로 위젯 설치 문서의 프롬프트를 사용하거나 Feedback API 레퍼런스에서 REST 설정 방법을 확인하세요.

모바일 앱에 설치

React Native·Expo 앱에는 앱 위젯 설치 가이드를 따라 SDK를 설치하고 앱 ID를 등록하세요.