이벤트 처리

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 상세

ChatData 객체 속성

onChatEvent 콜백을 통해 전달되는 ChatData 객체의 속성은 다음과 같습니다.

속성명	타입	설명
message	string	수신된 메시지의 내용입니다.
chat_type	string (ResponseChatType)	메시지의 종류를 나타냅니다. 가능한 값은 옆의 'ResponseChatType 값 상세' 탭을 참고하세요.
time	string	메시지가 발생한 시간의 문자열 표현입니다. (예: ISO 8601 형식)
id	string	메시지의 고유 식별자입니다.

ResponseChatType 값 상세

ChatData 객체의 chat_type 속성에 올 수 있는 값들과 그 의미는 다음과 같습니다. (BaseResponseChatType 참고)

ResponseChatType 값	설명
TEXT	아바타가 전송하는 텍스트 메시지입니다. 주로 KlleonChat.echo() 또는 KlleonChat.sendTextMessage() 메서드 사용 후 아바타의 응답으로 발생합니다.
STT_RESULT	사용자의 음성(STT)이 성공적으로 텍스트로 변환된 결과입니다.
STT_ERROR	사용자 음성(STT) 변환 또는 전송에 실패했을 때 발생합니다. 주로 음성 데이터가 없는 경우에 발생합니다.
WAIT	채팅 시작을 위해 대기 중일 때 발생합니다.
WARN_SUSPENDED	일정 시간(예: 10초) 동안 채팅이 없을 경우 곧 채팅이 중지될 것을 경고합니다.
DISABLED_TIME_OUT	장시간 채팅이 없어 세션이 중지되었을 때 발생합니다.
TEXT_ERROR	사용자가 보낸 텍스트 메시지 전송에 실패했을 때 발생합니다.
TEXT_MODERATION	사용자가 부적절한 언어를 사용하여 메시지가 필터링되었을 때 발생합니다.
ERROR	서버 측에서 일반적인 오류가 발생했을 때 전달됩니다. (예: 내부 서버 오류, 특정 요청 처리 실패 등)
PREPARING_RESPONSE	아바타가 사용자의 메시지에 대한 답변을 준비 중일 때 발생합니다.
RESPONSE_IS_ENDED	아바타의 한 턴(LLM이 생성한 여러 문장을 포함할 수 있는 응답)이 완전히 종료되었음을 알립니다.
RESPONSE_OK	아바타가 사용자 메시지에 대해 정상적으로 응답을 준비했거나 발화를 시작했음을 알립니다.
WORKER_DISCONNECTED	아바타 스트리밍 워커와의 연결이 끊어졌을 때 발생합니다.
EXCEED_CONCURRENT_QUOTA	허용된 최대 동시 접속자 수를 초과하여 연결이 거부되었을 때 발생합니다.
START_LONG_WAIT	지정된 시간 동안 사용자와의 상호작용이 없어 아바타가 긴 대기 상태로 전환될 때 발생합니다.
USER_SPEECH_STARTED	SDK가 사용자 음성 입력을 감지하기 시작했을 때 발생합니다.
USER_SPEECH_STOPPED	SDK가 사용자 음성 입력이 멈춘 것을 감지했을 때 발생합니다.

ChatData Flow

텍스트 메시지 전송

음성 메시지 전송

팁

onChatEvent를 통해 SDK의 기본 <chat-container>를 사용하지 않고, 실제로 애플리케이션에 맞는 커스텀 채팅창을 자유롭게 구축할 수 있습니다.

---

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가 초기화되었으나 아직 연결되지 않은 IDLE 상태입니다.
CONNECTING	세션 연결 전, sdk_key와 avatar_id를 검증하고 통과한 상태입니다.
CONNECTING_FAILED	올바르지 않은 sdk_key 또는 avatar_id 값으로 인해 검증에 실패한 상태입니다.
SOCKET_CONNECTED	웹소켓 서버에 성공적으로 연결된 상태입니다.
SOCKET_FAILED	웹소켓 서버 연결에 실패한 상태입니다.
STREAMING_CONNECTED	미디어 스트리밍(WebRTC) 서버에 성공적으로 연결된 상태입니다.
STREAMING_FAILED	미디어 스트리밍(WebRTC) 서버 연결에 실패한 상태입니다.
CONNECTED_FINISH	모든 연결(웹소켓, 스트리밍)이 성공적으로 완료된 상태입니다.
VIDEO_LOAD	아바타 비디오 데이터 로드가 시작된 상태입니다.
VIDEO_CAN_PLAY	아바타 비디오 재생이 가능하며, 대부분의 SDK 메서드를 호출할 수 있는 준비 상태입니다.

Status 이벤트 흐름

콜백 재등록

onChatEvent 또는 onStatusEvent를 동일한 이벤트 타입에 대해 여러 번 호출하면, 마지막으로 등록된 콜백 함수만 활성화됩니다. 즉, 새 콜백을 등록하면 이전 콜백은 자동으로 해제됩니다. 명시적인 off 메서드는 제공되지 않습니다.