跳轉至

WebSocket API

概述

WebSocket API 透過 Socket 伺服器與 WebSocket 通訊提供聊天服務。 支援遊戲客戶端連接、頻道消息傳送等功能。

WebSocket API的主要功能如下。

  • 客戶端連接 / 斷開
  • PING / PONG
  • 聊天消息發送 / 接收
    • 頻道聊天
    • 1:1 聊天
  • 封鎖用戶過濾
    • 不向被封鎖的用戶發送消息
    • 不接收來自被封鎖用戶的消息
  • 頻道進入、退出通知

基本信息

使用 WebSocket API 时，提供需要共同了解的基本信息。

主要術語

  • 頻道: 聊天室
  • 頻道消息: 發送給參與頻道的所有用戶的聊天消息
  • 1:1 消息: 僅發送給特定用戶的聊天消息

封包類型

Socket 伺服器傳送和接收的封包類型如下所示。

封包名稱 說明
CONNECT 連接 Socket 伺服器
RESPONSE_CONNECT 對 CONNECT 請求的回應
DISCONNECT 斷開 Socket 伺服器連接
RESPONSE_DISCONNECT 對 DISCONNECT 請求的回應
PING 保持連接
在 CONNECT 未成功的狀態下發送 PING 請求時，伺服器會斷開連接
PONG 對 PING 請求的回應
CHANNEL_CHAT 頻道聊天
RESPONSE_CHANNEL_CHAT 對 CHANNEL_CHAT 請求的回應
DIRECT_CHAT 1:1 聊天
RESPONSE_DIRECT_CHAT 對 DIRECT_CHAT 請求的回應
NOTIFY_ENTER_CHANNEL 頻道進入消息
NOTIFY_EXIT_CHANNEL 頻道退出消息
NOTIFY_DELETE_CHANNEL 頻道刪除消息
NOTIFY_CHANNEL_NOTICE 頻道公告消息
NOTIFY_CHANNEL_CHAT 頻道聊天消息
NOTIFY_DIRECT_CHAT 1:1 聊天消息
NOTIFY_DISCONNECT 斷開連接消息
當 WebSocket 連接處於閒置狀態且 Json 格式無效時，將以該封包類型回應

Socket 連接過程

  1. 在遊戲伺服器上通過聊天 Http API 請求發放令牌。※ 發放的令牌將用於連接聊天 Socket 伺服器

  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 物件
}

  • 其他数据包格式 

    {
        "packetType":"数据包类型",
        "body":{
                //根据 packetType 的 JSON 数据
        }
}

伺服器端斷開 WebSocket 連接的情況如下所示。

  • 當客戶端在1分鐘內沒有任何請求時
  • 當不是JSON格式時
  • 當status值為401或403時
    • 401 未授權
    • 403 禁止

回應代碼

回應狀態碼。

狀態碼 狀態訊息 說明
200 成功 成功
400 錯誤的請求 錯誤的請求
401 未授權 無權限
403 禁止 伺服器拒絕
408 請求超時 客戶端60秒內未發送請求，伺服器斷開連接
409 衝突 使用者的請求與伺服器狀態衝突 (例如：1:1聊天對方離線的情況)
500 內部伺服器錯誤 內部伺服器錯誤

WebSocket API 功能

說明用於聊天服務的 WebSocket API 的功能別 API 請求和回應、範例代碼。

客戶端連接

請求參數

欄位名稱 說明 類型 必要性
packetType 客戶端連接命令 (CONNECT) 字串 Y
body 請求數據 物件 Y
請求參數 > 主體
欄位名稱 說明 類型 必填與否 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
playerId 帳號識別碼
Hive 玩家 ID		 長整數 Y 例如 1234
loginKey 登入時使用的令牌
聊天 Http API發放		 字串 Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"
extraData 用戶附加資訊 (UTF-8 為準)
(最大 256 Byte)		 字串 N 例如 "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}"

回應主體

欄位名稱 說明 類型 必要性
packetType 連接請求的回應 (RESPONSE_CONNECT) 字串 Y
status 狀態碼 整數 Y
message 狀態消息 字串 Y
body 返回數據 物件 Y
回應主體 > 主體
欄位名稱 說明 類型 必要性 範例
sessionId 登入成功時返回的值 字串 Y 例如 "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"

請求範例

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "loginKey": JWT generated by API server,
                "extraData": Additional information
    }
}

回應範例

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

