세션

WebSocket을 통해 실시간 이벤트를 수신하려면 먼저 세션을 생성해야 합니다.

세션 생성 → WebSocket 연결 → 이벤트 구독 → 실시간 이벤트 수신

세션 유형

지원 이벤트

WebSocket 연결

세션 생성 API 응답에 포함된 url로 WebSocket 연결을 수립합니다.

wss://{socketHost}/?type=OPENAPI_SESSION&sessionKey={sessionKey}

중요: 표준 WebSocket(RFC 6455)을 사용해야 합니다. Socket.IO, SockJS 등의 라이브러리는 자체 프로토콜 계층을 추가하므로 호환되지 않습니다. 브라우저의 new WebSocket(url) 또는 각 언어의 표준 WebSocket 클라이언트를 사용하세요.

제한사항

• 세션당 최대 30개의 이벤트 구독이 가능합니다.
• 세션은 생성 후 12시간 동안 유효합니다.
• WebSocket 연결은 최대 2시간 동안 유지됩니다. 2시간이 경과하면 서버에 의해 연결이 종료됩니다.
• WebSocket 연결에서 10분 동안 메시지가 없으면 유휴 타임아웃으로 연결이 종료됩니다.
• WebSocket 연결이 서버에 의해 끊어질 수 있으므로, 자동 재연결 로직을 구현하는 것을 권장합니다.

연결 유지 (PING)

유휴 타임아웃을 방지하려면 주기적으로 PING 메시지를 전송해야 합니다.

전송 형식

{"type":"PING"}

응답 형식

{"action":"PONG"}

• 1분 간격으로 PING 메시지를 전송하는 것을 권장합니다.

재연결

WebSocket 연결이 끊어진 경우 다음 순서로 재연결합니다.

1. Access Token 만료 여부 확인, 만료 시 Refresh Token으로 갱신
2. 세션 재생성 (GET /api/openapi/open/v1/sessions/auth)
3. WebSocket 재연결 (응답의 url로 연결)
4. 이벤트 재구독 (POST /api/openapi/open/v1/sessions/events/subscribe/{event})

세션 API

사용자 세션 생성

GET /api/openapi/open/v1/sessions/auth

• 인증: Access Token (Bearer)

응답

클라이언트 세션 생성

GET /api/openapi/open/v1/sessions/auth/client

• 인증: Client ID/Secret

응답

이벤트 구독

세션에 이벤트 구독을 추가합니다. 모두 Access Token (Bearer) 인증을 사용합니다.

POST /api/openapi/open/v1/sessions/events/subscribe/{event}

{event}에 들어갈 수 있는 값:

• chat — 채팅 이벤트 (Scope: READ:LIVE_CHAT)
• donation — 후원 이벤트 (Scope: READ:DONATION)
• subscription — 구독 이벤트 (Scope: READ:SUBSCRIPTION)

Query 파라미터

응답: 200 OK, 응답 본문 없음

이벤트 구독 해제

세션에서 이벤트 구독을 해제합니다. 모두 Access Token (Bearer) 인증을 사용합니다.

POST /api/openapi/open/v1/sessions/events/unsubscribe/{event}

{event}에 들어갈 수 있는 값:

• chat — 채팅 이벤트 (Scope: READ:LIVE_CHAT)
• donation — 후원 이벤트 (Scope: READ:DONATION)
• subscription — 구독 이벤트 (Scope: READ:SUBSCRIPTION)

Query 파라미터

응답: 200 OK, 응답 본문 없음

WebSocket 메시지 형식

이벤트 구독 후 수신되는 메시지는 다음과 같은 공통 JSON 형식입니다.

{
  "event": "CHAT",
  "data": { ... }
}