メインコンテンツまでスキップ

イベント処理

Klleon Chat SDK は、リアルタイムで発生するさまざまな状態変化やデータをアプリケーションに通知するためにカスタムイベントを使用します。これらのイベントを購読することで、SDK の動作に連動した動的な機能を実装できます。

イベントリスナーの登録と管理​

KlleonChat.onChatEvent(callback)​

アバターまたはユーザーに関連するチャットメッセージが発生した際に呼び出されるコールバック関数を登録します。このイベントを活用することで、SDK が提供する <chat-container> UI コンポーネントを使用せず、受信した ChatData に基づいた独自のチャットインターフェースを実装できます。

  • callback ((data: ChatData) => void, 必須): ChatData オブジェクトを引数に取るコールバック関数です。
function handleChatMessage(chatData) {
  console.log("新しいチャットメッセージ:", chatData);
}

window.KlleonChat.onChatEvent(handleChatMessage);

ChatData & ResponseChatType​

onChatEvent コールバックを通じて渡される ChatData オブジェクトのプロパティは以下のとおりです。

プロパティ名タイプ説明
message string 受信されたメッセージの内容です。
chat_type string (ResponseChatType) メッセージの種類を示します。可能な値は隣の 'ResponseChatType値詳細' タブを参照してください。
time string メッセージが発生した時間の文字列表現です。 (例: ISO 8601形式)
id string メッセージの固有識別子です。

ChatData の流れ​

テキストメッセージ送信​

音声メッセージ送信​

ヒント

onChatEvent を利用することで、SDK のデフォルト <chat-container> を使わずに、アプリケーションに最適化された独自のチャット UI を構築可能です。

KlleonChat.onStatusEvent(callback)​

SDK およびアバターの主要な状態変化時に呼び出されるコールバック関数を登録します。

  • callback ((status: Status) => void, 必須): SDK またはアバターの現在の状態を示す Status 文字列を受け取るコールバック関数です。
function handleSdkStatus(currentStatus) {
  console.log("SDKの状態が変化しました:", currentStatus);

  if (currentStatus === "VIDEO_CAN_PLAY") {
    console.log(
      "アバター映像の再生準備が完了しました！他のSDKメソッドが利用可能です。"
    );
  }
}

window.KlleonChat.onStatusEvent(handleSdkStatus);
SDK メソッドの利用条件

ほとんどの SDK メソッド（例: メッセージ送信、STT 機能など）は、アバターが正常に接続され 映像再生が可能な状態（VIDEO_CAN_PLAY）であることが前提条件です。この状態は onStatusEvent によって通知されます。

VIDEO_CAN_PLAY でない場合にメソッドを呼び出すと、期待通りに動作しないか、エラーが発生する可能性があります。

なお、KlleonChat.init() および onChatEvent、onStatusEvent の登録はこの条件の対象外です。

Status イベント引数の詳細​

タイプ説明
string (Status) SDKおよびアバターの現在の状態を示す文字列です。可能な値は下の 'Status値詳細' 表を参照してください。

Status の値の詳細​

Status値説明
IDLE SDKが初期化されたがまだ接続されていないアイドル状態です。
CONNECTING セッション接続前、sdk_keyとavatar_idを検証して通過した状態です。
CONNECTING_FAILED 正しくないsdk_keyまたはavatar_id値により検証に失敗した状態です。
SOCKET_CONNECTED WebSocketサーバーに正常に接続された状態です。
SOCKET_FAILED WebSocketサーバー接続に失敗した状態です。
STREAMING_CONNECTED メディアストリーミング(WebRTC)サーバーに正常に接続された状態です。
STREAMING_FAILED メディアストリーミング(WebRTC)サーバー接続に失敗した状態です。
CONNECTED_FINISH すべての接続(WebSocket、ストリーミング)が正常に完了した状態です。
VIDEO_LOAD アバタービデオデータの読み込みが開始された状態です。
VIDEO_CAN_PLAY アバタービデオの再生が可能で、ほとんどのSDKメソッドを呼び出すことができる準備状態です。

Status イベントの流れ​

コールバックの再登録

onChatEvent または onStatusEvent を同一のイベントタイプに対して複数回呼び出すと、最後に登録されたコールバック関数のみが有効になります。つまり、新しいコールバックを登録すると以前のものは自動的に解除されます。明示的な off メソッドは提供されていません。