客戶端斷開連接

請求參數

欄位名稱 說明 類型 必需性
packetType 客戶端斷開連接命令 (DISCONNECT) 字串 Y
body 請求數據 物件 Y
請求參數 > 主體
欄位名稱 說明 類型 必要性 範例
sessionId 登入成功時返回的 sessionId 字串 N 例如 "6c2408fffe8c91a8-00002f24-00000032-093b757cdc668383-54b4fbc1"
  • 如果未指定 sessionId，則處理分配給 websocket 的 sessionId 的斷開連接
  • 如果指定 sessionId，則處理該值的斷開連接

回應主體

欄位名稱 說明 類型 必要性
packetType 對於斷開連接請求的回應 (RESPONSE_DISCONNECT) 字串 Y
status 狀態碼 整數 Y
message 狀態消息 字串 Y

請求範例

  • 如果未指定 sessionId 

    {
        "packetType":"DISCONNET"
}

  • 指定 sessionId 的情況下 

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

回應範例

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

PING / PONG

  • 只有在与 Socket 服务器的连接完成后，请求才有效
  • 如果没有 PONG 响应，则需要重新登录

請求參數

欄位名稱 說明 類型 必填與否
packetType PING 請求命令 (PING) 字串 Y

回應主體

欄位名稱 說明 類型 必填與否
packetType PONG 回應命令 (PONG) 字串 Y

請求範例

{
    "packetType":"PING"   
}

回應範例

{
    "packetType": "PONG"   
}

頻道消息傳送

請求參數

欄位名稱 說明 類型 必要性
packetType 頻道消息傳送命令 (CHANNEL_CHAT) 字串 Y
body 請求數據 物件 Y
请求参数 > body
字段名 说明 类型 必需性 示例
gameIndex Hive 游戏索引 integer Y 例如 1
from 发送消息到频道的账户标识符
Hive 玩家 ID		 long Y 例如 1234
to 发送消息到频道的频道 ID
聊天 Http API中创建		 string Y 例如 "open:1"
message 发送到频道的消息
(最多 200 字符)		 string Y 例如 "Hello World!"
langCode Hive 语言代码
(基于 ISO 639 alpha-2，ISO 639 alpha-2 不区分的语言使用 Script tag 区分)		 string Y 例如 "en"

回應主體

欄位名稱 說明 類型 必填 여부
packetType 對頻道消息傳送的回應 (RESPONSE_CHANNEL_CHAT) 字串 Y
status 狀態碼 整數 Y
message 狀態訊息 字串 Y

請求範例

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

回應範例

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

1:1 訊息傳送

請求參數

欄位名稱 說明 類型 必要性
packetType 1:1 訊息傳送命令 (DIRECT_CHAT) 字串 是
body 請求資料 物件 是
請求參數 > 主體
欄位名稱 說明 類型 必填與否 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
from 1:1 訊息傳送的帳戶識別碼
Hive 玩家 ID		 長整數 Y 例如 1234
to 1:1 訊息接收的帳戶識別碼
Hive 玩家 ID		 長整數 Y 例如 2222
message 1:1 傳送的訊息
(最多 200 字)		 字串 Y 例如 "Hello World!"
langCode Hive 語言代碼
(依據 ISO 639 alpha-2，對於不以 ISO 639 alpha-2 分隔的語言，請附上 Script 標籤以區分)		 字串 Y 例如 "en"

回應主體

欄位名稱 說明 類型 必填與否
packetType 1:1 消息傳送的回應 (RESPONSE_DIRECT_CHAT) 字串 Y
status 狀態代碼 整數 Y
message 狀態消息 字串 Y
回應主體 > 主體
欄位名稱 說明 類型 必填與否 範例
status 回應狀態碼 integer Y 例如 200

請求樣本

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

回應範例

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

Socket 伺服器事件消息

當事件發生時，說明從伺服器發送到客戶端的消息。

該消息以 packetType 為 NOTIFY 開頭。

頻道進入消息

欄位名稱 說明 類型 必要性
packetType 頻道進入消息 (NOTIFY_ENTER_CHANNEL) 字串 是
body 請求數據 物件 是

主體

欄位名稱 說明 類型 必填與否 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
channelId 進入的頻道 ID 字串 Y 例如 "open:10"
playerId 進入頻道的帳號識別碼
Hive 玩家 ID		 長整數 Y 例如 1234
extraData 用戶附加資訊 (UTF-8 為準)
(最大 256 Byte)		 字串 Y 例如 "abcd"
timestamp 進入頻道的時間 (UTC+0 為準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式) 字串 Y 例如 "2024-11-12T08:59:59.497Z"

