@vchatcloud/react-ui-kit
Version:
VChatCloud UI Kit for react integration
578 lines (577 loc) • 19.7 kB
TypeScript
/**
* 오류 객체입니다.
* [오류 코드 페이지](https://vchatcloud.com/doc/javascript/chatting/errorCodeDefinition.html)를 참조하세요.
*/
export interface VChatCloudError {
code: number;
message: string;
}
/**
* 과거 채팅 내역 데이터입니다.
*
* 기록이 내림차순(역순)으로 나타나므로 주의하세요.
*/
export interface MessageHistory {
logType: string;
roomId: string;
clientKey: string;
message: string;
mimeType: ChannelMimeType;
messageType: any;
nickName: string;
date: string;
grade: ChannelUserGrade;
userInfo: any;
}
export declare class VChatCloud {
/**
* 접속한 `roomId`별로 채널을 관리합니다.
*/
channels: Record<string, Channel>;
/**
* 현재 접속한 유저의 고유 키 입니다.
*/
clientKey: string;
/**
* 채팅 서버와의 연결을 초기화합니다.
*/
constructor(param?: {
/**
* 채팅 서버 URL입니다. (솔루션을 사용할 때만 작성하세요.)
*/
url?: string;
/**
* CMS에서 사용하는 유저 이메일을 작성합니다.
*
* 개인 비밀채팅방을 생성하는 `openChannel` 기능을 사용하려면 필수로 등록하여야 합니다.
*/
serviceId?: string;
});
/**
* 채팅방에 접속합니다.
*
* @param param 채팅에 접속 할 데이터입니다.
* @param callback 접속 시 실행되는 콜백입니다.
*/
joinChannel<T = Record<string, never>>(param: User, callback?: (
/**
* `error`는 오류 객체로 `null`이 아니면 오류가 발생 한 것입니다.
*/
error: VChatCloudError | null,
/**
* 접속에 성공할 경우 `history`에 최근 20개의 과거 채팅내역 데이터를 가져옵니다.
*/
history?: MessageHistory[]) => void): Channel<T>;
/**
* **새로운 채팅방**을 생성합니다.
*
* 새 채팅방을 생성하기 위해서는 먼저 CMS에서 생성한 채팅방 중
* 임의의 채팅방에 접속해있어야 한다.
*
* @param param 채팅에 접속 할 데이터입니다.
* @param callback 접속 시 실행되는 콜백입니다.
*/
openChannel(param: {
/**
* 채팅방의 고유 키 입니다. 기존의 `channelKey`가 아닌 새로운 값을 사용해야 합니다.
*/
roomId: string;
/**
* 채팅방을 생성할 사용자의 고유 키 입니다.
* 기존 채팅방에 접속한 유저의 `clientKey`여야 합니다.
*/
clientKey: string;
}, callback?: (
/**
* `error`는 오류 객체로 `null`이 아니면 오류가 발생 한 것입니다.
*/
error: VChatCloudError | null, result: boolean) => void): void;
/**
* `VChatCloud.openChannel`로 생성한 **새로운 채팅방**을 퇴장하고 종료합니다.
*
* `data.clientKey`에 채널을 생성한 유저의 `clientKey`를 설정해야 합니다.
*
* @param param 퇴장 할 채팅방의 데이터입니다.
* @param callback 퇴장 후 실행되는 콜백입니다.
*/
closeChannel(param: {
/**
* 채팅방의 고유 키 입니다. `channelKey`와 같은 값입니다.
*/
roomId: string;
/**
* 퇴장 할 사용자의 고유 키 입니다.
*/
clientKey: string;
}, callback?: (
/**
* `error`는 오류 객체로 `null`이 아니면 오류가 발생 한 것입니다.
*/
error: VChatCloudError | null, result: boolean) => void): void;
/**
* 채팅 서버와의 연결을 종료합니다.
*
* 주로 접속 시도 중 실패하거나, 서버와 연결을 종료할 때 실행합니다.
*
* @param callback 연결 종료 시 실행 될 콜백입니다.
*/
disconnect(
/**
* `error`가 `null`이 아닐 경우 접속 종료 중 오류가 발생한 것 입니다.
*/
callback?: (error: VChatCloudError | null) => void): void;
}
/**
* 채팅 유저 등급입니다.
*
* - `user`: 일반유저
* - `userManager`: 채팅방 매니저
* - `userMute`: 글쓰기 제한 유저
* - `manager`: 관리자
*/
export type ChannelUserGrade = "user" | "userManager" | "userMute" | "manager";
/**
* 채팅 데이터의 마임 타입입니다.
*
* - `text`: 문자열 데이터
* - `emoji_img`: 이모티콘 데이터
* - `file`: 파일 정보 JSON 데이터
*/
export type ChannelMimeType = "text" | "emoji_img" | "file";
/**
* 채팅 이벤트에서 받을 수 있는 이벤트 데이터입니다.
*/
export interface Message {
/**
* 채팅 유저의 닉네입입니다.
*/
nickName: string;
/**
* 채팅방의 고유한 `roomId`(=`channelKey`)입니다.
*/
roomId: string;
/**
* 채팅 유저의 고유 키 입니다.
*/
clientKey: string;
/**
* 귓속말 사용 시 상대방의 고유 키 입니다.
*/
receivedClientKey?: string;
/**
* 전송한 메시지 내용입니다.
*/
message: string;
/**
* 전송한 메시지의 마임 타입입니다.
*/
mimeType: ChannelMimeType;
/**
* 메시지를 전송한 날짜입니다.
*/
messageDt: string;
/**
* 채팅방에서 메시지를 전송한 숫자입니다.
*/
messageCount: string;
/**
* 메시지를 전송한 유저의 등급입니다.
*/
grade: ChannelUserGrade;
/**
* 접속한 유저의 정보로, 보통 JSON형태를 사용합니다.
*
* 필요한 데이터를 추가로 저장할 수 있습니다.
*/
userInfo: any;
}
/**
* 유저 객체입니다.
*/
export interface User {
/**
* 접속한 채팅방의 `roomId`(=`channelKey`)입니다.
*/
roomId: string;
/**
* 유저의 고유 키 입니다.
*/
clientKey: string;
/**
* 유저의 닉네입입니다.
*/
nickName: string;
/**
* 유저의 등급입니다.
*/
grade?: ChannelUserGrade;
/**
* 유저의 정보로, 보통 JSON형태를 사용합니다.
*
* 필요한 데이터를 추가로 저장할 수 있습니다.
*/
userInfo?: any;
}
/**
* 스트림 데이터가 추가될 때 발생합니다.
*/
export interface StreamAppendEvent {
client: {
clientKey: string;
grade: ChannelUserGrade;
nickName: string;
};
clientKey: string;
target: MediaStream;
type: "rtcLocalStreamAppend" | "rtcRemoteStreamAppend";
}
/**
* 스트림 데이터가 제거될 때 발생합니다.
*/
export interface StreamRemoveEvent {
client: undefined;
clientKey: string;
target: null;
type: "rtcLocalStreamRemove" | "rtcRemoteStreamRemove";
}
/**
* 스트림 데이터가 변경될 때 발생합니다.
*
* 사용자가 카메라를 On/Off하거나, 마이크를 On/Off할 때 발생합니다.
*/
export interface StreamChangeEvent {
clientKey: string;
enable: boolean;
share: boolean;
stream: MediaStream;
target: MediaStreamTrack;
type: "rtcLocalAudioChanged" | "rtcRemoteAudioChanged" | "rtcLocalVideoChanged" | "rtcRemoteVideoChanged";
}
/**
* WebRTC 이벤트 처리 함수 정의
*/
export interface WebRTCDefaultEventMap {
rtcLocalStreamAppend: (event: StreamAppendEvent) => void;
rtcRemoteStreamAppend: (event: StreamAppendEvent) => void;
rtcLocalStreamRemove: (event: StreamRemoveEvent) => void;
rtcRemoteStreamRemove: (event: StreamRemoveEvent) => void;
rtcLocalAudioChanged: (event: StreamChangeEvent) => void;
rtcLocalVideoChanged: (event: StreamChangeEvent) => void;
rtcRemoteAudioChanged: (event: StreamChangeEvent) => void;
rtcRemoteVideoChanged: (event: StreamChangeEvent) => void;
}
/**
* 메시지를 보내거나, 받은 메시지의 이벤트를 처리할 수 있는 객체입니다.
*/
export declare class Channel<ChannelEventMap = Record<string, never>, DefaultEventMap = WebRTCDefaultEventMap> extends Object {
nickName: string;
roomId: string;
roomName: string;
clientKey: string;
grade: ChannelUserGrade;
resultCode: number;
/**
* 접속한 유저 목록입니다.
*
* Record<userClientKey: User>형태로 구성되어 있습니다.
*/
users: Record<string, User>;
private constructor();
/**
* 채팅방에 메시지를 전송합니다.
*
* @param data 전송할 메시지 데이터입니다.
* @param callback 전송 후 실행될 콜백입니다.
*/
sendMessage(data: {
/**
* 전송할 데이터를 입력합니다.
*/
message: string;
/**
* 전송할 데이터의 `mimeType`을 작성합니다.
*
* @default 'text'
*/
mimeType?: ChannelMimeType;
}, callback?: (
/**
* 오류가 발생하지 않으면 null이 전달됩니다.
*/
err: VChatCloudError | null) => void): void;
/**
* 채팅방에서 특정 유저에게 귓속말을 전송합니다.
*
* 귓속말을 전송하면 `data.receivedClientKey`에 지정한 상대방에게만 귓속말 이벤트가 전송됩니다.
*
* @param data 전송할 메시지 데이터입니다.
* @param callback 전송 후 실행될 콜백입니다.
*/
sendWhisper(data: {
/**
* 전송할 데이터를 입력합니다.
*/
message: string;
/**
* 전송할 데이터의 `mimeType`을 작성합니다.
*
* @default 'text'
*/
mimeType?: ChannelMimeType;
/**
* 귓속말 수신 유저의 고유 키 (`clientKey`)
*/
receivedClientKey: string;
},
/**
* 오류가 발생하지 않으면 null이 전달됩니다.
*/
callback?: (err: VChatCloudError | null) => void): void;
/**
* [CustomEvent](https://vchatcloud.com/doc/javascript/chatting/customMessage.html#%E1%84%8F%E1%85%A5%E1%84%89%E1%85%B3%E1%84%90%E1%85%A5%E1%86%B7-%E1%84%86%E1%85%A6%E1%84%89%E1%85%A6%E1%84%8C%E1%85%B5-%E1%84%8C%E1%85%A1%E1%86%A8%E1%84%89%E1%85%A5%E1%86%BC%E1%84%87%E1%85%A1%E1%86%BC%E1%84%87%E1%85%A5%E1%86%B8)를 전송합니다.
*
* 해당 기능을 이용해서 다양한 기능을 구현할 수 있습니다.
*
* 예를 들어 JSON형식의 데이터를 문자열로 변환하여 보낸 뒤
* `onNotifyCustom`에서 받은 데이터를 JSON으로 역직렬화하여
* 원하는 함수를 실행하는 방법 등 으로 사용하실 수 있습니다.
*
*
* @param data 커스텀 이벤트 데이터를 작성합니다.
* @param callback 커스텀 이벤트 전송 후 실행될 콜백입니다.
*/
sendCustom(data: {
message: string;
}, callback?: (err: VChatCloudError | null) => void): void;
/**
* 기존 채팅방에 접속해있는 유저를 **새로운 채팅방**에 초대합니다.
*
* @param data 초대 할 채팅방과 상대방의 정보입니다.
* @param callback 초대 후 실행될 콜백입니다.
*/
sendInvite(data: {
/**
* 새로 생성한 채팅방의 `roomId`(=`channelKey`)입니다.
*/
roomId: string;
/**
* 초대할 사용자의 `clientKey`입니다.
*/
clientKey: string;
}, callback?: (err: VChatCloudError | null, res: boolean) => void): void;
/**
* 공지사항을 채팅방에 전송합니다.
*
* @param data
* @param callback
*/
sendNotice(data: {
/**
* 전송할 데이터를 입력합니다.
*/
message: string;
/**
* 전송할 데이터의 `mimeType`을 작성합니다.
*
* @default 'text'
*/
mimeType?: ChannelMimeType;
}, callback?: (err: VChatCloudError | null) => void): void;
/**
* 접속중인 채팅방에서 퇴장합니다.
*
* @param callback 퇴장 후 실행될 콜백입니다.
*/
leave(callback?: () => void): void;
/**
* 채널에 접속한 유저 목록을 조회합니다.
*
* @param callback 유저 목록 조회 후 실행 될 콜백입니다.
*/
getAllUserList(callback?: (err: VChatCloudError | null, users: User[]) => void): void;
/**
* 선택한 유저를 입장 제한시킵니다.
*
* @param data 입장 제한할 유저의 `clientKey`를 작성합니다.
* @param callback 입장 제한 후 실행 될 콜백입니다.
*/
kickUser(data: {
clientKey: string;
}, callback?: (err: VChatCloudError | null) => void): void;
/**
* 선택한 유저를 채팅 제한 시킵니다.
*
* @param data 채팅 제한할 유저의 `clientKey`를 입력합니다.
* @param callback 채팅 제한 후 실행 될 콜백입니다.
*/
muteUser(data: {
clientKey: string;
}, callback?: (err: VChatCloudError | null) => void): void;
/**
* 선택한 유저의 입장 제한을 해제합니다.
*
* @param data 입장 제한을 해제할 유저의 `clientKey`를 작성합니다.
* @param callback 입장 제한 해제 후 실행 될 콜백입니다.
*/
unkickUser(data: {
clientKey: string;
}, callback?: (err: VChatCloudError | null) => void): void;
/**
* 선택한 유저의 채팅 제한을 해제합니다.
*
* @param data 채팅 제한을 해제할 유저의 `clientKey`를 작성합니다.
* @param callback 채팅 제한 해제 후 실행 될 콜백입니다.
*/
unmuteUser(data: {
clientKey: string;
}, callback?: (err: VChatCloudError | null) => void): void;
/**
* 채널 연결이 종료될 때 실행됩니다.
*/
onDisconnected: () => void;
/**
* 채팅방에 유저가 새로 접속할 때 전달됩니다.
*/
onNotifyJoinUser: (event: Message) => void;
/**
* 채팅방에 접속 해 있는 유저가 퇴장할 때 전달됩니다.
*/
onNotifyLeaveUser: (event: Message) => void;
/**
* 새로운 메시지를 받았을 때 전달됩니다.
*/
onNotifyMessage: (event: Message) => void;
/**
* 새로운 공지사항을 받았을 떄 전달됩니다.
*/
onNotifyNotice: (event: Message) => void;
/**
* 유저가 입장 제한될 때 전달됩니다.
*/
onNotifyKickUser: (event: Message) => void;
/**
* 유저의 입장 제한이 해제될 때 전달됩니다.
*/
onNotifyUnkickUser: (event: Message) => void;
/**
* 유저가 채팅 제한될 때 전달됩니다.
*/
onNotifyMuteUser: (event: Message) => void;
/**
* 유저의 채팅 제한이 해제될 때 전달됩니다.
*/
onNotifyUnmuteUser: (event: Message) => void;
/**
* 커스텀 이벤트를 수신 할 때 전달됩니다.
*/
onNotifyCustom: (event: Message) => void;
/**
* 귓속말을 받은 유저에게 전달됩니다.
*/
onPersonalWhisper: (event: Message) => void;
/**
* **서브 채팅방**에 초대 된 유저에게 전달됩니다.
* 일반적으로 `{channel key}-{Date.now()}_{invite user client key}`형식으로 구성되어 있습니다.
*/
onPersonalInvite: (event: Pick<Message, "roomId">) => void;
/**
* 입장 제한당한 유저에게 전달됩니다.
*
* 해당 유저는 채팅방의 연결이 종료되고, 입장 제한이 해제 되기 전까지
* 다시 입장할 수 없습니다.
*/
onPersonalKickUser: (event: Message) => void;
/**
* 채팅 제한당한 유저에게 전달됩니다.
*/
onPersonalMuteUser: (event: Message) => void;
/**
* 채팅 제한이 해제 된 유저에게 전달됩니다.
*/
onPersonalUnmuteUser: (event: Message) => void;
/**
* 로그인할 때 `clientKey`가 중복으로 이루어질경우
* 기존 (`clientKey`가 같은)사용자에게 전달됩니다.
*/
onPersonalDuplicateUser: (event: Message) => void;
/**
* 자신의 영상 소스를 Video 태그에 설정합니다.
*
* `HTMLVideoElement.srcObject`에 `MediaStream`을 설정하고,
* 음소거를 해제합니다.
*
* @param video srcObject를 설정할 HTMLVideoElement
*/
setRTCLocalMedia(video: HTMLVideoElement): void;
/**
* 참가자의 영상 소스를 Video 태그에 설정합니다.
*
* `HTMLVideoElement.srcObject`에 `MediaStream`을 설정하고,
* 음소거를 해제합니다.
*
* @param video srcObject를 설정할 HTMLVideoElement
* @param clientKey 참가자의 `clientKey`
*/
setRTCRemoteMedia(video: HTMLVideoElement, clientKey: string): void;
/**
* 자신의 오디오 입력을 토글합니다.
*
* @param on `true`를 설정하면 켭니다. `false`를 설정하면 끕니다. 미설정 시 토글됩니다.
*/
toggleRTCAudioControl(on?: boolean): void;
/**
* 자신의 비디오 입력을 토글합니다.
*
* @param on `true`를 설정하면 켭니다. `false`를 설정하면 끕니다. 미설정 시 토글됩니다.
*/
toggleRTCVideoControl(on?: boolean): void;
/**
* 자신의 영상 입력(카메라 <=> 화면공유)을 변경합니다.
*
* @param callback 영상 입력 변경 후 실행될 콜백 함수입니다.
*/
toggleRTCMedia(callback?: (
/**
* 영상 입력 종류입니다.
*
* - media: 카메라 입력
* - share: 화면 공유 입력
*/
name: "media" | "share",
/**
* 변경 성공 여부입니다.
*/
result: boolean) => void): void;
/**
* 이벤트 리스너를 추가합니다.
*/
on<T extends keyof ChannelEventMap | keyof DefaultEventMap>(event: T, fn: T extends keyof ChannelEventMap ? ChannelEventMap[T] : T extends keyof DefaultEventMap ? DefaultEventMap[T] : never): this;
/**
* 이벤트 리스너를 추가합니다.
*/
addListener<T extends keyof ChannelEventMap | keyof DefaultEventMap>(event: T, fn: T extends keyof ChannelEventMap ? ChannelEventMap[T] : T extends keyof DefaultEventMap ? DefaultEventMap[T] : never): this;
/**
* 한번만 실행되는 이벤트 리스너를 추가합니다.
*/
once<T extends keyof ChannelEventMap | keyof DefaultEventMap>(event: T, fn: T extends keyof ChannelEventMap ? ChannelEventMap[T] : T extends keyof DefaultEventMap ? DefaultEventMap[T] : never): this;
/**
* 이벤트 리스너를 제거합니다.
*/
off<T extends keyof ChannelEventMap | keyof DefaultEventMap>(event: T, fn: T extends keyof ChannelEventMap ? ChannelEventMap[T] : T extends keyof DefaultEventMap ? DefaultEventMap[T] : never): this;
/**
* 이벤트 리스너를 제거합니다.
*/
removeListener<T extends keyof ChannelEventMap | keyof DefaultEventMap>(event: T, fn: T extends keyof ChannelEventMap ? ChannelEventMap[T] : T extends keyof DefaultEventMap ? DefaultEventMap[T] : never): this;
/**
* 등록되어있는 모든 이벤트 리스너를 제거합니다.
*
* 파라미터로 입력할 경우 해당 이벤트 리스너를 제거합니다.
*/
removeAllListeners<T extends keyof ChannelEventMap | keyof DefaultEventMap>(event: T): this;
}
declare global {
interface Window {
VChatCloud: typeof VChatCloud;
Channel: typeof Channel;
}
}