채팅 SDK

웹사이트에 쉽게 통합할 수 있는 실시간 채팅 위젯입니다. Shadow DOM을 활용하여 호스트 페이지와 격리된 환경에서 동작하며, 설치 및 커스터마이징이 간편합니다.

주요 기능

• 독립성: Shadow DOM 격리로 호스트 페이지 영향 최소화
• 경량성: Vite 기반 번들, CDN 배포로 로딩 최적화
• 확장성: TanStack Query로 실시간 업데이트, TanStack Router로 내부 화면 전환 관리

설치 방법

CDN 방식

<script src="https://cdn.example.com/chat-sdk.js"></script>
<script>
  window.ChatSDK.init({
    headerTitle: "고객 상담",
    primaryColor: "#3B82F6",
    secondaryColor: "#10B981",
    position: "bottom-right"
  });
</script>

NPM 방식

npm install chat-sdk
# 또는
yarn add chat-sdk
# 또는
pnpm add chat-sdk

import { initChatSDK } from 'chat-sdk';

initChatSDK({
  headerTitle: "고객 상담",
  primaryColor: "#3B82F6",
  secondaryColor: "#10B981",
  position: "bottom-right"
});

설정 옵션

| 옵션 | 타입 | 기본값 | 설명 | |------|------|--------|------| | headerTitle | string | "고객 상담" | 채팅창 상단에 표시되는 제목 | | primaryColor | string | "#3B82F6" | 주요 색상 (버튼, 헤더 등) | | secondaryColor | string | "#10B981" | 보조 색상 | | position | string | "bottom-right" | 위젯 위치 ("bottom-right", "bottom-left", "top-right", "top-left") | | initialOpen | boolean | false | 초기 로드 시 채팅창 자동 열림 여부 | | customIcon | ReactNode | null | 커스텀 아이콘 (React 컴포넌트) | | customText | string | null | 버튼에 표시될 커스텀 텍스트 | | apiKey | string | null | API 키 (인증용) | | organizationId | string | null | 조직 ID | | theme | object | {} | 테마 설정 객체 | | initialMessage | string | null | 초기 시스템 메시지 | | inquiryTypes | array | [] | 문의 유형 목록 | | onChatStart | function | null | 채팅 시작 시 호출될 콜백 | | onChatEnd | function | null | 채팅 종료 시 호출될 콜백 | | onMessageSent | function | null | 메시지 전송 시 호출될 콜백 | | onMessageReceived | function | null | 메시지 수신 시 호출될 콜백 |

API 메서드

채팅창 열기

// 전역 객체 사용
window.ChatSDK.open();

// 또는 인스턴스 사용
const chatInstance = initChatSDK({...});
chatInstance.open();

채팅창 닫기

// 전역 객체 사용
window.ChatSDK.close();

// 또는 인스턴스 사용
const chatInstance = initChatSDK({...});
chatInstance.close();

SDK 제거

// 전역 객체 사용
window.ChatSDK.destroy();

// 또는 인스턴스 사용
const chatInstance = initChatSDK({...});
chatInstance.destroy();

이벤트 리스닝

// 초기화 시 이벤트 핸들러 등록
initChatSDK({
  onChatStart: () => {
    console.log('채팅창이 열렸습니다.');
  },
  onChatEnd: () => {
    console.log('채팅창이 닫혔습니다.');
  },
  onMessageSent: (message) => {
    console.log('메시지 전송:', message);
  },
  onMessageReceived: (message) => {
    console.log('메시지 수신:', message);
  }
});

// 또는 DOM 이벤트 리스너 사용
document.addEventListener('chat-sdk:open', () => {
  console.log('채팅창이 열렸습니다.');
});

document.addEventListener('chat-sdk:close', () => {
  console.log('채팅창이 닫혔습니다.');
});

document.addEventListener('chat-sdk:message', (event) => {
  console.log('메시지 이벤트:', event.detail);
});

개발 환경 설정

# 의존성 설치
pnpm install

# 개발 서버 실행
pnpm dev

# 데모 페이지 실행
pnpm demo

# 빌드
pnpm build

# 린트 검사
pnpm lint

기술 스택

• React
• TypeScript
• TanStack Query (실시간 데이터 관리)
• TanStack Router (내부 라우팅)
• Zustand (상태 관리)
• Tailwind CSS (스타일링)
• Vite (번들링)
• Shadow DOM (격리된 렌더링 환경)

라이선스

MIT