구축 범위
- 프로토콜
- WebSocket (RFC 6455) / SSE
- 인증 방식
- API Key (Header / Query)
- 이벤트 채널
- game · wallet · agent · admin
- 메시지 형식
- JSON
- 재연결 보장
- 최대 5분 이내 누락 이벤트 재전송
- 최대 구독 채널
- 연결당 16개
연결 방식 및 인증
WebSocket 엔드포인트(`wss://api.gamesolution.kr/stream`)에 연결 시 헤더 또는 쿼리 파라미터로 API 키를 전달합니다. 연결 수립 후 구독할 채널(Channel)과 이벤트 타입(Event Type)을 JSON 메시지로 선언합니다.
SSE 방식은 단방향 서버→클라이언트 스트림이 필요한 경우 사용합니다. REST 폴링 대비 서버 부하를 줄이면서 최대 수백 ms 단위의 갱신 주기를 유지할 수 있습니다. SSE 엔드포인트는 HTTP/2 멀티플렉싱을 활용하여 다수의 스트림을 단일 TCP 연결로 처리합니다.
이벤트 채널 구조
스트리밍 API는 `game`, `wallet`, `agent`, `admin` 네 가지 채널을 제공합니다. `game` 채널은 라운드 시작·결과·취소 이벤트를, `wallet` 채널은 입출금·정산 이벤트를, `agent` 채널은 하위 에이전트 활동 요약을 실시간으로 전송합니다.
이벤트 페이로드는 `type`, `timestamp`, `data` 필드를 기본으로 포함하는 JSON 스키마를 사용합니다. 버저닝(Versioning)은 채널 선언 시 `version` 파라미터로 지정하며, 구 버전과의 하위 호환성을 보장합니다.
재연결 및 메시지 보장
클라이언트 연결이 끊어졌다가 재연결될 경우, 마지막 수신 이벤트 ID(`Last-Event-ID`)를 헤더에 포함하면 누락 이벤트를 최대 5분 이내 범위에서 재전송합니다. 이 메커니즘은 모바일 환경의 네트워크 단절 상황에서 데이터 일관성을 보장합니다.
메시지 순서는 채널 내에서 단조 증가하는 시퀀스 번호(Sequence Number)로 보장됩니다. 중복 수신 방지를 위해 각 이벤트는 전역 고유 ID를 갖습니다.
자주 묻는 질문
- WebSocket 연결 유지 시간(Keep-Alive) 정책은 어떻게 되나요?
- 30초마다 서버에서 Ping 프레임을 전송합니다. 클라이언트가 60초 이내에 Pong을 응답하지 않으면 연결이 종료됩니다. 클라이언트 SDK에는 자동 재연결 로직이 포함되어 있으며, Exponential Backoff 방식으로 재시도합니다.
- 스트리밍 API의 SLA는 어떻게 되나요?
- 정상 운영 시 p99 레이턴시 150ms 이내, 월간 가용성 99.9%를 목표로 합니다. 구체적인 SLA 조건은 B2B 계약 협의 시 파트너 요구사항에 맞춰 조정됩니다.
게임 플랫폼 개발 프로젝트 — 기술 상담 시작
개발하려는 플랫폼 유형(라이브·스포츠·테이블·로터리)과 희망 일정을 공유해 주시면 구축 범위와 견적을 맞춥니다. 연동할 게임 API와 에이전트 구조도 함께 알려주시면 더 정확한 제안을 드립니다.