Skip to main content

Getting Started

Integrating the Klleon Chat SDK into your web application is simple. This guide walks you through the prerequisites, installation steps, and the basic initialization process.

Prerequisites​

Before you begin, ensure the following:

  1. Klleon Studio Account: You'll need a Klleon Studio account. If you don’t have one, please register first.

  2. Register Your Domain: Add your web app's domain to Klleon Studio.

    • Login and navigate to the "SDK Management" menu.
    • For assistance, contact partnership@klleon.io.

  3. Get Your SDK Key: Once your domain is registered, you’ll receive a unique sdk_key required for initialization.

  4. Avatar ID: Each avatar has a unique avatar_id. Only avatars with copyable IDs on the avatar list can be used with the SDK.

Installing the SDK​

You can install the Klleon Chat SDK by adding a <script> tag to your HTML file:

index.html (Install SDK)
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Klleon Chat SDK Getting Started</title>
    <!-- Insert SDK script (replace {VERSION} with actual 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>

:::tip SDK Version Replace {VERSION} with the actual version number in X.Y.Z format (e.g., 1.0.0). You can find the latest version via Klleon Studio or official announcements. :::

SDK Initialization​

After the SDK is loaded, initialize it using window.KlleonChat.init(). Initialization typically happens after the DOM is ready, usually inside your main app script.

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

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

    const init = async () => {
      KlleonChat.onStatusEvent((status) => {
        if (status === "VIDEO_CAN_PLAY") {
          console.log("Avatar video ready!");
        }
      });

      KlleonChat.onChatEvent((chatData) => {
        console.log("SDK Chat Event:", chatData);
      });

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

  return <></>;
}

export default App;

Init Options​

The init() method accepts various configuration options:

ParameterTypeRequiredDefaultDescription
sdk_key string O - SDK key issued by Klleon Studio
avatar_id string O - Unique ID of the avatar to be used
subtitle_code string X ko_kr Avatar speech subtitle language setting.
Supported codes: ko_kr (Korean), en_us (English), ja_jp (Japanese), id_id (Indonesian), etc.
voice_code string X ko_kr Avatar speech voice language setting.
voice_tts_speech_speed number X 1.0 Avatar speech speed control feature.
Range: 0.5 ~ 2.0
enable_microphone boolean X true When set to true, attempts voice input without requesting microphone permission.
(Behavior may vary depending on browser policy.)
log_level string X debug Sets the detail level of SDK internal logs. Depending on the set level, the following logs are output:
- When set to debug: All debug, info, warn, error logs are output (for development and detailed debugging)
- When set to info: info, warn, error logs are output
- When set to warn: warn, error logs are output
- When set to error: Only error logs are output
- When set to silent: All log outputs are disabled
For production deployment, it is recommended to use "silent" to optimize performance and prevent unnecessary information exposure.
custom_id string X - Sets a custom device identifier or other user-defined identifier used in the client system.
user_key string X - User session management key issued through Klleon Studio's End-User creation API. It can be used for session time adjustment, etc.

:::tip About user_key The user_key is managed through the End-User API. Contact partnership@klleon.io for access and usage instructions. :::

Full Working Example​

Here’s a complete working example showing SDK installation, event handling, and initialization.

index.html
<!DOCTYPE html>
<html lang="en">
  <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 + TS + TailwindCSS</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("Avatar video ready!");
        }
      });

      KlleonChat.onChatEvent((chatData) => {
        console.log("SDK Chat Event:", 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;

Live Example​