시작하기

VChatCloud React UI Kit는 VChatCloud 서비스를 React 프로젝트에 간편하게 통합할 수 있게 해주는 라이브러리입니다.

라이브러리 설치

명령어를 입력 해 프로젝트에 @vchatcloud/react-ui-kit를 의존성으로 추가합니다.

bash

npm install @vchatcloud/react-ui-kit
# or
# yarn add @vchatcloud/react-ui-kit
# or
# pnpm add @vchatcloud/react-ui-kit

사용법

React UI Kit을 사용하기 전에, index.html 파일의 <head> 태그 내에 다음과 같은 스크립트 태그를 추가해야 합니다.

html

<head>
  <script src="https://www.vchatcloud.com/lib/e7lib-latest.min.js"></script>
</head>

프로젝트 내에서 UI Kit 컴포넌트를 사용하려면, 필요한 컴포넌트를 import하여 사용하면 됩니다. VChatCloud 서비스를 초기화하고 실행하는 핵심 컴포넌트는 VChatCloudApp입니다.

코드 예시

tsx

import { VChatCloudApp } from "@vchatcloud/react-ui-kit";
import { FC, useEffect, useRef } from "react";

const App: FC = () => {
  const [roomId, clientKey, nickName, grade, userInfo] = [
    "YOUR_ROOM_ID",
    // clientKey는 사용자 식별에 중요한 값입니다.
    // 사용자 간 중복을 피하도록 고유한 값을 사용하거나,
    // `setRandomClientKey` 함수를 사용하여 임의의 키를 생성할 수 있습니다.
    // 중복 로그인 시 기존 사용자가 접속 종료되니 주의하시기 바랍니다.
    "YOUR_CLIENT_KEY",
    "YOUR_NICKNAME",
    "user",
    { profile: 1 },
  ];
  const privateContainer = useRef<HTMLDivElement>(null);

  // private container 사용 시
  useEffect(() => {
    if (!privateContainer.current) return;
    privateContainer.current.style.display = "none";

    const observer = new MutationObserver(() => {
      if (!privateContainer.current) return;

      privateContainer.current.style.display =
        privateContainer.current.children.length === 0 ? "none" : "block";
    });
    observer.observe(privateContainer.current, { childList: true });

    return () => observer.disconnect();
  }, []);

  return (
    <>
      <div className="app" style={{ width: "100%", height: "100vh" }}>
        <VChatCloudApp
          clientKey={clientKey}
          email="YOUR_EMAIL" // VChatCloud CMS 계정 ID
          grade={grade}
          nickName={nickName}
          privateContainer=".private-container" // querySelector 파라미터 또는 HTMLElement
          roomId={roomId}
          sessionType="parameter" // 'login', 'parameter', 'private' 중 선택
          userInfo={userInfo}
          // logoUrl="LOGO_IMG_URL"
          // company="YOUR_COMPANY_NAME"
        />
      </div>
      {/* 비밀채팅용 wrapper */}
      <div
        className="app private-container"
        ref={privateContainer}
        style={{ width: "100%", height: "100vh" }}
      />
    </>
  );
};

export default App;

주요 컴포넌트 속성

`VChatCloudApp`

VChatCloud 서비스의 핵심 기능을 제공하는 컴포넌트입니다. 다음은 주요 속성 목록입니다.

clientKey: 사용자 고유 식별 키입니다. 동일한 키로 여러 사용자가 동시에 접속할 경우 기존 세션이 종료될 수 있으므로, 각 사용자에게 고유한 키를 할당해야 합니다. setRandomClientKey 함수를 사용하여 임의의 키를 생성할 수도 있습니다.
email : VChatCloud CMS 계정 ID.
grade : 사용자 등급 (user, userManager 등).
nickName : 사용자 닉네임.
roomId : 채팅방 ID.
privateContainer : 비밀 채팅을 위한 HTML 컨테이너 (querySelector 파라미터 또는 HTMLElement).
sessionType : 세션 타입
- login : 로그인 화면을 사용해 접속자가 원하는 닉네임과 프로필을 설정할 수 있습니다.
- parameter : 파라미터로 사용자의 정보를 불러와 사용합니다. 개발자가 지정한 정보를 사용하게 됩니다.
- private : 파라미터와 동일하게 사용자의 정보를 불러와 사용하지만, 비밀채팅을 이용할 때 설정합니다.
userInfo : 추가 사용자 정보 (객체 형태). userInfo.profile에 숫자를 지정하면 기본 제공하는 프로필 이미지를 사용할 수 있습니다. (1 ~ 48까지 제공)
logoUrl: 선택 사항으로, 로그인 화면에 표시될 로고 이미지의 URL을 설정할 수 있습니다.
company: 선택 사항으로, 로그인 화면 하단에 표시될 회사 이름을 설정할 수 있습니다.

주의사항

StrictMode 비활성화: React 개발 모드에서 <React.StrictMode>로 감싸여 있을 경우, VChatCloud SDK와의 호환성 문제로 인해 오류가 발생할 수 있습니다. 개발 서버 실행 시에는 StrictMode를 비활성화하여 실행해야 합니다.
clientKey 중복 관리: 동일한 clientKey로 여러 사용자가 동시에 로그인하면 기존 사용자의 연결이 끊어질 수 있습니다. 각 사용자에게 고유한 clientKey를 할당하거나, 필요에 따라 setRandomClientKey 함수를 사용하여 임의의 키를 생성하는 것을 권장합니다.

시작하기 ​

라이브러리 설치 ​

사용법 ​

코드 예시 ​

주요 컴포넌트 속성 ​

VChatCloudApp ​

주의사항 ​