WebSocket API

개요¶

WebSocket API는 Socket 서버와 WebSocket 통신하여 채팅 서비스를 제공합니다. 게임 클라이언트 접속, 채널 메시지 전송 등을 지원합니다.

WebSocket API의 주요 기능은 아래와 같습니다.

• 클라이언트 접속 / 해제
• PING / PONG
• 채팅 메시지 전송 / 수신
  • 채널 채팅
  • 1:1 채팅
• 차단한 유저 필터링
  • 차단한 유저에게 메시지를 발신하지 않음
  • 차단한 유저로부터 메시지를 수신하지 않음
• 채널 입장, 퇴장 알림

기본 정보¶

WebSocket API 사용 시, 공통적으로 알아야 하는 기본 정보를 안내합니다.

주요 용어¶

• 채널: 채팅방
• 채널 메시지: 참여한 채널의 모든 유저에게 전송하는 채팅 메시지
• 1:1 메시지: 특정 유저에게만 전송하는 채팅 메시지

패킷 유형¶

Socket 서버와 전송 및 수신하는 패킷 유형은 아래와 같습니다.

Socket 접속 프로세스¶

1. 게임 서버에서 채팅 Http API로 토큰 발급 요청. ※ 발급된 토큰은 채팅 Socket 서버 연결에 사용됨

   • Hive Certification Key를 사용하여 유저 토큰 발급 API을 요청

2. 게임 클라이언트에서 Socket 서버로 접속 요청

   • WebSocket 통신
   • 1번 과정에서 발급된 토큰 사용
   • 접속에 성공하면 Socket 서버에서는 아래 정보를 반환

   {
       "packetType":"RESPONSE_CONNECT",
       "status": 200,
       "message": "OK",
       "body":{
           "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
       }
   }
   

Socket 통신 구조¶

• 'RESPONSE_'로 시작하는 패킷 유형의 JSON 형식

  {
          "packetType":"패킷 유형",
          "status":"상태 코드",
          "message":"상태 메시지",
          "body": JSON Object
  }
  

• 그 외의 패킷 형식

  {
          "packetType":"패킷 유형",
          "body":{
                  //packetType 에 따른 JSON 데이터
          }
  }
  

서버 측에서 WebSocket 연결 해제하는 경우는 아래에 해당됩니다.

• 클라이언트 측에서 1분간 아무런 요청이 없을 경우
• JSON 형식이 아닐 때
• status 값이 401, 403 일 때
  • 401 unauthorized
  • 403 forbidden

응답 코드¶

응답 상태 코드입니다.

WebSocket API 기능¶

채팅 서비스에 이용되는 WebSocket API의 기능 별 API 요청 및 응답, 예제 코드를 설명합니다.

클라이언트 접속¶

Request parameters¶

Request parameters > body¶

Response body¶

Response body > body¶

Request sample¶

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "loginKey": API 서버에서 생성한 JWT,
        "extraData":부가정보
    }
}

Response sample¶

{
    "packetType":"RESPONSE_CONNECT",
    "status": 200,
    "message":"OK",
    "body":{
        "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
    }
}

클라이언트 접속 해제¶

Request parameters¶

Request parameters > body¶

• sessionId 를 지정하지 않을 경우, websocket 에 할당된 sessionId 에 대한 연결해제 처리
• sessionId 를 지정할 경우, 해당 값에 대한 연결해제 처리

Response body¶

Request sample¶

• sessionId를 지정하지 않은 경우

  {
          "packetType":"DISCONNET"
  }
  

• sessionId를 지정하는 경우

  {
          "packetType":"DISCONNECT",
          "body":{
                  "sessionId":"6c2408fffe8c91a8-00002f24-00000032-093b757cdc668383-54b4fbc1"
          }
  }
  

Response Sample¶

{
    "packetType": "RESPONSE_DISCONNECT",
    "status": 200,
    "message":"OK"
}

PING / PONG¶

• Socket 서버와 CONNECT가 완료된 상태에서만 요청이 유효
• PONG 응답이 없을 경우 재로그인 필요

Request parameters¶

Response body¶

Request sample¶

{
    "packetType":"PING"   
}

Response sample¶

{
    "packetType": "PONG"   
}

채널 메시지 전송¶

Request parameters¶

Request parameters > body¶

Response body¶

Request sample¶

{
    "packetType":"CHANNEL_CHAT",
    "body": {
        "gameIndex": 1,
        "from": 1234,
        "to": "open:1",
        "message": "Hello World!",
        "langCode": "en"
    }
}

Response sample¶

{
    "packetType": "RESPONSE_CHANNEL_CHAT",
    "status": 200,
    "message":"OK"
}

1:1 메시지 전송¶

Request parameters¶

Request parameters > body¶

Response body¶

Response body > body¶

Request sample¶

{
  "packetType": "DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 2222,
    "to": 1234,
    "message": "안녕하세요",
    "langCode": "ko"
  }
}

Response sample¶

{
    "packetType": "RESPONSE_DIRECT_CHAT",
    "status": 200,
    "message":"OK"
}

Socket 서버 이벤트 메시지¶

이벤트 발생 시, Server에서 Client로 전송되는 메시지를 설명합니다.

해당 메시지는 packetType이 NOTIFY 로 시작합니다.

채널 입장 메시지¶

Body¶

Sample¶

{
  "packetType": "NOTIFY_ENTER_CHANNEL",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "playerId": 1234,
    "extraData": "abcd",
    "timestamp": "2024-11-12T08:59:59.497Z"
  }
}

채널 퇴장 메시지¶

Body¶

Sample¶

{
  "packetType": "NOTIFY_EXIT_CHANNEL",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "playerId": 2222,
    "extraData": "abcd",
    "timestamp": "2024-11-12T09:29:35.872Z"
  }
}

채널 삭제 메시지¶

Body¶

Sample¶

{
  "packetType": "NOTIFY_DELETE_CHANNEL",
  "body": {
    "gameIndex": 1,
    "channelId": "owner:1",
    "timestamp": "2024-11-13T05:06:29.198Z"
  }
}

채널 공지 메시지¶

Body¶

Sample¶

// 특정 채널에 공지
{
  "packetType": "NOTIFY_CHANNEL_NOTICE",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "from": "SYSTEM",
    "message": "공지 메시지 입니다.",
    "timestamp": "2024-11-13T05:06:29.198Z"
  }
}

채널 메시지¶

Body¶

Sample¶

{
  "packetType": "NOTIFY_CHANNEL_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 2222,
    "fromExtra": "bbbb",
    "to": "open:10",
    "message": "Hello World!",
    "langCode": "ko",
    "timestamp": "2024-11-13T05:12:18.385Z"
  }
}

1:1 메시지¶

Body¶

Sample¶

{
  "packetType": "NOTIFY_DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 1234,
    "fromExtra": "abcd",
    "to": 2222,
    "message": "안녕하세요. 1:1 채팅입니다.",
    "langCode": "ko",
    "timestamp": "2024-11-13T05:12:50.060Z"
  }
}