SDK Method

Klleon Chat SDK は、Web アプリケーションとさまざまなインタラクションを可能にするメソッドを提供します。SDK の初期化からメッセージ送信、アバター制御まで、本ドキュメントで主要な機能をご紹介します。

SDK Lifecycle

SDK のライフサイクルを適切に管理することで、リソースリークを防ぎ、アプリケーションの安定性を高めることができます。

KlleonChat.init(options)

SDK を初期化し、サーバーとの接続を準備します。このメソッドはアプリケーションのロード時に一度だけ呼び出すことが推奨されます。

初期化オプション (options)：

parameter	type	required	default	description
sdk_key	string	O	-	クレオンスタジオで発行されたSDKキー
avatar_id	string	O	-	使用するアバターの固有ID
subtitle_code	string	X	ko_kr	アバター発話字幕言語設定です。 サポートコード: ko_kr (韓国語), en_us (英語), ja_jp (日本語), id_id (インドネシア語) など
voice_code	string	X	ko_kr	アバター発話音声言語設定です。
voice_tts_speech_speed	number	X	1.0	アバター発話速度調整機能です。 範囲: 0.5 ~ 2.0
enable_microphone	boolean	X	true	trueに設定すると、マイク権限の要求なしに音声入力機能を試みます。 (ブラウザのポリシーによって動作が異なる場合があります。)
log_level	string	X	debug	SDK内部ログの詳細レベルを設定します。設定されたレベルに応じて次のログが出力されます: - debug設定時: debug, info, warn, errorログすべて出力 (開発および詳細デバッグ用) - info設定時: info, warn, errorログ出力 - warn設定時: warn, errorログ出力 - error設定時: errorログのみ出力 - silent設定時: すべてのログ出力無効化 プロダクション配布時には、性能最適化および不要な情報露出防止のために"silent"の使用を推奨します。
custom_id	string	X	-	顧客システムで使用する独自のデバイス識別値またはその他のユーザー定義識別子を設定します。
user_key	string	X	-	クレオンスタジオのEnd-User生成APIを通じて発行されたユーザーセッション管理用キーです。セッション時間調整などに使用されることがあります。

注意

KlleonChat.init() は SDK インスタンスごとに一度だけ呼び出すことを推奨します。SDK は内部で重複初期化を防ぐロジックを持っており、複数回呼び出しても最初の一回のみが有効になります。最適なパフォーマンスと明確なコード管理のために、アプリケーションロード時の一回のみの使用を推奨します。

KlleonChat.destroy()

SDK が使用していたすべてのリソース（ソケット接続、WebRTC 接続、イベントリスナーなど）を解放し、完全に終了させます。

使用例：

App.tsx (SDK ライフサイクル管理)

import { useEffect } from "react";

const App = () => {
  useEffect(() => {
    const init = async () => {
      const { KlleonChat } = window;

      await KlleonChat.init({
        sdk_key: "YOUR_SDK_KEY",
        avatar_id: "YOUR_AVATAR_ID",
        subtitle_code: "ja_jp",
        voice_code: "ja_jp",
        voice_tts_speech_speed: 1.0,
        enable_microphone: true,
        log_level: "debug",
        custom_id: "YOUR_CUSTOM_ID",
        user_key: "YOUR_USER_KEY",
      });
    };

    init();

    return () => {
      window.KlleonChat.destroy();
    };
  }, []);
  return (
    <div>
      <avatar-container />
      <chat-container />
    </div>
  );
};

export default App;

メッセージ送信

KlleonChat.sendTextMessage(text)

ユーザーが入力したテキストメッセージをアバターに送信します。

• text (string, 必須)：送信するメッセージテキスト。

使用例：

App.tsx (sendTextMessage)

import { useRef } from "react";

const App = () => {
  const inputRef = useRef<HTMLInputElement>(null);

  const handleSend = () => {
    const text = inputRef.current?.value.trim();
    if (text) {
      window.KlleonChat.sendTextMessage(text);
      inputRef.current.value = "";
    }
  };
  return (
    <div>
      <avatar-container />
      <chat-container />
      <input ref={inputRef} type="text" placeholder="メッセージを入力" />
      <button onClick={handleSend}>送信</button>
    </div>
  );
};

音声入力（STT: Speech-to-Text）

ユーザーの音声をテキストに変換し、アバターに送信する機能です。startStt() で録音を開始し、endStt() で録音を終了して送信します。

マイク権限

音声対話機能を使用するには、ブラウザのマイク使用許可が必要です。init() 時に enable_microphone: true を設定してください（デフォルトで true）。

KlleonChat.startStt() / KlleonChat.endStt()

• startStt()：マイクから音声データの収集を開始します。
• endStt()：音声収集を停止し、テキストに変換してアバターへ送信します。

使用例：

App.tsx (startStt, endStt)

import { useRef } from "react";

const App = () => {
  const isRecording = useRef(false);

  const handleRecord = () => {
    if (!isRecording.current) {
      window.KlleonChat.startStt();
      isRecording.current = true;
    } else {
      window.KlleonChat.endStt();
      isRecording.current = false;
    }
  };

  return (
    <div>
      <avatar-container />
      <button onClick={handleRecord}>録音開始 / 終了</button>
    </div>
  );
};

アバター発話制御

KlleonChat.cancelStt()

録音中の音声入力（startStt() の後）をキャンセルします。収集された音声データは送信されず、再び録音が可能な状態になります。

使用例：

