u-chat 속성

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

<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>

속성 목록

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

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

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

크기

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

<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를 페이지에 직접 쓰지 못할 때(정적 페이지, 캐시되는 페이지) 써요.

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

// 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

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

<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

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

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

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

설치·제거와 속성 변경

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

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에서 태그를 다루는 흐름은 비동기 로딩과 여러 채팅방을 보세요.