본문으로 건너뛰기
버전: 1.3.0

이벤트 처리

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 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, onErrorEvent)는 이 전제 조건에서 제외됩니다.

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_FAILED 미디어 스트리밍(WebRTC) 서버 연결에 실패한 상태입니다.
CONNECTED_FINISH 모든 연결(웹소켓, 스트리밍)이 성공적으로 완료된 상태입니다.
VIDEO_LOAD 아바타 비디오 데이터 로드가 시작된 상태입니다.
VIDEO_CAN_PLAY 아바타 비디오 재생이 가능하며, 대부분의 SDK 메서드를 호출할 수 있는 준비 상태입니다.

Status 이벤트 흐름​

KlleonChat.onErrorEvent(callback)​

SDK 내부에서 발생하는 에러를 수신하기 위한 콜백 함수를 등록합니다. 네트워크 오류, 미디어 재생 실패 등 다양한 에러 상황을 감지하고 처리할 수 있습니다.

  • callback ((error: ErrorData) => void, 필수): ErrorData 객체({ code: ErrorCode; message: string })를 인자로 받는 콜백 함수입니다.
function handleError(error) {
  console.error("SDK 에러 발생:", error.code, error.message);
}

window.KlleonChat.onErrorEvent(handleError);

ErrorCode 상세​

에러 코드는 초기화 단계(init() 호출 시 발생)와 런타임 단계(VIDEO_CAN_PLAY 이후 발생)로 분류됩니다.

에러 코드발생 단계설명
SOCKET_FAILED 초기화 초기화 과정에서 WebSocket 연결에 실패했습니다. 서버에 접속할 수 없거나 네트워크가 불안정한 경우 발생합니다.
STREAMING_FAILED 초기화 초기화 과정에서 미디어 스트리밍(Agora) 연결에 실패했거나, 10초 내에 스트리밍 서버 응답이 없는 경우 발생합니다.
STREAMING_RECONNECT_FAILED 런타임 Agora 스트리밍 연결이 끊어져 자동 재연결을 시도했으나 실패한 경우 발생합니다.
VIDEO_ELEMENT_NOT_FOUND 런타임 스트리밍 연결 성공 후, document.querySelector로 <avatar-container> 요소를 탐색하지만 DOM에 존재하지 않는 경우 발생합니다. 조건부 렌더링(예: React에서 상태값에 따라 컴포넌트를 표시/숨김 처리)으로 인해 <avatar-container>가 document.body에 마운트되지 않은 경우가 대표적입니다. SDK 내부에서 300ms 간격으로 최대 3초간 폴링합니다.
SOCKET_DISCONNECTED_UNEXPECTEDLY 런타임 아바타 영상 재생 중(VIDEO_CAN_PLAY 상태) WebSocket 연결이 예기치 않게 끊어졌을 때 발생합니다. 네트워크 중단 또는 서버 측 연결 해제가 원인입니다.
STREAMING_DISCONNECTED_UNEXPECTEDLY 런타임 활성 세션 중 미디어 스트리밍 연결이 예기치 않게 끊어졌을 때 발생합니다. 네트워크 오류, 토큰 만료, IP/채널/UID 차단 등이 원인일 수 있습니다.

에러 이벤트 흐름​

콜백 재등록

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