주요 기능
기획서 기반으로 구현된 위젯의 핵심 기능들입니다.
인사 말풍선
위젯 닫힌 상태에서 트리거 버튼 위에 인사 메시지를 표시합니다. 운영시간에 따라 활성/비활성 상태가 전환됩니다.
홈 화면
브랜드 정보, 운영시간, 새 문의 시작, 문의 내역 목록을 보여줍니다. 문의하기 영역은 접기/펼치기가 가능합니다.
실시간 채팅
WebSocket 기반 실시간 메시지 송수신. 상담원/고객 메시지를 구분하고 타이핑 인디케이터를 지원합니다.
Plugin Key 인증
X-Session-Token 기반 세션 관리. boot API로 세션을 초기화하고, 멤버 인증(identify)을 지원합니다.
파일 & 이미지
이미지 썸네일 프리뷰, 파일 카드 UI를 지원합니다. presign → S3 업로드 → CDN URL 플로우로 최대 10MB 첨부 가능합니다.
문의 내역
지난 상담 내역을 서버에서 실시간 로드합니다. 읽지 않은 메시지 뱃지, 최신순 정렬, 스켈레톤 로딩을 지원합니다.
보안
Shadow DOM 격리, XSS 방지 (textContent), fileUrl 검증, CSP nonce, GDPR autoStart 게이트를 지원합니다.
WebSocket 최적화
25초 heartbeat, 지연 연결 (열 때만), Tab Visibility / Network 감지, 무제한 재연결, pagehide 정리를 적용합니다.
Quick Start
CDN 스크립트 한 줄로 어떤 웹사이트에든 삽입할 수 있습니다.
<script src="https://cdn.talk.zeroworks.ai/latest/chat-widget.iife.js"></script>
<!-- 2. 초기화 -->
<script>
ZeroTalk.init({
pluginKey: "pk_your_key_here",
title: "고객지원",
});
</script>
Public API
window.ZeroTalk 글로벌 객체로 위젯을 제어합니다.
| 메서드 | 설명 |
|---|---|
init(options) |
위젯 초기화 및 마운트. pluginKey 필수. |
destroy() |
위젯 언마운트 및 리소스 정리. |
getInstance() |
현재 위젯 인스턴스 반환. 없으면 null. |
.open() |
채팅 윈도우 열기. |
.close() |
채팅 윈도우 닫기. |
.toggle() |
열기/닫기 토글. |
.start() |
SDK 세션 시작. autoStart: false 사용 시 호출. |
Options
init() 호출 시 전달하는 설정 옵션입니다.
| 옵션 | 타입 | 설명 |
|---|---|---|
pluginKey |
string (필수) | 워크스페이스 플러그인 키 |
title |
string | 헤더에 표시할 브랜드명 (기본: "Chat") |
theme |
Partial<ThemeTokens> | CSS 변수 오버라이드 (--zerotalk-primary 등) |
apiBaseUrl |
string | API 엔드포인트 (기본: /api/v1) |
wsUrl |
string | WebSocket 엔드포인트 (기본: /ws) |
memberId |
string | 로그인한 사용자 식별자 |
memberHash |
string |
HMAC-SHA256(memberId, identity_verification_secret) — secret은 SDK Key
생성 시 1회 발급되는 secret_key(고객사 백엔드에만 저장)이며, 페이지에
노출된 pluginKey를 secret으로 사용하면 안 됩니다. 해시는 반드시 고객사
서버에서 계산해 클라이언트로 전달하세요.
|
cspNonce |
string | CSP nonce (strict CSP 사이트 호환) |
autoStart |
boolean | false 시 boot 지연 (GDPR 동의 게이트). 기본: true |
Architecture
Vanilla TypeScript, 프레임워크 의존성 없이 구현되었습니다.
기술 스펙
빌드 및 배포 환경입니다.
| 항목 | 내용 |
|---|---|
| 번들 포맷 | IIFE (단일 JS 파일) |
| 빌드 도구 | Vite 6 (Library Mode) |
| 언어 | TypeScript (strict) |
| 스타일 | Shadow DOM 내 CSS-in-JS, Figma 디자인 토큰 |
| CDN | AWS S3 + CloudFront (OAC) |
| 인증 | X-Session-Token (Plugin Key boot) |
| 실시간 | WebSocket (25초 heartbeat, 무제한 재연결, 지연 연결) |
| 번들 크기 | ~93KB (gzip ~24KB) |
| 입력 제한 | 최대 2,000자, Enter 전송 / Shift+Enter 줄바꿈 |
| 보안 | XSS 방지, CSP nonce, GDPR autoStart, URL 검증 |
테스트
Kent Beck TDD 방식으로 기획 스펙 기반 테스트를 작성했습니다.
| 파일 | 범위 | 테스트 수 |
|---|---|---|
| styles-spec | Figma CSS 스펙 일치 검증 | 42 |
| api | boot, 채널, 메시지, WS auth, destroy | 24 |
| container | 뷰 전환, 탭바, 나가기 플로우, API 안전성 | 22 |
| home | 브랜드, 운영시간, 문의 내역, 스켈레톤 | 23 |
| chat | 메시지 그룹핑, 한국어 시간, 파일/이미지 | 18 |
| trigger | FAB, 인사 말풍선, 온라인/오프라인 상태 | 15 |
| input-area | 구성 요소, 전송, 2000자 제한 | 14 |
| websocket | heartbeat, 지연 연결, visibility, network | 12 |
| exit-confirm | 다이얼로그 구성, CSS 클래스 토글 | 10 |
| emoji-picker | 검색, 카테고리, 선택 | 9 |
| file-upload | presign, S3, complete 플로우 | 6 |