# u-chat 속성

> 채팅방을 넣는 u-chat 태그의 속성과 설치·제거 규칙이에요.

`<u-chat>` 태그 하나가 채팅방 하나예요. 이 문서는 태그에 쓸 수 있는 속성과, 태그를 넣고 빼고 바꿀 때 어떻게 동작하는지 정리해요. 설치 코드 자체는 [5분 설치](/doc/1.2#install-code)를 보세요.

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

## 속성 목록 {#attributes}

`style`과 `wrap`을 뺀 모든 속성이 채팅방 설치 옵션으로 넘어가요. 값은 모두 문자열이에요.

| 속성 | 형식 | 설명 |
| --- | --- | --- |
| `room` | 채팅방 아이디 | 필수. 없으면 태그를 무시해요 |
| `user_data` | 서명한 문자열 | 회원 연동 접속 정보. 서버에서 만들어 넣어요. 형식은 [회원 연동 서명 규격](/doc/3.7) |
| `user_data_url` | URL | 접속 정보를 스크립트로 받아 올 주소. 아래 [user_data_url](#user-data-url) 참고 |
| `skin` | 스킨 이름 | 쓸 스킨. 생략하면 관리 페이지에서 고른 스킨을 써요 |
| `skin_arguments` | JSON 문자열 | 스킨 설정을 이 페이지에서만 덮어써요. 아래 [skin_arguments](#skin-arguments) 참고 |
| `password` | 문자열 | 접속 비밀번호(또는 관리자 비밀번호). 비밀번호가 걸린 채팅방에 묻지 않고 들어가요 |
| `lang` | 언어 코드 | 채팅방 화면 언어. 아래 [lang](#lang) 참고 |
| `invite` | 닉네임 | 입장 직후 이 닉네임을 내 개인채널로 초대해요. `user_data_url`과 함께 쓰면 동작하지 않아요 |

- 속성 이름은 HTML 규칙대로 대소문자를 가리지 않아요.
- `user_data`와 `user_data_url`을 둘 다 주면 `user_data`를 써요.
- 회원 연동을 켠 채팅방은 `user_data`나 `user_data_url` 없이 들어오면 오류 203으로 거절돼요.
- `password` 값은 페이지 소스에 그대로 보여요. 누구나 볼 수 있는 페이지라면 비밀번호를 거는 의미가 없어요.

## 크기 {#size}

크기는 `style`로 정해요. 채팅방 iframe은 태그 크기에 맞춰 가로·세로 100%로 채워져요.

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

`<u-chat>`은 기본이 인라인 요소이므로 `display:inline-block`(또는 `block`)과 높이를 함께 주세요. 높이가 0이면 채팅방이 보이지 않아요. 관리 페이지의 설치 코드는 1~4자리 숫자에 `px`, `%`, `vh`, `vw`, `em`, `rem` 단위를 붙인 값을 만들어요.

## user_data_url {#user-data-url}

`user_data`를 페이지에 직접 쓰지 못할 때(정적 페이지, 캐시되는 페이지) 써요.

1. 채팅방이 `{user_data_url}?room={채팅방 아이디}` 주소를 `<script>`로 불러와요.
2. 그 스크립트는 `window.Uchat_cache.token['채팅방 아이디']`에 [서명한 문자열](/doc/3.7)을 넣어야 해요.
3. 스크립트가 끝나면 그 값으로 입장해요.

```js
// https://example.com/uchat-token.js?room=my-room 의 응답 (서버가 로그인한 회원 기준으로 만든다)
window.Uchat_cache.token['my-room'] = 'id user1|level 5|nick %ED%99%8D%EA%B8%B8%EB%8F%99|room my-room|time 1700000000|hash ...';
```

이 응답은 스크립트로 실행돼요. 내 사이트와 같은 출처에서 내보내고, 회원마다 다른 값이므로 `Cache-Control: no-store`를 붙이세요.

## skin_arguments {#skin-arguments}

관리 페이지에서 정한 스킨 설정 위에 이 페이지에서만 쓸 값을 덮어써요. 합쳐진 값은 페이지 스크립트에서 `room.skin.arguments`로 읽을 수 있어요.

```html
<u-chat room="my-room" skin_arguments='{"lang":"en"}' style="display:inline-block; width:100%; max-width:400px; height:600px;"></u-chat>
```

JSON이 잘못되면 오류 없이 `{}`로 처리되어 아무것도 바뀌지 않아요. 값이 적용되지 않으면 먼저 JSON 문법(큰따옴표, 쉼표)을 확인하세요. 속성 값은 작은따옴표로 감싸면 JSON 안의 큰따옴표를 그대로 쓸 수 있어요.

## lang {#lang}

채팅방 화면 언어는 아래 순서로 처음 맞는 값을 써요. 언어팩이 있는 언어는 `ko`, `en`, `ja`예요.

1. `lang` 속성
2. 관리 페이지(또는 `skin_arguments`)의 `lang`
3. 채팅방을 붙인 페이지의 `<html lang>`
4. 브라우저 언어
5. 영어

`ko-KR`, `ja_JP`처럼 지역이 붙은 값은 앞부분만 봐요.

## 설치·제거와 속성 변경 {#lifecycle}

- uchat.js는 처음 읽힐 때 페이지의 `<u-chat>`을 모두 설치하고, 그 뒤에는 태그가 문서에 **추가되면 설치, 제거되면 파괴**해요(MutationObserver).
- **속성을 바꿔도 다시 설치하지 않아요.** `room`, `user_data` 등을 바꾸려면 태그를 지우고 새 태그를 넣으세요.

```js
function replaceRoom(container, attrs) {
	container.querySelector('u-chat')?.remove();
	const tag = document.createElement('u-chat');
	for (const [name, value] of Object.entries(attrs)) tag.setAttribute(name, value);
	tag.style.cssText = 'display:inline-block; width:100%; max-width:400px; height:600px;';
	container.appendChild(tag);
}
```

- 같은 `room` 값의 태그는 페이지에 하나만 설치돼요. 두 번째 태그는 무시돼요.
- 태그를 지우면 그 채팅방에만 등록한 이벤트(`U.chat('my-room').on`, `room.on`)도 함께 지워져요. `U.chat('*')`로 등록한 이벤트는 남아요.

비동기 로딩과 SPA에서 태그를 다루는 흐름은 [비동기 로딩과 여러 채팅방](/doc/2.2)을 보세요.