はじめに
動作要件
SDKは以下の環境で動作します。実行前に確認してください。
| ブラウザ | 最小バージョン |
|---|---|
| Chrome / Edge | 92以上 |
| Firefox | 95以上 |
| Safari（iOS含む） | 15.4以上 |
| Samsung Internet | 16以上 |
- 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;