イベント

イベント登録タイミング

コールバックは init() の前後いつでも登録できます。ただし、onStatus は init() 中の状態変更（CONNECTING、SOCKET_CONNECTED など）を受信するために、init() 呼び出し前に登録してください。

• 各タイプにつきコールバックは1つのみ登録可能で、最後の登録が以前のものを上書きします。
• destroy() 後もコールバックは保持されるため、再初期化時に再登録する必要はありません。

onSignal(callback)

サーバーから受信したシグナルを受け取ります。

JavaScript

SDK.onSignal((data) => {
  console.log(data.signal, data.payload);
});

React

useEffect(() => {
  window.KlleonSDK.onSignal((data) => {
    console.log(data.signal, data.payload);
  });
}, []);

コールバックパラメータ

フィールド	型	必須	説明
signal	string	O	シグナル種類
payload	object	X	シグナル別追加データ
id	string	O	シグナルUUID
type	string	O	"SESSION" | "INPUT" | "OUTPUT"

主要シグナル

会話フロー

シグナル	説明	payload
RESPONSE_TEXT	アバター応答テキスト	{ text: string, language: string }
STT_RESULT	音声認識結果	{ text: string }
RESPONSE_PREPARING	応答準備中（LLMリクエスト直前）	-
RESPONSE_STARTED	応答開始	-
RESPONSE_ENDED	応答完了	-
USER_SPEECH_STARTED	STTセッション内の発話区間開始（マイクはすでにオン）	-
USER_SPEECH_STOPPED	STTセッション内の発話区間終了（マイクはまだオン）	-
ERROR	サーバーエラー（セッション維持）	{ type: "STT_ERROR" | "LLM_ERROR" | ... }
REJECTED	入力拒否（セッション維持）	{ type: "STT_EMPTY" | "MODERATION" | ... }

セッション管理

シグナル	説明	payload
MATCH_WAITING	マッチング待機中（ローディングUI表示用）	-
SESSION_ENDED	セッション正常終了	-
SESSION_TIMED_OUT	セッションタイムアウト	-
TIME_EXHAUSTED	使用時間消費	-
QUOTA_EXCEEDED	同接quota超過	-
SUSPEND_WARNED	長時間待機警告	-

onStatus(callback)

SDK接続状態の変更を受け取ります。

JavaScript

SDK.onStatus((status) => {
  console.log('状態:', status);
  if (status === 'CONNECTED_FINISH') {
    console.log('アバター準備完了');
  }
});

React

const [status, setStatus] = useState('IDLE');

useEffect(() => {
  window.KlleonSDK.onStatus((s) => setStatus(s));
}, []);

onError(callback)

SDK内部エラー + サーバーエラーを受け取ります。

JavaScript

SDK.onError((error) => {
  console.error(error.code, error.message);
});

React

useEffect(() => {
  window.KlleonSDK.onError((error) => {
    console.error(error.code, error.message);
  });
}, []);

コールバックパラメータ

フィールド	型	必須	説明
code	string	O	エラーコード
message	string	X	詳細メッセージ

エラーコード詳細

初期化エラー（init失敗時）

コード	発生タイミング	message例
SOCKET_FAILED	SDKキー検証失敗またはWebSocket接続失敗	"Failed to connect: ..."
STREAMING_FAILED	ストリーミング接続失敗	"Failed to connect streaming: ..."

init失敗時、onError は呼び出されません。init() が Error をthrowするため、try/catch で処理してください。

ランタイムエラー（接続中に発生）

コード	発生タイミング	message例
SOCKET_DISCONNECTED_UNEXPECTEDLY	WebSocketエラー発生	"WebSocket disconnected unexpectedly"
STREAMING_FAILED	リモートトラック購読失敗	"Failed to subscribe to remote track"
STREAMING_DISCONNECTED_UNEXPECTEDLY	ストリーミング異常終了	"Streaming disconnected: NETWORK_ERROR"

サーバーエラー

コード	発生タイミング	message例
SERVER_ERROR	サーバーから SERVER_ERROR シグナル受信	サーバーからのメッセージまたは "SERVER_ERROR"
WORKER_DISCONNECTED	サーバー接続終了シグナル受信	"WORKER_DISCONNECTED"

イベント登録例

JavaScript

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}`);
});

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

React

import { useEffect, useRef } from 'react';

function App() {
  const initialized = useRef(false);

  useEffect(() => {
    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}`);
    });

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

    return () => {
      if (initialized.current) SDK.destroy();
    };
  }, []);

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