시작하기
채팅을 내 서비스에 붙이는 데 필요한 것은 셋이다. 콘솔에서 만든 앱, 토큰을 발급하는 백엔드 엔드포인트 하나, 브라우저의 SDK.
npm install @kispi/chat진입점이 둘이다. SDK는 런타임 의존성이 없고 타입 선언을 포함한다.
| 진입점 | 어디서 | 쓰는 키 |
|---|---|---|
@kispi/chat |
브라우저(와 Node) | publishable key(pk_) |
@kispi/chat/server |
내 백엔드 | secret key(sk_) |
1. 콘솔에서 앱을 만든다
가입한 뒤 새 앱을 누른다. 앱 하나가 테넌트 하나다 — 유저·방·메시지·키가 앱마다 따로 있다. 만들자마자 키 두 개가 나온다.
| 키 | 어디에 두나 | 무엇을 하나 |
|---|---|---|
publishable key(pk_…) |
프론트엔드 코드 | 어느 앱인지만 말한다. 공개값이다 |
secret key(sk_…) |
백엔드의 환경변수 | 그 앱의 모든 데이터다. 토큰 발급과 서버 API에 쓴다 |
sk_는 만든 순간 한 번만 보인다. 콘솔은 그 값을 저장하지 않으므로 바로 비밀 저장소에
옮겨 둔다. 잃어버렸으면 새 sk_를 발급하고 옛 것을 폐기한다(키 교체).
화면을 누르는 대신 스크립트나 AI로 앱을 만들고 싶다면 계정 키(ck_) 하나로 된다. 콘솔 API를 본다.
허용 origin
앱을 만들 때 적는 허용 origin은 브라우저에서 이 pk_를 쓸 수 있는 페이지의 origin이다.
- 스킴·호스트·포트가 정확히 맞아야 한다.
https://example.com과https://www.example.com은 다른 origin이다. http://localhost:3000과http://127.0.0.1:3000도 다르다. 개발용 origin은 따로 넣는다.- 목록에 없는 페이지에서 쓰면
unauthorized로 거절된다. 목록은 키 화면에서 허용 origin 칸을 눌러 바꾼다.
2. 백엔드가 토큰을 발급한다
엔진은 사람이 누구인지 모른다. 토큰의 서명을 검증하고 그 안의 유저 id를 액면 그대로 믿을 뿐이다. 누가 로그인했는지는 서비스가 아니까, 필요한 것은 그 사람에게 토큰을 발급하는 엔드포인트 하나다.
// src/routes/api/chat-token/+server.ts (SvelteKit) — 어떤 프레임워크든 모양은 같다
import { json } from '@sveltejs/kit'
import { createChatServer } from '@kispi/chat/server'
import { env } from '$env/dynamic/private'
const chat = createChatServer({
secretKey: env.CHAT_SECRET_KEY // sk_…
})
export const POST = async ({ locals }) => {
const user = locals.user // 서비스의 세션
if (!user) return new Response(null, { status: 401 })
return json({
token: chat.token({
userId: String(user.id), // 이 사람의 id
name: user.nickname,
avatar: user.avatarUrl, // 선택
ttlSeconds: 3600 // 선택. 기본 1시간, 최대 24시간
})
})
}# chat_token()은 "서버 연동" 쪽에 있다 — 여기서는 그것을 부르기만 한다
@app.post("/api/chat-token")
def issue_chat_token():
user = current_user() # 서비스의 세션
if user is None:
return "", 401
return {"token": chat_token(SK, str(user.id), user.nickname, ttl=3600)}// chatToken()은 "서버 연동" 쪽에 있다 — 여기서는 그것을 부르기만 한다
func issueChatToken(w http.ResponseWriter, r *http.Request) {
user, ok := currentUser(r) // 서비스의 세션
if !ok {
http.Error(w, "", http.StatusUnauthorized)
return
}
token, err := chatToken(sk, user.ID, user.Nickname, time.Hour)
if err != nil {
http.Error(w, "", http.StatusInternalServerError)
return
}
json.NewEncoder(w).Encode(map[string]string{"token": token})
}// chatToken()은 "서버 연동" 쪽에 있다 — 여기서는 그것을 부르기만 한다
@PostMapping("/api/chat-token")
fun issueChatToken(session: HttpSession): Map<String, String> {
val user = session.user ?: throw ResponseStatusException(HttpStatus.UNAUTHORIZED)
return mapOf("token" to chatToken(sk, user.id.toString(), user.nickname))
}chat.token()은 네트워크를 타지 않는 로컬 서명이라 요청마다 불러도 된다. 다른 언어도
같다 — 서명뿐이라 엔진을 부르지 않는다. name은 접속할 때마다 이 값으로 덮어쓴다. 토큰 규격
자체는 서버 연동에 있고, 로그인하지 않은 방문자는
비로그인 사용자가 같은 엔드포인트에서 발급하는 법을 적는다.
3. 브라우저가 주고받는다
iOS·Android·Flutter나 Swift·Kotlin·Dart·Python 같은 JS 밖의 언어라면 이 단계의 SDK 대신 실시간 프로토콜(WebSocket)과 REST API를 따른다. 토큰을 발급하는 2단계는 그대로다.
// chat.ts
import { createChatClient } from '@kispi/chat'
export const chat = createChatClient({
key: import.meta.env.VITE_CHAT_PK, // pk_…
token: async () => {
const res = await fetch('/api/chat-token', { method: 'POST' })
return (await res.json()).token
}
})
chat.on('state', (s) => setStatus(s)) // connecting | open | reconnecting | closed
chat.connect().catch(() => {})재접속과 토큰 갱신은 SDK가 한다. 방은 백엔드가 만든다 — 키로 연다고 방이 생기지 않고,
없는 키를 구독하면 not_found다. rooms.ensure는 있으면 그대로 돌려주는 get-or-create다.
// 백엔드. 2단계에서 만든 createChatServer 인스턴스다
await chat.rooms.ensure({ key: 'lobby', type: 'public' })방 key는 영문 대소문자·숫자와 _ . : -만 쓰고 1~128자다(^[A-Za-z0-9_.:-]{1,128}$).
한글이나 공백이 들어가면 400 invalid이므로, 사람이 읽는 이름은 name에 두고 key는 order-1234
같은 ASCII 별칭으로 정한다.
아래부터는 다시 브라우저, 3단계에서 만든 createChatClient 쪽이다.
const room = chat.roomByKey('lobby')
await room.subscribe() // 라이브 피드 + 최근 20건(엔진 기본 페이지)
room.on('messages', (all) => render(all)) // 목록이 바뀔 때마다 통째로
room.on('message.created', (m) => append(m)) // 또는 새 메시지 하나씩
const ack = await room.send({ text: '안녕' }) // { messageId, seq }
await room.send({ text: '이거 봐', attachments: [{ type: 'image', url, key }] })
await room.react(ack.messageId, '👍')
await room.markRead(room.lastSeq)
room.typing()
const { hasMore } = await room.loadOlder() // 스크롤을 올려 과거를 볼 때. 끝이면 falseroom.messages는 언제나 seq 오름차순이고 구멍이 없다. 바뀔 때마다 새 배열이라 참조로
비교하는 상태(Svelte $state.raw, React useState, Vue shallowRef)에 그대로 넣는다.
파일은 엔진이 보관하지 않는다 — 쓰고 있는 저장소(S3 같은 것)에 올리고 그 주소를
attachments에 싣는다(url은 https://로 시작해야 한다).
두 이벤트는 꼭 처리한다.
reset— SDK가 목록을 버리고 다시 채웠다. 렌더한 것을 버리고room.messages로 다시 그린다.error— 히스토리를 읽는 데 실패했다. 방이 스스로 다시 구독하므로 알리기만 한다.
| 저장되나 | 재접속 뒤 | |
|---|---|---|
| 메시지 | 된다 | SDK가 구멍을 메운다 |
| 리액션 | 된다 | 히스토리에 실려 온다. 끊긴 동안의 변화(리액션·스레드 수·수정·삭제)는 SDK가 재접속 때 방의 최근 한 페이지(20건)에 맞춘다. 그보다 오래된 행은 reload() |
읽음 커서(markRead) |
된다 | rooms.list()의 unread가 반영한다 |
| presence | 안 된다 | 새로 받는다 |
| typing | 안 된다 | 놓쳐도 된다. 한 사람당 많아야 3초에 한 번 오므로 마지막 것 뒤 5초쯤 보여 주고 지운다. 방마다 3초 창에 3명까지만 방송하므로 붐비는 방에서는 입력 중인데 알려지지 않는 사람이 있다 |
typing은 보낸 사람에게도 온다 — "X가 입력 중"을 그린다면 자기 userId는 건너뛴다.
실패는 ChatError로 던지고, err.code가 rate_limited면 err.retryAfterMs만큼 기다린다.
한도
속도와 크기의 한도는 앱마다 다르다. 기본값은 아래와 같고, 콘솔의 한도 탭에서 앱마다 보고 바꾼다.
| 한도 | 기본값 | 세는 단위 |
|---|---|---|
| 메시지 보내기 | 초당 5, 한꺼번에 10 | 유저 |
| 리액션 | 초당 10 | 유저 |
typing |
초당 20 | 유저 |
| 메시지 수정 | 초당 2 | 유저 |
| 접속 | 분당 10 | 유저 |
| 동시 연결 | 10 | 유저 |
| 접속 수립 | 분당 60 | pk_ + IP |
| 구독 | 100 | 연결 |
| 메시지 길이 | 4000자 | 메시지 |
| 첨부 | 10개 | 메시지 |
| 리액션 종류 | 20개 | 메시지 |
| 프레임 크기 | 64 KB | 연결 |
| 저장 메시지 수 | 제한 없음 | 앱 |
| 수정 가능 시간 | 제한 없음 | 메시지 |
- 서버 API(
sk_)로 보내는 메시지에는 속도 한도가 걸리지 않고, 수정 가능 시간도 적용되지 않는다. - 저장 메시지 수는 삭제된 메시지(tombstone)도 센다. 한도를 정한 앱이 가득 차면 새 메시지는
quota_exceeded(REST 403)로 거절되고, 기다려도 풀리지 않으므로 재시도하지 않는다. - 속도와 크기는 그 앱의 상한까지 올릴 수 있다. 낮추는 것도 되지만 프레임 크기는 기본 64 KB 아래로
내릴 수 없다. 보내기 대기열(
sendQueueSize)은 모든 앱에 같은 값으로 고정이다. - 붙어 있는 연결에는 30초 안에 닿는다. 접속에서 정해지는 값(접속 속도, 동시 연결, 구독 수, 프레임 크기)은
다음 접속부터다. 지금 걸린 값은 접속 때
hello.limits로도 온다.
4. 웹훅 (선택)
발행·수정·삭제를 백엔드가 들어야 할 때 쓴다 — 푸시 알림, 검색 색인, 감사 로그.
발행 전에 끼어들어 거절하거나 본문을 바꾸는 before_publish도 있다. 받는 쪽 코드와
서명 검증은 웹훅에 있다.
다음
- 서버 연동 — 토큰 규격, 서버 API, 키 교체.
- SDK 레퍼런스 — 모든 메서드와 이벤트.
- 실시간 프로토콜·REST API — iOS·Android·Flutter와 다른 언어에서 SDK 없이 붙을 때. 터미널에서 5분 안에 확인하는 방법이 있다.
- 아키텍처와 벤치마크 — 얼마나 버티는지, 어떻게 쟀고 무엇을 못 쟀는지.