@klever-one/web-sdk
Version:
Web SDK for integrating real-time room management and streaming functionality into web applications
291 lines (219 loc) • 8.47 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 19+ 버전이 필요합니다.
```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.10/dist/core/klever-one-core-v0.1.0-beta.10.umd.js"></script>
```
## 빠른 시작
### JavaScript/TypeScript
```javascript
import { KleverOneClient } from "@klever-one/web-sdk/core";
const client = new KleverOneClient({
apiKey: "your-api-key",
container: document.getElementById("streaming-container"),
callbacks: {
onReady: () => console.log("클라이언트 준비 완료!"),
onMessageReceived: (message) => console.log("AI:", message.content),
onConnectionStatusChange: (status) => console.log("상태:", status),
},
});
// 디지털 휴먼에 연결
await client.connect();
// 텍스트 메시지 전송
await client.sendText("안녕하세요, 어떻게 지내세요?");
// 음성 녹음 시작
await client.startRecording();
// 녹음 중지 및 전송
await client.stopRecording();
// 텍스트 음성 변환 전송
await client.speak("안녕하세요!");
```
### React
```jsx
import { useKleverOneClient } from "@klever-one/web-sdk/react";
function DigitalHumanChat() {
const containerRef = useRef < HTMLDivElement > null;
const { connect, disconnect, sendText, speak, state, messages } =
useKleverOneClient({
apiKey: "your-api-key",
container: containerRef.current,
callbacks: {
onMessageReceived: (message) => {
console.log("받은 메시지:", message.content);
},
},
});
return (
<div>
<div
ref={containerRef}
style={{ width: "100%", height: "500px" }}
/>
<button
onClick={connect}
disabled={state.connection === "connected"}
>
연결
</button>
<button onClick={() => sendText("안녕하세요!")}>메시지 전송</button>
<div>
{messages.map((msg, idx) => (
<div key={idx}>
<strong>{msg.role}:</strong> {msg.content}
</div>
))}
</div>
</div>
);
}
```
## 예제
프로젝트에 포함된 예제 파일들로 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>` |
### 상태 모니터링
```typescript
// 콜백을 통한 상태 모니터링
const client = new KleverOneClient({
apiKey: "your-api-key",
container: document.getElementById("container"),
callbacks: {
// 연결 상태 변화 감지
onConnectionStatusChange: (status) => {
console.log("상태:", status); // "connecting" | "connected" | "disconnected"
},
// 메시지 수신 이벤트
onMessageReceived: (message) => {
console.log("받은 메시지:", message.content);
},
// 녹음 상태 변화
onRecordingStatusChange: (status) => {
console.log("녹음 상태:", status); // "idle" | "recording" | "processing"
},
// 스트리밍 상태 변화
onStreamingStatusChange: (isStreaming) => {
console.log("스트리밍:", isStreaming);
},
// 방 정보 업데이트
onRoomInfoUpdated: (roomInfo) => {
console.log("방 정보:", roomInfo);
},
// 에러 처리
onError: (error: Error) => {
console.error("SDK 에러:", error);
},
// 디버깅 로그
onLog: (message: string) => {
console.log("SDK 로그:", message);
},
},
});
// 상태 직접 확인
const currentState = client.getState();
console.log("현재 상태:", currentState);
const metrics = client.getMetrics();
console.log("메트릭:", metrics);
```
## 링크
- **[전체 문서](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>