# 5분 설치

> 채팅방을 만들고 설치 코드를 붙여 내 사이트에 채팅방을 띄워요. 프레임워크·CMS·채널 채팅방 설치와 안 뜰 때 점검할 것도 다뤄요.

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

## 채팅방 만들기 {#create-room}

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

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

## 설치 코드 {#install-code}

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

```html
<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>`을 나중에 넣거나 지워도 채팅방이 따라서 열리고 닫혀요. 자세한 동작은 [비동기 로딩과 여러 채팅방](/doc/2.2)에 있어요.
- `<u-chat>`에 넣을 수 있는 다른 속성(회원 연동, 스킨, 접속 비밀번호, 언어 등)은 [u-chat 속성](/doc/3.1)에 있어요.

## 크기 {#size}

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

```html
<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만 써요. 채팅창이 그려지면 그 위를 덮어 사라져요. 화면 오른쪽의 미리보기에서 고른 모양을 바로 볼 수 있어요.

화면 오른쪽 아래 단추로 열고 닫는 채팅창이 필요하면 [떠 있는 위젯](/doc/2.2#widget)을 쓰세요.

## React·Vue·Svelte {#frameworks}

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

React · Next.js:

```jsx
'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
<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` 설정 없이 써요.

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

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

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

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

## CMS에 설치 {#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 코드 | 회원 정보 변수만 내 사이트에 맞게 바꿔요. → [회원 연동](/doc/2.1) |

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

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

## 채널 채팅방 {#channel-rooms}

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

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

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

## 안 뜰 때 점검 {#not-showing}

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

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