範例

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

頻道退出消息

欄位名稱 說明 類型 必填 여부
packetType 頻道退出消息 (NOTIFY_EXIT_CHANNEL) 字串 Y
body 請求資料 物件 Y

主體

欄位名稱 說明 類型 必填與否 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
channelId 退出的頻道 ID 字串 Y 例如 "open:10"
playerId 頻道中退出的帳號識別碼
Hive 玩家 ID		 長整數 Y 例如 2222
extraData 用戶附加信息 (UTF-8 為準)
(最大 256 Byte)		 字串 Y 例如 "abcd"
timestamp 頻道中退出的時間 (UTC+0 為準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式) 字串 Y 例如 "2024-11-12T08:59:59.497Z"

範例

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

渠道刪除消息

欄位名稱 說明 類型 必需性
packetType 渠道刪除消息 (NOTIFY_DELETE_CHANNEL) 字串 Y
body 請求數據 物件 Y

主體

欄位名稱 說明 類型 必填與否 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
channelId 刪除的頻道 ID 字串 Y 例如 "open:10"
timestamp 刪除頻道的時間 (UTC+0 為基準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式) 字串 Y 例如 "2024-11-12T08:59:59.497Z"

樣本

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

頻道公告消息

欄位名稱 說明 類型 必要性
packetType 通知消息 (NOTIFY_CHANNEL_NOTICE) 字串 是
body 請求數據 物件 是

主體

欄位名稱 說明 類型 必填與否 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
channelId 公告消息接收的頻道 ID 字串 N 例如 "open:10"
from 公告消息發送的帳號識別碼 字串 Y 例如 SYSTEM
message 公告消息內容 字串 Y 例如 "這是公告消息。"
timestamp 公告消息發送的時間 (UTC+0 為基準，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式) 字串 Y 例如 "2024-11-13T05:06:29.198Z"

範例

// Announcement to specific channel
{
  "packetType": "NOTIFY_CHANNEL_NOTICE",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "from": "SYSTEM",
    "message": "Notice message.",
    "timestamp": "2024-11-13T05:06:29.198Z"
  }
}

頻道消息

欄位名稱 說明 類型 必要性
packetType 頻道消息 (NOTIFY_CHANNEL_CHAT) 字串 Y
body 請求數據 物件 Y

主體

欄位名稱 說明 類型 必填與否 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
from 發送頻道消息的帳戶識別碼
Hive 玩家 ID		 長整數 Y 例如 2222
fromExtra 用戶附加信息 (UTF-8 為準)
(最大 256 Byte)		 字串 Y 例如 "bbbb"
to 發送頻道消息的頻道 ID 字串 Y 例如 "open:10"
langCode Hive 語言代碼
(以 ISO 639 alpha-2 為準，對於不以 ISO 639 alpha-2 區分的語言，附加 Script 標籤以區分)		 字串 Y 例如 "ko"
timestamp 發送頻道消息的時間 (UTC+0 為準，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式) 字串 Y 例如 "2024-11-13T05:12:18.385Z"

範例

{
  "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 消息

字段名 说明 类型 必填 여부
packetType 1:1 消息 (NOTIFY_DIRECT_CHAT) 字符串 Y
body 请求数据 对象 Y

主體

欄位名稱 說明 類型 必填與否 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
from 1:1 訊息傳遞的帳號識別碼
Hive 玩家 ID		 長整數 Y 例如 1234
fromExtra 使用者附加資訊 (UTF-8 為準)
(最大 256 Byte)		 字串 Y 例如 "abcd"
to 1:1 訊息發送的帳號識別碼
Hive 玩家 ID		 長整數 Y 例如 2222
message 1:1 訊息內容 字串 Y 例如 "你好。這是 1:1 聊天。"
langCode Hive 語言代碼
(以 ISO 639 alpha-2 為準，對於不以 ISO 639 alpha-2 分隔的語言，請附加 Script 標籤以區分)		 字串 Y 例如 "ko"
timestamp 1:1 訊息發送的日期時間 (UTC+0 為準，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式) 字串 Y 例如 "2024-11-13T05:12:50.060Z"

範例

{
  "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"
  }
}