Klleon SDK

한국어

English
日本語

한국어

English
日本語

테마

시작하기 ​

실행 조건 ​

SDK를 사용하려면 아래 버전 이상이 필요합니다. 실행 전에 확인하세요.

브라우저최소 버전
Chrome / Edge92 이상
Firefox95 이상
Safari (iOS 포함)15.4 이상
Samsung Internet16 이상
  • HTTPS 필수 — HTTP 환경에서는 SDK가 사용하는 내부 브라우저 API가 없어 연결에 실패하며, 이 실패가 다른 에러로 잘못 진단될 수 있습니다. 로컬 개발 시 http://localhost는 예외적으로 허용됩니다.
  • 마이크 권한 — 음성 입력(STT)을 사용하려면 브라우저의 마이크 권한 허용이 필요합니다. enable_microphone: false로 초기화하면 권한을 요청하지 않으며, 음성 입력을 사용할 수 없습니다.

CDN으로 설치 ​

html
<script src="https://klleon.k1.klleon.io/{VERSION}/klleon-sdk.umd.js"></script>

{VERSION}을 실제 버전(예: 2.0.0)으로 교체하세요. 로드 후 window.KlleonSDK로 SDK에 접근합니다.

기본 사용법 ​

1. HTML에 컴포넌트 추가 ​

html
<avatar-container style="width: 400px; height: 400px;"></avatar-container>
<chat-container></chat-container>

2. 이벤트 구독 ​

onStatus는 init() 중 상태 변경을 수신하려면 init() 전에 등록하세요.

js
const SDK = window.KlleonSDK;

SDK.onStatus((status) => {
  console.log('상태 변경:', status);
});

SDK.onSignal((data) => {
  console.log('시그널:', data.signal, data.payload);
});

SDK.onError((error) => {
  console.error('에러:', error.code, error.message);
});
jsx
const [status, setStatus] = useState('IDLE');

useEffect(() => {
  const SDK = window.KlleonSDK;

  SDK.onStatus((s) => setStatus(s));
  SDK.onSignal((data) => console.log(data.signal, data.payload));
  SDK.onError((error) => console.error(error.code, error.message));
}, []);

3. SDK 초기화 ​

init()은 상태가 CONNECTED_FINISH로 전이된 직후 resolve됩니다. 초기화에 실패하면 상태는 IDLE로 돌아가며, 실패는 onStatus가 아니라 init()이 던지는 예외로만 알 수 있습니다.

js
SDK.init({
  sdk_key: 'YOUR_SDK_KEY',
  avatar_id: 'YOUR_AVATAR_ID',
}).catch((e) => console.error('초기화 실패:', e.message));
jsx
import { useEffect, useState } from 'react';

function App() {
  const [failed, setFailed] = useState(false);

  useEffect(() => {
    const SDK = window.KlleonSDK;
    SDK.init({
      sdk_key: 'YOUR_SDK_KEY',
      avatar_id: 'YOUR_AVATAR_ID',
    })
      .catch((e) => {
        setFailed(true);
        console.error('초기화 실패:', e.message);
      });

    return () => {
      // 이 콜백에서는 비동기 종료 완료를 기다릴 수 없으므로 종료 요청만 시작합니다
      SDK.destroy();
    };
  }, []);
}

4. 메시지 전송 ​

전송은 상태가 CONNECTED_FINISH가 된 뒤에 하세요. 미연결 상태(IDLE)에서 호출하면 예외 없이 무시되고 경고 로그만 남습니다. 연결이 진행 중일 때의 호출 결과는 보장되지 않으므로, 상태를 확인한 뒤 호출하거나 전송 UI를 비활성화하세요.

js
if (SDK.getStatus() === 'CONNECTED_FINISH') {
  SDK.sendMessage('안녕하세요');
}
jsx
// status는 2단계 onStatus로, failed는 3단계 init()의 catch에서 갱신한 값입니다
const isReady = status === 'CONNECTED_FINISH';
const label = failed ? '연결 실패' : isReady ? '대화 가능' : '연결 중';

return (
  <>
    <p>상태: {label}</p>
    <button
      onClick={() => window.KlleonSDK.sendMessage('안녕하세요')}
      disabled={!isReady}
    >
      전송
    </button>
  </>
);

5. SDK 종료 ​

destroy()는 비동기 함수입니다. 종료가 끝날 때까지 기다리려면 await하세요.

js
async function endSession() {
  await window.KlleonSDK.destroy();
}

React 컴포넌트의 cleanup 콜백처럼 await를 쓸 수 없는 곳에서는 종료 요청만 시작합니다.

음성 입력 ​

js
window.KlleonSDK.startListening(); // STT 시작
window.KlleonSDK.endListening();   // STT 종료

전체 예제 ​

html
<!DOCTYPE html>
<html>
<head>
  <script src="https://klleon.k1.klleon.io/{VERSION}/klleon-sdk.umd.js"></script>
</head>
<body>
  <avatar-container style="width: 400px; height: 600px;"></avatar-container>
  <chat-container></chat-container>

  <script>
    const SDK = window.KlleonSDK;

    SDK.onStatus((status) => {
      console.log('상태:', status);
    });

    SDK.onSignal((data) => {
      if (data.signal === 'RESPONSE_TEXT') {
        console.log('아바타:', data.payload.text);
      }
    });

    SDK.onError((error) => {
      console.error('에러:', error.code, error.message);
    });

    (async () => {
      try {
        await SDK.init({
          sdk_key: 'YOUR_SDK_KEY',
          avatar_id: 'YOUR_AVATAR_ID',
        });
        SDK.sendMessage('안녕하세요');
      } catch (e) {
        console.error('초기화 실패:', e.message);
      }
    })();
  </script>
</body>
</html>
jsx
import { useEffect } from 'react';

function App() {

  useEffect(() => {
    const SDK = window.KlleonSDK;

    SDK.onStatus((status) => console.log('상태:', status));
    SDK.onSignal((data) => console.log(data.signal, data.payload));
    SDK.onError((error) => console.error(error.code, error.message));

    SDK.init({
      sdk_key: 'YOUR_SDK_KEY',
      avatar_id: 'YOUR_AVATAR_ID',
    })
      .catch((e) => console.error(e.message));

    return () => {
      // 이 콜백에서는 비동기 종료 완료를 기다릴 수 없으므로 종료 요청만 시작합니다
      SDK.destroy();
    };
  }, []);

  return (
    <div>
      <avatar-container style={{ width: 400, height: 600 }} />
      <chat-container />
    </div>
  );
}

export default App;