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

はじめに

Klleon Chat SDK を使って Web アプリケーションにアバターチャット機能を統合するのはとても簡単です。このガイドでは、SDK を使うための事前準備からインストール、基本的な初期化方法までをステップごとに紹介します。

事前準備​

Klleon Chat SDK を使用する前に、以下の準備が必要です：

  1. Klleon Studio アカウント：Klleon Studioのアカウントが必要です。まだお持ちでない場合は、アカウントを作成してください。
  2. ドメイン登録：SDK を使用する Web サイトのドメインを Klleon Studio に登録してください。
    • ログイン後、「SDK 管理」メニューから登録可能です。
    • 登録に問題がある場合は partnership@klleon.io にお問い合わせください。
  3. SDK キーの発行：ドメイン登録後、そのドメインで使用可能な sdk_key が発行されます。SDK 初期化時に必要です。
  4. アバター ID の確認：使用したいアバターの avatar_id を確認してください。Klleon Studio のアバター一覧ページから確認できますが、このページで ID をコピーできるアバターのみが SDK 連携に使用可能です。

SDK のインストール​

Klleon Chat SDK は、Web ページに <script> タグを追加することで簡単に導入できます。

HTML の <head> タグ内に次のスクリプトを追加してください：

index.html (SDKのインストール)
<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Klleon Chat SDK はじめに</title>
    <!-- Klleon Chat SDKスクリプトの追加 ({VERSION}は実際のバージョンに置き換え) -->
    <script src="https://web.sdk.klleon.io/{VERSION}/klleon-chat.umd.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
SDK バージョンの確認

{VERSION} には X.Y.Z 形式の実際の SDK バージョンを入力してください（例：1.0.0）。
利用可能な最新バージョンは Klleon Studio の「SDK 管理」ページまたは通知チャンネルで確認できます。特定バージョンが必要な場合は明示してください。

SDK の初期化​

SDK スクリプトがロードされた後、window.KlleonChat.init() メソッドを使って SDK を初期化します。DOM が準備された後やメインスクリプト内で呼び出すのが一般的です。

初期化には sdk_key と avatar_id の 2 つのオプションが必須です（イベントリスナーを先に登録してから init を呼ぶのが推奨されます）。

App.tsx (React)
import { useEffect } from "react";

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

    const init = async () => {
      // 1. ステータスイベントリスナー登録
      KlleonChat.onStatusEvent((status) => {
        if (status === "VIDEO_CAN_PLAY") {
          console.log("アバターの動画再生準備完了！");
        }
      });

      // 2. チャットイベントリスナー登録
      KlleonChat.onChatEvent((chatData) => {
        console.log("SDKチャットイベント:", chatData);
      });

      // 3. SDK初期化
      await KlleonChat.init({
        sdk_key: "YOUR_SDK_KEY",
        avatar_id: "YOUR_AVATAR_ID",
      });
    };
    init();
  }, []);

  return <></>;
}

export default App;

初期化オプション（InitOption）​

init() メソッドは、さまざまなオプションをオブジェクト形式で受け取り、SDK の動作を制御します。主なオプションは以下の通りです：

parametertyperequireddefaultdescription
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を通じて発行されたユーザーセッション管理用キーです。セッション時間調整などに使用されることがあります。
user_key の使用について

user_key は End-User API を通じて管理される機能です。使用を希望される場合は、Klleon Studio に登録のうえ partnership@klleon.io にご連絡ください。

すぐ試せる：全体の例​

以下は、Klleon Chat SDK を Web ページに導入し、イベントを登録して初期化する基本的な例です。
環境は VITE + React です。
（動作させるには YOUR_SDK_KEY と YOUR_AVATAR_ID を有効な値に置き換えてください）

index.html
<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vite + React</title>
    <script src="https://web.sdk.klleon.io/1.0.0/klleon-chat.umd.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
App.tsx
import { useEffect, useRef, type CSSProperties } from "react";

interface AvatarProps {
  videoStyle?: CSSProperties;
  volume?: number;
}

interface ChatProps {
  delay?: number;
  type?: "voice" | "text";
  isShowCount?: boolean;
}

function App() {
  const avatarRef = useRef<HTMLElement & AvatarProps>(null);
  const chatRef = useRef<HTMLElement & ChatProps>(null);

  useEffect(() => {
    const { KlleonChat } = window;

    const init = async () => {
      KlleonChat.onStatusEvent((status) => {
        if (status === "VIDEO_CAN_PLAY") {
          console.log("アバターの動画再生準備完了！");
        }
      });

      KlleonChat.onChatEvent((chatData) => {
        console.log("SDKチャットイベント:", chatData);
      });

      await KlleonChat.init({
        sdk_key: "YOUR_SDK_KEY",
        avatar_id: "YOUR_AVATAR_ID",
      });
    };
    init();

    if (avatarRef.current) {
      avatarRef.current.videoStyle = {
        borderRadius: "30px",
        objectFit: "cover",
      };
      avatarRef.current.volume = 100;
    }

    if (chatRef.current) {
      chatRef.current.delay = 30;
      chatRef.current.type = "text";
      chatRef.current.isShowCount = true;
    }

    return () => {
      KlleonChat.destroy();
    };
  }, []);

  return (
    <div
      style={{
        display: "flex",
        width: "600px",
        height: "720px",
        gap: "0px 24px",
      }}
    >
      <avatar-container
        ref={avatarRef}
        style={{ flex: 1 }}
        class=""
      ></avatar-container>
      <chat-container
        ref={chatRef}
        style={{ flex: 1 }}
        class="rounded-3xl"
      ></chat-container>
    </div>
  );
}

export default App;

実行例​