# @klever-one/web-sdk

[![Node.js](https://img.shields.io/badge/Node.js-22+-44CC11)](https://nodejs.org/)
[![npm version](https://img.shields.io/npm/v/@klever-one/web-sdk.svg)](https://www.npmjs.com/package/@klever-one/web-sdk)
[![License: UNLICENSED](https://img.shields.io/badge/License-UNLICENSED-red.svg)]()
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](https://www.typescriptlang.org/)
[![Documents](https://img.shields.io/badge/%F0%9F%8C%90%20Documents%20-0874B6)](https://docs.klever-one.com/)

디지털 휴먼과 실시간 상호작용을 위한 웹 SDK입니다. React Hook과 JavaScript로 쉽게 통합하세요.

## 설치

### npm/yarn/pnpm

> **주의**: React 사용 시 React 18+ 버전이 필요합니다.

```bash
# npm
npm install @klever-one/web-sdk

# yarn
yarn add @klever-one/web-sdk

# pnpm
pnpm add @klever-one/web-sdk
```

### CDN

```html
<script src="https://unpkg.com/@klever-one/web-sdk@0.1.0-beta.19/dist/core/klever-one-core-v0.1.0-beta.19.umd.js"></script>
```

## 예제

프로젝트에 포함된 예제 파일들로 SDK를 테스트하고 기능을 확인할 수 있습니다. `examples/` 디렉토리에서 다양한 사용 예제를 찾아보세요.

### SDK 사용 예제

완전한 SDK 최적화 구현은 `examples/digital-human-sdk-example.html`을 참조하세요:

- 터치 친화적 플로팅 액션 버튼
- 모바일 디바이스용 반응형 디자인
- 음성 녹음 및 텍스트 채팅
- Material Design 아이콘을 활용한 모던 UI

### WebView 통합

Flutter WebView 통합은 `examples/digital-human-webview-example.html`을 참조하세요:

- 최소한의 전체 화면 구현
- Flutter 통신 브리지
- 모바일 앱 통합에 최적화

> **팁**: `examples/` 디렉토리의 HTML 파일들을 다운로드하여 로컬에서 실행하면 SDK의 모든 기능을 즉시 테스트할 수 있습니다. 단, `your_api_key`를 실제 API 키로 바꿔 입력하세요.

## 주요 기능

**실시간 AI 대화** - 자연스러운 텍스트/음성 기반 대화  
**음성 인터랙션** - 브라우저 STT/TTS 완벽 지원  
**멀티 플랫폼** - React Hook + TypeScript  
**보안** - HTTPS/WSS 암호화 통신  
**반응형** - 모바일/태블릿/데스크톱 최적화

## 시스템 요구사항

### 필수 조건

- **보안 컨텍스트**: HTTPS 또는 localhost
- **WebRTC 지원**: Chrome 60+, Firefox 60+, Safari 12+
- **마이크 권한**: 음성 기능 사용 시

### 권장 사항

- **브라우저**: Chrome 최신 버전 (최적 성능)
- **네트워크**: 1Mbps 이상 안정적 연결
- **디바이스**: 마이크 지원 기기

## 아키텍처

```
 ┌─────────────────┐
 │   웹 애플리케이션   │
 └────────┬────────┘
          │
    ┌─────▼─────┐
    │ SDK Entry │
    │  Point    │
    └─────┬─────┘
          │
  ┌───────▼───────┐
  │KleverOneClient│
  └───────┬───────┘
          │
   ┌──────▼──────┐
   │  Services   │
   ├─────────────┤
   │RoomManager  │ ← WebSocket 연결
   │Streaming    │ ← WebRTC 스트리밍
   │Conversation │ ← AI 대화 처리
   │Recorder     │ ← 음성 녹음/처리
   └─────────────┘
```

## API 레퍼런스

### 연결 관리

| 메서드         | 설명             | 반환값          |
| -------------- | ---------------- | --------------- |
| `connect()`    | 디지털 휴먼 연결 | `Promise<void>` |
| `disconnect()` | 연결 종료        | `Promise<void>` |
| `isReady()`    | 준비 상태 확인   | `boolean`       |
| `getState()`   | 현재 상태 조회   | `ClientState`   |

### 대화 기능

| 메서드              | 설명               | 반환값          |
| ------------------- | ------------------ | --------------- |
| `sendText(message)` | 텍스트 메시지 전송 | `Promise<void>` |
| `speak(text)`       | TTS 음성 출력      | `Promise<void>` |
| `startRecording()`  | 음성 녹음 시작     | `Promise<void>` |
| `stopRecording()`   | 녹음 중지 및 전송  | `Promise<void>` |

## 링크

- **[전체 문서](https://docs.klever-one.com/)** - 상세한 API 문서 및 가이드
- **[Klever One Studio](https://www.klever-one.com/studio)** - 디지털 휴먼 생성 및 API 키 관리
- **[기술 지원](mailto:support@klever-one.com)** - 문의 및 지원

## 문제 해결

### 자주 발생하는 이슈

**HTTPS 오류**

```
Error: WebRTC requires HTTPS or localhost
```

→ HTTPS 환경 또는 localhost에서 실행하세요.

**마이크 권한 오류**

```
Error: Microphone permission denied
```

→ 브라우저에서 마이크 권한을 허용하세요.

**API 키 오류**

→ [스튜디오](https://www.klever-one.com/studio)에서 올바른 API 키를 확인하세요.

---

<div align="center">

**Klever One으로 차세대 디지털 경험을 시작하세요!**

[시작하기](https://docs.klever-one.com/) • [Studio](https://www.klever-one.com/studio) • [지원](mailto:support@klever-one.com)

</div>