Skip to main content

Klever One SDK 5분 완성 가이드

디지털 휴먼과의 첫 만남을 5분 안에 완성해보세요!

준비물​

  • API 키: Klever One 대시보드에서 발급받은 API 키
  • 웹 브라우저: Chrome, Safari, Edge 등 (HTTPS 환경 권장)
  • 마이크: 음성 대화 기능 사용 시 필요
중요!

마이크 사용과 WebRTC 연결을 위해 HTTPS 또는 localhost 환경에서만 정상 동작합니다.

방법 선택​

사용하는 환경에 따라 원하는 방법을 선택하세요:

HTML/JavaScript

웹페이지에 바로 추가

HTML 방법 보기

TypeScript/Node.js

타입 안전성이 필요한 프로젝트

TypeScript 방법 보기

️React

React 애플리케이션에 통합

React 방법 보기

HTML 방법​

가장 빠른 온보딩은 단일 HTML 파일에 SDK를 임베드하는 것입니다.

index.html
<!DOCTYPE html>
<html lang="ko">
  <body>
    <div
      id="avatar"
      style="width: 480px; height: 600px; margin: 0 auto;"
    ></div>

    <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>
    <script>
      const client = new KleverOneSdk.KleverOneClient({
        apiKey: "YOUR_API_KEY",
        container: document.getElementById("avatar"),
        callbacks: {
          onReady: () => client.sendText("안녕하세요!"),
          onMessageReceived: (message) => console.log(message.content),
          onError: (error) => console.error(error),
        },
      });

      client.connect();
    </script>
  </body>
</html>
  • YOUR_API_KEY를 Klever One 대시보드에서 발급받은 값으로 교체하세요.
  • HTTPS 또는 localhost에서 열면 바로 디지털 휴먼을 확인할 수 있습니다.

더 많은 UI 예시는 HTML/JavaScript 사용법에서 확인할 수 있습니다.

TypeScript 방법​

빠르게 시도하려면 Vite 템플릿에 다음 두 가지만 추가하면 충분합니다.

  1. SDK 설치

    npm install @klever-one/web-sdk

  2. src/main.ts 구성

    src/main.ts
    import { KleverOneClient } from "@klever-one/web-sdk/core";

    const client = new KleverOneClient({
      apiKey: import.meta.env.VITE_KLEVER_API_KEY,
      container: document.getElementById("avatar")!,
      callbacks: {
        onReady: () => client.sendText("안녕하세요!"),
      },
    });

    client.connect();

  3. index.html에 컨테이너만 두세요.

    index.html
    <body>
      <div
        id="avatar"
        style="width: 480px; height: 600px;"
      ></div>
      <script
        type="module"
        src="/src/main.ts"
      ></script>
    </body>

빌드/번들링 설정과 메시지 스트리밍 등 고급 기능은 TypeScript 사용법 문서에서 이어서 살펴보세요.

️React 방법​

React 앱에서는 훅 대신 가장 필요한 코드만으로 시작해보세요.

  1. 패키지 설치

    npm install @klever-one/web-sdk

  2. DigitalHuman 컴포넌트 생성

    src/DigitalHuman.tsx
    "use client";

    import { useEffect, useRef } from "react";
    import { KleverOneClient } from "@klever-one/web-sdk/core";

    interface DigitalHumanProps {
      apiKey: string;
    }

    export function DigitalHuman({ apiKey }: DigitalHumanProps) {
      const containerRef = useRef<HTMLDivElement>(null);

      useEffect(() => {
        if (!containerRef.current) {
          return;
        }

        const client = new KleverOneClient({
          apiKey,
          container: containerRef.current,
          callbacks: { onReady: () => client.sendText("안녕하세요!") },
        });

        client.connect();
        return () => client.disconnect();
      }, [apiKey]);

      return (
        <div
          ref={containerRef}
          style={{ width: 480, height: 600 }}
        />
      );
    }

  3. 앱에서 API 키만 넘겨주세요.

    src/App.tsx
    import { DigitalHuman } from "./DigitalHuman";

    export default function App() {
      return <DigitalHuman apiKey={import.meta.env.VITE_KLEVER_API_KEY} />;
    }

React 전용 훅과 스트리밍 UI는 React 사용법에서 이어서 확인하세요.

다음 단계​

  1. 환경 설정 가이드 - HTTPS 설정 및 문제 해결
  2. 상세 사용법 - 더 많은 기능과 커스터마이징

도움이 필요하신가요?​