@klever-one/web-sdk
Version:
Web SDK for integrating real-time room management and streaming functionality into web applications
164 lines (113 loc) • 5.28 kB
Markdown
# @klever-one/web-sdk
[](https://nodejs.org/)
[](https://www.npmjs.com/package/@klever-one/web-sdk)
[]()
[](https://www.typescriptlang.org/)
[](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.15/dist/core/klever-one-core-v0.1.0-beta.15.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>