실시간 (Realtime)

WebSocket 기반 실시간 통신 API입니다. 채팅, 알림, 협업 기능 등에 사용합니다.

📌 cb.realtime 은 카테고리(category) 기반 pub/sub 입니다. 카테고리는 콘솔에서 생성하거나 서버에서 자동 생성된 이름(예: chat-room-1)을 사용합니다.

연결

typescript

// Public Key 만으로 연결 (게스트)
await cb.realtime.connect()

// 또는 앱 멤버 토큰으로 연결
const guest = await cb.auth.signInAsGuestMember()
await cb.realtime.connect({ accessToken: guest.access_token })

connect() 의 옵션:

옵션	타입	기본값	설명
`accessToken`	string	-	앱 멤버 JWT (지정 시 Public Key 대신 사용)
`userId`	string	-	표시용 사용자 식별자
`maxRetries`	number	5	자동 재연결 횟수
`retryInterval`	number	1000	재연결 간격 (ms)
`timeout`	number	30000	응답 대기 타임아웃 (ms)
`debug`	boolean	false	디버그 로그

카테고리 구독

typescript

const chat = await cb.realtime.subscribe('chat-room-1')

console.log(chat.info.category, chat.info.persist)

subscribe() 가 반환하는 Subscription 객체는 다음 메서드를 가집니다:

메서드	설명
`onMessage(handler)`	메시지 수신 핸들러 등록 (해제 함수 반환)
`send(data, options?)`	메시지 전송
`getHistory(limit?)`	히스토리 조회 (`persist=true` 카테고리만)
`unsubscribe()`	구독 해제

메시지 수신 / 전송

typescript

const chat = await cb.realtime.subscribe('chat-room-1')

// 수신 핸들러 등록
const off = chat.onMessage<{ text: string; from: string }>((msg) => {
  console.log('새 메시지:', msg.data.text, 'from', msg.data.from)
})

// 전송 (기본적으로 발신자에게도 echo 됨)
await chat.send({ text: '안녕!', from: 'me' })

// echo 없이 전송
await chat.send({ text: '...' }, { includeSelf: false })

// 핸들러 해제
off()

히스토리 조회

persist=true 로 설정된 카테고리만 메시지를 저장합니다.

typescript

if (chat.info.persist) {
  const history = await chat.getHistory(50)
  history.messages.forEach((m) => {
    console.log(m.from, m.data, new Date(m.sentAt).toISOString())
  })
}

구독 해제 / 연결 종료

typescript

await chat.unsubscribe()
cb.realtime.disconnect()

연결 상태

typescript

const state = cb.realtime.getState()
// 'disconnected' | 'connecting' | 'connected' | 'reconnecting'

cb.realtime.connectionId  // 현재 연결 ID
cb.realtime.appId          // 연결된 앱 ID

AI 스트리밍

LLM 응답을 토큰 단위로 스트리밍 받을 수 있습니다.

typescript

await cb.realtime.connect()

const session = await cb.realtime.stream(
  [{ role: 'user', content: '안녕하세요' }],
  {
    onToken: (token) => process.stdout.write(token),
    onDone: (result) => console.log('\n완료:', result.fullText),
    onError: (e) => console.error('에러:', e)
  },
  { provider: 'gemini', model: 'gemini-2.0-flash', temperature: 0.7 }
)

// 필요 시 중지
await session.stop()

자동 재연결

SDK는 maxRetries 만큼 자동으로 재연결을 시도합니다. 별도 핸들러 등록 없이 동작합니다.

함수 (Functions)

WebRTC