5분 설치

채팅방을 하나 만들고 설치 코드 두 줄을 페이지에 붙이면 그 자리에 채팅방이 열려요. 이 문서의 예시는 채팅방 아이디 my-room을 써요.

채팅방 만들기

내 채팅방에서 채팅방 만들기를 누르고 아이디·이름·관리자 비밀번호를 정해요. 아이디는 영문·숫자·_·- 4~20자이고 나중에 바꿀 수 없어요. 아이디가 설치 코드의 room 값이 돼요.

만들고 나면 설치 코드 화면으로 이동해요. 나중에는 관리 페이지의 설치 코드 메뉴에서 다시 볼 수 있어요.

설치 코드

회원 연동을 쓰지 않는 채팅방의 설치 코드예요. 채팅방을 보여 줄 자리에 붙여 넣으세요.

<script async src="https://client.uchat.io/uchat.js"></script>
<u-chat room="my-room" style="display:inline-block; width:100%; max-width:500px; height:500px;"></u-chat>

• <script>는 페이지에 한 번만 넣어요. async로 불러오므로 페이지 표시를 막지 않아요.
• <u-chat> 태그 하나가 채팅방 하나예요. 아이디가 다른 <u-chat>을 여러 개 두면 한 페이지에 채팅방 여러 개가 열려요. 같은 아이디는 페이지에 하나만 둘 수 있어요.
• 자바스크립트로 <u-chat>을 나중에 넣거나 지워도 채팅방이 따라서 열리고 닫혀요. 자세한 동작은 비동기 로딩과 여러 채팅방에 있어요.
• <u-chat>에 넣을 수 있는 다른 속성(회원 연동, 스킨, 접속 비밀번호, 언어 등)은 u-chat 속성에 있어요.

크기

채팅방은 <u-chat> 태그의 크기를 따라요. style의 width, height로 정하세요. <u-chat>은 기본이 인라인 요소라서 display:inline-block 또는 display:block을 함께 주어야 크기가 적용돼요.

<u-chat room="my-room" style="display:block; width:100%; height:70vh;"></u-chat>

설치 코드 화면의 너비·높이 칸은 숫자 1~4자리에 단위 px, %, vh, vw, em, rem 중 하나를 붙인 값(500px, 100%, 70vh 등)만 받아요. 직접 코드를 고칠 때는 CSS 값을 자유롭게 써도 돼요. 너무 작으면 입력창과 사용자 목록이 제대로 보이지 않아요.

설치 코드 화면의 로딩에서 채팅방이 뜨기 전까지 그 자리에 보일 모양(채팅방 뼈대, 도는 원, 로고)을 고를 수 있어요. 코드에 짧은 <style>과 <u-chat>의 클래스로 들어가고, 자바스크립트 없이 CSS만 써요. 채팅창이 그려지면 그 위를 덮어 사라져요. 화면 오른쪽의 미리보기에서 고른 모양을 바로 볼 수 있어요.

화면 오른쪽 아래 단추로 열고 닫는 채팅창이 필요하면 떠 있는 위젯을 쓰세요.

React·Vue·Svelte

설치 코드 화면의 사이트에 붙이기에서 HTML, React · Next.js, Vue · Nuxt, Svelte · SvelteKit 탭을 고르면 그 방식에 맞는 코드가 나와요. 모두 uchat.js를 한 번만 불러오고 <u-chat> 태그를 두는 방식이에요.

React · Next.js:

'use client'; // Next.js App Router에서만 필요

import { useEffect } from 'react';

export default function ChatRoom() {
	useEffect(() => {
		if (!document.querySelector('script[data-uchat]')) {
			const s = document.createElement('script');
			s.src = 'https://client.uchat.io/uchat.js';
			s.async = true;
			s.dataset.uchat = '';
			document.head.appendChild(s);
		}
	}, []);
	return <u-chat room="my-room" style={{ display: 'inline-block', width: '100%', maxWidth: '500px', height: '500px' }} />;
}

Vue · Nuxt는 u-chat을 사용자 정의 요소로 알려 주어야 경고가 나지 않아요(vite.config의 vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === 'u-chat' } } })).

Svelte · SvelteKit:

<svelte:head>
	<script async src="https://client.uchat.io/uchat.js"></script>
</svelte:head>

<u-chat room="my-room" style="display:inline-block; width:100%; max-width:500px; height:500px;"></u-chat>

npm 패키지로 붙일 수도 있어요. @u-chat/react·@u-chat/vue·@u-chat/svelte의 UchatRoom은 <u-chat>을 그리고 uchat.js를 한 번만 불러오며, 컴포넌트가 사라지면 채팅방도 닫혀요. 크기는 width·height(숫자는 px), 회원 연동은 userData, 독립 서버는 src로 넘겨요. Vue는 isCustomElement 설정 없이 써요.

// npm install @u-chat/react
import { UchatRoom } from '@u-chat/react';

export default function Chat() {
	return <UchatRoom room="my-room" width="100%" height={500} />;
}

화면 전환 때 채팅방을 붙였다 떼거나 이벤트를 걸고 정리하는 방법은 비동기 로딩과 여러 채팅방을 보세요.

