사용자 정의 이벤트

사용자 정의 이벤트는 채팅방에 접속된 모든 클라이언트에게 특정 이벤트나 데이터를 전송할 수 있는 강력한 기능입니다. 공지사항, 팝업 알림, 실시간 퀴즈 등 애플리케이션에 필요한 다양한 상호작용을 구현하는 데 사용할 수 있습니다.

메시지 내용은 일반적으로 JSON 형식의 문자열로 구성하여, 사전에 정의된 type에 따라 클라이언트에서 각기 다른 동작을 수행하도록 만들 수 있습니다.

이 문서에서는 사용자 정의 이벤트를 수신하고 처리하는 방법을 설명합니다.

사전 준비

모든 이벤트 핸들러를 사용하기 전에, vChatCloud.joinChannel을 통해 채팅방 입장이 완료되어 channel 객체가 성공적으로 생성되어야 합니다. 자세한 내용은 SDK 개요 문서를 참고하세요.

사용자 정의 이벤트 전송 방법

사용자 정의 이벤트는 VChatCloud CMS, REST API 등 다양한 방법으로 전송할 수 있습니다.

1. VChatCloud CMS 사용

가장 기본적인 방법으로, VChatCloud 관리자 페이지(CMS)에서 직접 사용자 정의 이벤트를 등록하고 전송할 수 있습니다.

1. 사용자 정의 이벤트 등록: 채팅방 관리 > 사용자 정의 이벤트 메뉴에서 전송할 메시지의 내용을 JSON 형식으로 등록합니다.
2. 이벤트 전송: 채팅방 관리 > 채팅방 목록에서 원하는 채팅방의 채팅방 모니터링으로 이동한 후, 사용자 정의 이벤트 전송 기능을 통해 등록된 메시지를 즉시 또는 예약 전송합니다.

2. JavaScript SDK 사용

JavaScript SDK의 Channel 객체에 포함된 sendCustom 메소드를 사용하여 클라이언트에서 직접 사용자 정의 이벤트를 전송할 수 있습니다. 이 기능은 주로 관리자 등급의 사용자에게 UI를 통해 특정 액션을 실행하게 하는 용도로 사용될 수 있습니다.

sendCustom 메소드는 전송할 메시지를 message 파라미터로 받습니다.

const pollData = {
  type: "poll_start",
  question: "가장 선호하는 계절은?",
  options: ["봄", "여름", "가을", "겨울"],
  duration: 30 // 30초
};

channel.sendCustom({
  message: JSON.stringify(pollData)
}, (error, result) => {
  if (error) {
    console.error('투표 시작 이벤트 전송 실패:', error);
    return;
  }
  console.log('투표 시작 이벤트 전송 성공:', result);
});

더 자세한 내용은 JavaScript SDK API 레퍼런스 문서를 참고하세요.

3. REST API 사용

서버 환경에서는 REST API를 호출하여 동적으로 사용자 정의 이벤트를 전송할 수 있습니다. 예를 들어, 특정 조건이 만족되었을 때 시스템에서 자동으로 공지를 보내는 등의 기능을 구현할 수 있습니다.

자세한 사용 방법과 API 명세는 채팅 REST API 문서를 참고하세요.

사용자 정의 이벤트 수신

채팅방에 사용자 정의 이벤트가 도착하면 channel.onNotifyCustom 이벤트가 발생합니다. 이 이벤트 핸들러를 등록하여 메시지 수신 시 원하는 로직을 실행할 수 있습니다.

channel.onNotifyCustom = (event) => {
  console.log('사용자 정의 이벤트 수신:', event);
  // 여기에 사용자 정의 이벤트 처리 로직을 구현합니다.
};

Event 객체 구조

onNotifyCustom 핸들러는 아래와 같은 구조의 event 객체를 파라미터로 전달받습니다.

필드명	타입	설명
roomId	string	채팅방의 channelKey
message	string	전송된 사용자 정의 이벤트 내용. 일반적으로 JSON 형식의 문자열입니다.
nickName	string	메시지를 전송한 운영자 또는 시스템의 닉네임.
clientKey	string	메시지를 전송한 클라이언트의 고유 키.
messageDt	string	메시지 전송 시간 (YYYY-MM-DD HH:mm:ss).
mimeType	string	메시지 타입.
messageCount	number	현재 채팅방의 총 메시지 수.

사용 예시

다음은 수신된 사용자 정의 이벤트의 message 내용을 JSON으로 파싱하고, type 값에 따라 다른 처리를 하는 간단한 예시입니다. 실제 애플리케이션에서는 console.log 대신 UI를 업데이트하는 코드를 작성하게 됩니다.

// 사용자 정의 이벤트 수신 이벤트 핸들러
channel.onNotifyCustom = (event) => {
  try {
    // 수신된 메시지를 JSON 객체로 파싱합니다.
    const customData = JSON.parse(event.message);

    console.log('사용자 정의 이벤트 수신:', customData);

    // 'poll_start' 타입의 이벤트를 받아 투표 UI를 생성합니다.
    if (customData.type === 'poll_start') {
      // 예: 화면에 투표 UI를 표시하는 함수 호출
      console.log(`[투표 시작] ${customData.question}`);
      // showPoll(customData.question, customData.options, customData.duration);
    } else {
      // 기타 다른 유형의 이벤트 처리
      console.log(`[기타 이벤트] ${customData.type}`);
    }
  } catch (e) {
    // JSON 파싱에 실패한 경우, 원본 메시지를 그대로 처리합니다.
    console.warn('JSON 파싱 불가:', event.message);
  }
};