Widget SDK

이 가이드는 웹사이트 어디에나 챗봇 위젯을 설치하고, 런타임에서 제어하는 방법을 설명합니다.

빠른 시작

아래 코드를 <head> 또는 <body> 끝에 붙여 넣기
identifier와 apiBase 값을 본인 환경에 맞게 변경

<script>
  window.DF_WIDGET_CONFIG = {
    identifier: "YOUR_CHATBOT_IDENTIFIER",
    apiBase: "https://your-app",
    // Optional
    // autoOpen: true,
    // language: "ko",
    // theme: "light",
    // ui: { position: "bottom-right", colors: { primary: "#111" } },
    // metadata: () => ({ user_id: "USER_123", plan: "pro" }),
    // context: () => ({ url: location.href, title: document.title })
  };
</script>
<script async src="https://your-app/widget.js"></script>

런타임 제어 (SDK)

<script>
  // 열기/닫기/토글
  window.DF_WIDGET.open();
  window.DF_WIDGET.close();
  window.DF_WIDGET.toggle();

  // 메시지 전송
  window.DF_WIDGET.send('안녕하세요!');

  // 언어/테마/스타일 변경
  window.DF_WIDGET.setLanguage('ko');
  window.DF_WIDGET.setTheme('dark');
  window.DF_WIDGET.updateUI({ colors: { primary: '#4f46e5' } });
</script>

설정 옵션

identifier (필수): 챗봇 식별자
apiBase (필수): API Origin(`/api/v1/embeds/*`, `/widget.js`)
autoOpen: 초기 자동 열기
language: ko | en
theme: light | dark | system
ui: 위치/색상/z-index/헤더/로고/Powered by 설정
metadata: 객체 또는 함수(사용자 ID, 플랜 등)
context: 객체 또는 함수(페이지 URL/타이틀 등)

보안/권장 사항

조직별 허용 도메인(Origin) 제한이 필요하면 서버에서 검증 추가
`/api/v1/embeds/chat`에 rate limit 권장
민감 데이터는 metadata에 넣지 않도록 주의

플랫폼별 설치는 Integration Guides를 참고하세요: 문서 인덱스