채팅방을 페이지 오른쪽 아래 단추로 띄우려면 떠 있는 위젯을 쓰세요. 설치 코드 화면의 떠 있는 위젯 탭(회원 연동 방은 넣는 모양 → 떠 있는 위젯)이 코드를 만들어 줘요. 모양(둥근 단추·아래쪽 막대·오른쪽 사이드바), 단추 글자·색·그림, 창 제목, 언어, 위치·크기 같은 위젯 설정도 그 화면에서 골라요. React·Vue·Svelte는 npm 패키지 @u-chat/react·@u-chat/vue·@u-chat/svelte로 붙여요.

CMS에 설치

관리 페이지 회원 연동을 켜면 설치 코드 화면에서 사이트 종류를 고를 수 있어요. 고른 종류에 맞춰 회원 정보로 접속하는 코드나 설치 파일을 줘요.

사이트 종류	받는 것	설치
그누보드 4/5	PHP 코드	채팅방을 보여 줄 파일에 붙여 넣어요. 로그인한 회원의 닉네임·아이디·레벨·관리자 여부와 회원 아이콘이 들어가요.
그누보드7	uchat-chat-gnuboard7.zip(설치 코드 화면에서 이 사이트 종류로 코드 만들기를 누르면 나오는 주소에서 받아요. 관리 페이지에 로그인한 채로 열어요)	그누보드7 관리자 → 플러그인 관리 → 수동 설치에서 올리고 활성화한 뒤, 플러그인 설정에 채팅방 아이디와 토큰을 넣고 표시 위치를 골라요(그누보드7 7.0.10 이상).
XpressEngine	uchat2.zip(설치 코드 화면에서 이 사이트 종류로 코드 만들기를 누르면 나오는 주소에서 받아요. 관리 페이지에 로그인한 채로 열어요)	XE 위젯 폴더에 올린 뒤 위젯으로 추가해요.
라이믹스	XpressEngine과 같은 uchat2.zip	라이믹스의 widgets 폴더에 올린 뒤, 관리자 → 고급 → 설치된 위젯에서 유챗2 위젯의 코드생성으로 코드를 만들어 페이지나 레이아웃에 넣어요. 로그인한 회원은 닉네임·아이디·레벨·관리자 여부로 들어와요.
워드프레스	uchat-wordpress.zip(설치 코드 화면에서 이 사이트 종류로 코드 만들기를 누르면 나오는 주소에서 받아요. 관리 페이지에 로그인한 채로 열어요)	플러그인 → 새로 추가 → 업로드로 설치하고 설정 → 유챗에 채팅방 아이디와 토큰을 넣은 뒤, 채팅방을 보일 글·페이지·템플릿에 [uchat]을 넣어요(블록 테마는 "숏코드" 블록, 크기는 [uchat height="600px"]처럼). 위젯 영역이 있는 테마는 유챗 위젯으로 넣어도 돼요. 서명은 방문자의 브라우저가 열 때마다 새로 받아 오므로 페이지 캐시 플러그인과 같이 써도 돼요. 로그인한 회원은 표시 이름(닉네임)·이메일(아이디)·사용자 레벨로, 사이트 관리자는 채팅방 관리자로, 로그인하지 않은 방문자는 손님으로 들어와요.
그 밖의 사이트	PHP·Node.js·Python·Java 코드	회원 정보 변수만 내 사이트에 맞게 바꿔요. → 회원 연동

그누보드7·XpressEngine·라이믹스·워드프레스는 설치 파일이 늘 같고, 넣는 모양(페이지 안에 넣기 또는 떠 있는 위젯), 로딩, 위젯 모양·단추·크기는 각 플러그인 설정에서 골라요(워드프레스는 설정 → 유챗, XE·라이믹스는 위젯 설정, 그누보드7은 플러그인 설정). 바꿀 때 파일을 다시 받을 필요가 없어요.

설치 파일과 코드에는 채팅방 토큰이 들어가거나 토큰을 입력하게 돼요. 토큰은 서버에만 두세요.

채널 채팅방

회원가입 없이 쓰는 채널 채팅방은 https://uchat.ch/채팅방이름 주소에서 열려요. 내 사이트에는 iframe으로 붙여요.

<iframe src="https://uchat.ch/채팅방이름" style="display:inline-block; width:100%; max-width:500px; height:500px;" frameborder=0></iframe>

채널 채팅방은 iframe으로 붙으므로 U.chat() 페이지 스크립트와 스킨 UI API를 내 페이지에서 쓸 수 없어요. 확장 기능이 필요하면 내 채팅방에서 채팅방을 만들어 <u-chat>으로 설치하세요.

안 뜰 때 점검

증상	확인할 것
아무것도 보이지 않음	uchat.js <script>가 페이지에 있는지, <u-chat>에 display와 width·height를 주었는지 확인해요.
두 번째 채팅방이 안 열림	같은 room 아이디의 <u-chat>이 이미 페이지에 있어요. 같은 아이디는 처음 것만 열려요.
속성을 바꿨는데 그대로임	<u-chat>의 속성 변경은 감지하지 않아요. 태그를 지우고 새로 넣으세요. → 비동기 로딩과 여러 채팅방
"토큰이 누락됐어요" 같은 오류	회원 연동이 켜진 채팅방에 연동 코드 없이 접속했어요. → 회원 연동
접속 비밀번호를 물어봄	관리 페이지에서 접속 비밀번호를 걸어 두었어요. u-chat 속성의 password로 미리 넣을 수 있어요.

원인을 모르겠으면 페이지 주소에 ?uchatdebug=1을 붙여 열고 브라우저 콘솔의 로그를 확인하세요.