채팅방 이벤트 사용하기

VChatCloud SDK는 메시지 수신 외에도, 사용자의 입장 및 퇴장, 운영자에 의한 추방이나 침묵 처리 등 채팅방 내부에서 발생하는 다양한 상태 변화를 실시간으로 감지할 수 있는 이벤트 핸들러를 제공합니다.

이러한 이벤트들을 활용하여 "OOO님이 입장했습니다"와 같은 시스템 메시지를 표시하거나, 특정 사용자의 상태 변화에 따른 UI를 동적으로 구현할 수 있습니다.

사전 준비

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

사용자 입장 및 퇴장

채팅방에 사용자가 들어오거나 나갔을 때 발생하는 이벤트입니다.

신규 사용자 입장

onNotifyJoinUser 이벤트는 새로운 사용자가 채팅방에 입장했을 때 모든 클라이언트에게 발생합니다.

channel.onNotifyJoinUser = (event) => {
  console.log('사용자 입장:', event);
  // 예: 채팅창에 시스템 메시지 표시
  // writeSystemMessage(`${event.nickName}님이 입장했습니다.`);
};

• Event 객체

필드명	타입	설명
roomId	string	채널 키
clientKey	string	입장한 사용자의 고유 키
nickName	string	입장한 사용자의 닉네임
grade	string	입장한 사용자의 등급 (사용자 등급표 참조)
joinCount	number	현재 채팅방의 누적 참여자 수

사용자 퇴장

onNotifyLeaveUser 이벤트는 다른 사용자가 채팅방에서 퇴장했을 때 모든 클라이언트에게 발생합니다.

channel.onNotifyLeaveUser = (event) => {
  console.log('사용자 퇴장:', event);
  // 예: 채팅창에 시스템 메시지 표시 및 사용자 목록에서 제거
  // writeSystemMessage(`${event.nickName}님이 퇴장했습니다.`);
  // removeUserFromList(event.clientKey);
};

• Event 객체

필드명	타입	설명
clientKey	string	퇴장한 사용자의 고유 키
nickName	string	퇴장한 사용자의 닉네임

운영 이벤트 (전체 알림)

관리자가 특정 사용자를 대상으로 운영(추방, 침묵 등)을 했을 때, 채팅방 안의 모든 사용자에게 알려주는 이벤트입니다.

사용자 글쓰기 제한 및 해제

onNotifyMuteUser와 onNotifyUnmuteUser 이벤트는 특정 사용자가 관리자에 의해 글쓰기 금지(침묵) 처리되거나 해제되었을 때 발생합니다.

// 글쓰기 제한
channel.onNotifyMuteUser = (event) => {
  console.log('글쓰기 제한:', event);
  // writeSystemMessage(`${event.nickName}님의 글쓰기가 제한되었습니다.`);
};

// 글쓰기 제한 해제
channel.onNotifyUnmuteUser = (event) => {
  console.log('글쓰기 제한 해제:', event);
  // writeSystemMessage(`${event.nickName}님의 글쓰기 제한이 해제되었습니다.`);
};

• Event 객체

필드명	타입	설명
clientKey	string	대상 사용자의 고유 키
nickName	string	대상 사용자의 닉네임

사용자 추방 및 추방 해제

onNotifyKickUser와 onNotifyUnkickUser 이벤트는 특정 사용자가 관리자에 의해 추방되거나 추방 해제되었을 때 발생합니다.

// 추방
channel.onNotifyKickUser = (event) => {
  console.log('추방:', event);
  // writeSystemMessage(`${event.nickName}님이 추방되었습니다.`);
};

// 추방 해제
channel.onNotifyUnkickUser = (event) => {
  console.log('추방 해제:', event);
  // writeSystemMessage(`${event.nickName}님이 추방 해제되었습니다.`);
};

• Event 객체

필드명	타입	설명
clientKey	string	대상 사용자의 고유 키
nickName	string	대상 사용자의 닉네임

개인 알림 이벤트

관리자의 조치나 시스템 상태 변경 등, 자기 자신에게만 발생하는 이벤트입니다.

내가 글쓰기 금지/해제되었을 때

onPersonalMuteUser와 onPersonalUnmuteUser 이벤트는 자기 자신이 글쓰기 금지 처리되거나 해제되었을 때 발생합니다.

// 글쓰기 금지
channel.onPersonalMuteUser = (event) => {
  alert('채팅이 금지되었습니다.');
  // 예: 채팅 입력창 비활성화
  // document.getElementById('chat-input').disabled = true;
};

// 글쓰기 금지 해제
channel.onPersonalUnmuteUser = (event) => {
  alert('글쓰기 제한이 해제되었습니다.');
  // 예: 채팅 입력창 활성화
  // document.getElementById('chat-input').disabled = false;
};

내가 추방당했을 때

onPersonalKickUser 이벤트는 자기 자신이 채팅방에서 추방당했을 때 발생합니다.

channel.onPersonalKickUser = (event) => {
  alert('채팅방에서 추방되었습니다.');
  // 예: 채팅방 나가기 처리
  // channel.disconnect();
  // location.href = '/';
};

중복 로그인 감지

onPersonalDuplicateUser 이벤트는 동일한 clientKey로 다른 기기나 브라우저에서 새로운 로그인이 발생했을 때, 기존에 접속해 있던 세션에서 발생합니다. 이 이벤트를 받아 현재 세션을 안전하게 종료하는 처리를 해야 합니다.

channel.onPersonalDuplicateUser = (event) => {
  alert('다른 기기에서 로그인하여 현재 접속을 종료합니다.');
  // 예: 접속 종료 및 로그인 페이지로 이동
  // channel.disconnect();
  // location.reload();
};

• Event 객체

필드명	타입	설명
clientKey	string	중복 접속된 사용자의 고유 키
messageDt	number	이벤트 발생 시간 (epoch time)

초대 이벤트

다른 채팅방으로부터 초대를 받았을 때 발생하는 개인 알림 이벤트입니다.

다른 채팅방에 초대받았을 때

onPersonalInvite 이벤트는 다른 채팅방으로부터 초대를 받았을 때 발생합니다.

channel.onPersonalInvite = (event) => {
  console.log('채팅방 초대:', event);
  if (confirm(`'${event.roomId}' 방으로 이동하시겠습니까?`)) {
    // 현재 채널 접속을 끊고 새로운 채널로 입장하는 로직 구현
    // channel.disconnect();
    // joinNewChannel(event.roomId);
  }
};

• Event 객체

필드명	타입	설명
roomId	string	초대받은 채팅방의 채널 키
clientKey	string	초대한 사용자의 고유 키