세션

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 연결은 AWS API Gateway WebSocket 기본 제약에 따라 최대 2시간 동안 유지됩니다. 2시간이 경과하면 서버에 의해 연결이 종료됩니다.
• WebSocket 연결에서 10분 동안 메시지가 없으면 WebSocket의 유휴 타임아웃으로 연결이 종료됩니다.
• WebSocket 연결이 서버에 의해 끊어질 수 있으므로, 자동 재연결 로직을 구현하는 것을 권장합니다.

참고: 세션 유효기간(12시간) 내에는 기존 sessionKey/url로 그대로 재연결할 수 있습니다. 재연결 시 기존 이벤트 구독도 유지되므로 재구독이 필요 없습니다. 세션이 만료되었거나(12시간 경과) 세션 수 제한으로 제거된 경우에만 세션을 새로 생성해야 합니다.

연결 유지 (PING)

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

전송 형식

{"type":"PING"}

응답 형식

{"action":"PONG"}

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

재연결

WebSocket 연결이 끊어진 경우, 세션이 아직 유효하다면(생성 후 12시간 이내) 기존 sessionKey/url로 그대로 재연결할 수 있습니다. 이때 기존 이벤트 구독은 유지되므로 재구독은 필요 없습니다.

1. 기존 url(sessionKey)로 WebSocket 재연결
2. (구독 유지됨 — 재구독 불필요)

세션이 만료되었거나(12시간 경과) 세션 수 제한으로 제거된 경우에만 세션을 새로 생성해야 하며, 세션 생성 엔드포인트는 세션 유형에 따라 다릅니다.

사용자 세션 (USER) 세션 재생성

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

클라이언트 세션 (CLIENT) 세션 재생성

1. 세션 생성 (GET /api/openapi/open/v1/sessions/auth/client, Client ID/Secret 필요)
2. WebSocket 연결 (응답의 url로 연결)
3. 이벤트 구독 (POST /api/openapi/open/v1/sessions/events/subscribe/{event})

주의: 클라이언트 세션을 새로 생성할 때는 /sessions/auth/client를 사용해야 합니다. USER용 /sessions/auth는 Access Token(Bearer)이 필요하므로 Client ID/Secret만으로 호출하면 401이 발생합니다.

세션 API

사용자 세션 생성

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

• 인증: Access Token (Bearer)

응답

클라이언트 세션 생성

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

• 인증: Client ID/Secret

응답

사용자 세션 목록 조회

애플리케이션에 속한 사용자 세션 목록을 조회합니다.

GET /api/openapi/open/v1/sessions

• 인증: Client ID/Secret

Query 파라미터

응답

클라이언트 세션 목록 조회

애플리케이션에 속한 클라이언트 세션 목록을 조회합니다.

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

• 인증: Client ID/Secret

Query 파라미터

응답

이벤트 구독

세션에 이벤트 구독을 추가합니다. 모두 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": { ... }
}