App.tsx (cancelStt)

const handleCancel = () => {
  window.KlleonChat.cancelStt();
};

KlleonChat.stopSpeech()

アバターが現在話している音声（TTS）を即座に停止させます。

使用例：

App.tsx (stopSpeech)

const handleStopSpeech = () => {
  window.KlleonChat.stopSpeech();
};

エコー機能

KlleonChat.echo(text)

指定された text 文字列をアバターがそのまま発話（TTS）します。

• text (string, 必須)：アバターが話すテキストメッセージです。

使用例：

App.tsx (echo)

import { useRef } from "react";

const App = () => {
  const inputRef = useRef<HTMLInputElement>(null);

  const handleSend = () => {
    const text = inputRef.current?.value.trim();
    if (text) {
      window.KlleonChat.echo(text);
      inputRef.current.value = "";
    }
  };
  return (
    <div>
      <avatar-container />
      <chat-container />
      <input ref={inputRef} type="text" placeholder="メッセージを入力" />
      <button onClick={handleSend}>送信</button>
    </div>
  );
};

KlleonChat.startAudioEcho(audio) / KlleonChat.endAudioEcho()

• KlleonChat.startAudioEcho(audio)：Base64 でエンコードされた audio データを送信し、アバターに音声を発話させます。発話後は endAudioEcho() を呼び出す必要があります。
  • audio (string, 必須)：Base64 形式の音声データ（最大 0.1MB）
• KlleonChat.endAudioEcho()：オーディオエコーセッションを終了し、映像を自然に切り替えるための信号を送ります。

使用例：

App.tsx (startAudioEcho, endAudioEcho)

import { useRef } from "react";

const App = () => {
  const audioInputRef = useRef<HTMLTextAreaElement>(null);

  const handleStartAudioEcho = () => {
    const audioData = audioInputRef.current?.value.trim();
    if (audioData) {
      try {
        window.KlleonChat.startAudioEcho(audioData);
        console.log("オーディオエコー開始");

        setTimeout(() => {
          window.KlleonChat.endAudioEcho();
          console.log("オーディオエコー終了");
        }, 100);
      } catch (error) {
        console.error("オーディオエコー開始失敗:", error);
      }
    }
  };

  const handleMultipleAudioEcho = async () => {
    const audioList = [
      "base64_audio_data_1",
      "base64_audio_data_2",
      "base64_audio_data_3",
    ];

    try {
      for (const audio of audioList) {
        await window.KlleonChat.startAudioEcho(audio);
        console.log("オーディオ送信済み:", audio);
      }

      window.KlleonChat.endAudioEcho();
      console.log("すべてのオーディオエコー終了");
    } catch (error) {
      console.error("オーディオエコー処理失敗:", error);
    }
  };

  return (
    <div>
      <avatar-container />
      <chat-container />
      <textarea
        ref={audioInputRef}
        placeholder="Base64 オーディオデータを入力"
        rows={4}
        cols={50}
      />
      <button onClick={handleStartAudioEcho}>単一オーディオエコー</button>
      <button onClick={handleMultipleAudioEcho}>連続オーディオエコー</button>
    </div>
  );
};

End Audio Echo の役割

endAudioEcho() はオーディオ発話の完了後、自然な映像遷移を促すために必要です。

呼び出さない場合：

• 映像の切り替えが不自然になる場合があります
• 一部の映像モードで待機映像に戻らない可能性があります

推奨使用法：

• 音声送信直後にすぐ呼び出す（完了待ちは不要）
• 複数音声を送信する場合は、最後の送信後に 1 回だけ呼び出す

アバター変更

KlleonChat.changeAvatar(option)

現在の SDK セッションを終了し、指定された option に基づき新しいアバターでセッションを開始します。

ChangeAvatarOption：

パラメータ	タイプ	必須かどうか	デフォルト値	説明
avatar_id	string	O	-	変更するアバターの固有ID
subtitle_code	string	X	初回接続値	アバター発話字幕言語設定です。 サポートコード: ko_kr (韓国語), en_us (英語), ja_jp (日本語), id_id (インドネシア語) など
voice_code	string	X	初回接続値	アバター発話音声言語設定です。
voice_tts_speech_speed	number	X	初回接続値	アバター発話速度調整機能です。 範囲: 0.5 ~ 2.0

使用例：

App.tsx (changeAvatar)

const App = () => {
  const handleChangeAvatar = () => {
    window.KlleonChat.changeAvatar({
      avatar_id: "YOUR_AVATAR_ID",
      subtitle_code: "ja_jp",
      voice_code: "ja_jp",
      voice_tts_speech_speed: 1.0,
    });
  };

  return (
    <div>
      <avatar-container />
      <chat-container />
      <button onClick={handleChangeAvatar}>アバター変更</button>
    </div>
  );
};

メッセージ一覧の管理

KlleonChat.clearMessageList()

SDK 内部のメッセージ一覧の状態をクリアします。主に <chat-container> などの SDK 提供 UI コンポーネントで使用され、表示中のメッセージを初期化します。 このメソッドはログをサーバーから削除するものではなく、クライアント側の UI 表示状態をリセットするものです。

使用例：

App.tsx (clearMessageList)

const App = () => {
  const handleClearMessageList = () => {
    window.KlleonChat.clearMessageList();
  };

  return (
    <div>
      <avatar-container />
      <chat-container />
      <button onClick={handleClearMessageList}>メッセージ一覧を初期化</button>
    </div>
  );
};