WebSocket API

概述¶

WebSocket API 透過 WebSocket 與 Socket 伺服器進行通信，提供聊天服務。它支持遊戲客戶端連接、頻道消息傳輸等功能。

WebSocket API 的主要特點如下。

客戶端連接 / 斷開連接
PING / PONG
發送 / 接收聊天消息
- 頻道聊天
- 1:1 聊天
過濾被封鎖的用戶
- 不向被封鎖的用戶發送消息
- 不接收來自被封鎖的用戶的消息
頻道加入和離開通知

基本信息¶

這提供了使用 WebSocket API 時需要知道的基本資訊。

關鍵術語¶

頻道: 聊天室
頻道消息: 發送給已加入頻道的所有用戶的聊天消息
1:1 消息: 僅發送給特定用戶的聊天消息

封包類型¶

與套接字伺服器發送和接收的數據包類型如下。

封包名稱	描述
CONNECT	連接到套接字伺服器
RESPONSE_CONNECT	對CONNECT請求的回應
RECONNECT	重新連接到套接字伺服器
RESPONSE_RECONNECT	對RECONNECT請求的回應
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格式無效時，會以此封包類型回應

插座連接過程¶

透過遊戲伺服器上的聊天 Http API 請求發行令牌。 ※ 發行的令牌用於連接聊天 Socket 伺服器
- 使用 Hive 認證金鑰請求用戶令牌發行 API

遊戲客戶端向 Socket 伺服器的連接請求

WebSocket 通信
使用第 1 步驟中發出的令牌
如果連接成功，Socket 伺服器將返回以下信息

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

插座斷線¶

當WebSocket連接終止時，伺服器會執行以下操作。

退出參與的頻道並發送退出通知消息
刪除連接信息

插座通信结构¶

WebSocket 通信是以 JSON 格式进行的。请求数据包格式如下。

{
        "packetType":"Packet type",
        "correlationId":"Identifier for matching the response to the request",
        "body": {
                // JSON data according to packetType
        }
}

以下是响应数据包格式。

{
        "packetType":"Packet type (starts with RESPONSE)",
        "correlationId":"Identifier for matching the response to the request",
        "status":"Status code",
        "message":"Status message",
        "body": // JSON Object
}

以下是伺服器訊息封包格式。

{
        "packetType":"Packet type (starts with NOTIFY)",
        "body":{
                // JSON data according to packetType
        }
}

當伺服器端斷開 WebSocket 連接時，以下情況適用。

如果客戶端在 1 分鐘內沒有請求
當它不是 JSON 格式
當狀態值為 401 或 403
- 401 未授權
- 403 禁止
如果從另一個會話訪問，現有會話將被終止

回應代碼¶

這是回應狀態碼。

狀態碼	狀態訊息	描述
200	成功。	成功
400	錯誤的請求	錯誤的請求
401	未授權	未授權
403	禁止	伺服器禁止
408	請求超時	由於客戶端60秒內沒有請求，伺服器關閉了連接
409	衝突	用戶的請求與伺服器狀態衝突（例如，當1:1聊天中的聊天夥伴離線時）
500	內部伺服器錯誤	內部伺服器錯誤

Websocket API 功能¶

這解釋了聊天服務中使用的WebSocket API每個功能的API請求和響應，以及示例代碼。

客戶訪問¶

請求參數¶

欄位名稱	描述	類型	必填
packetType	客戶端連接命令 (`CONNECT`)	字串	是
body	請求數據	物件	是

請求參數 > 主體¶

字段名称	描述	类型	必需	示例
gameIndex	Hive 游戏索引	整数	是	例如 1
playerId	账户标识符 Hive 玩家 ID	长整型	是	例如 1234
loginKey	用于访问的令牌从 Chat Http API 发行	字符串	是	"eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"
extraData	用户附加信息 (`UTF-8` 基础) (最多 256 字节)	字符串	否	例如 "{\"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": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY", // JWT generated by the API server
        "extraData": "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}" // Additional information
    }
}

回應範例¶

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

客戶端重新連接¶

重連功能是因為WebSocket連接可能會根據網絡情況而斷開。如果在WebSocket連接斷開後的10分鐘內發出RECONNECT請求，您將進入您之前參加的頻道。

請求參數¶

欄位名稱	描述	類型	是否必填
packetType	客戶端重新連接命令 (`RECONNECT`)	字串	是
body	請求資料	物件	是

請求參數 > 主體¶

字段名稱	描述	類型	必需	範例
gameIndex	Hive 遊戲索引	整數	Y	例如 1
playerId	帳戶識別碼 Hive 玩家 ID	長整數	Y	例如 1234
loginKey	用於訪問的令牌聊天 HTTP API 發出	字串	Y	"eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"
extraData	用戶附加信息 (`UTF-8` 基礎) (最大 256 字節)	字串	N	例如 "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}"

回應主體¶

欄位名稱	描述	類型	必需
packetType	重新連接請求的回應（`RESPONSE_RECONNECT`）	字串	是
status	狀態碼	整數	是
message	狀態訊息	字串	是
body	返回的數據	物件	是

回應主體 > 主體¶

字段名稱	描述	類型	必需	範例
sessionId	成功連接後返回的值	字串	是	例如 "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
channelIds	在先前參與的頻道中成功進入的頻道列表	陣列	是	例如 ["ch:1", "ch:2"]
failChannelIds	在先前參與的頻道中未能進入的頻道列表	陣列	是	例如 []

請求範例¶

{
    "packetType": "RECONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY", // JWT generated by the API server
        "extraData": "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}" // Additional information
    }
}

回應範例¶

{
    "packetType":"RESPONSE_RECONNECT",
    "status": 200,
    "message":"OK",
    "body":{
        "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76",
        "channelIds":["ch:1", "ch:2"], // List of channels successfully joined from previously participated channels
        "failChannelIds":[]                // List of channels that failed to join from previously participated channels
    }
}

PING / PONG¶

當套接字伺服器和 CONNECT 完成時，請求才有效。
如果沒有 PONG 回應，則需要重新登錄。

請求參數¶

欄位名稱	描述	類型	必需
packetType	PING 請求命令 (`PING`)	字串	Y

回應主體¶

欄位名稱	描述	類型	必需
packetType	PONG 回應命令 (`PONG`)	字串	Y

請求範例¶

{
    "packetType":"PING"   
}

回應範例¶

{
    "packetType": "PONG"   
}

頻道消息發送¶

請求參數¶

欄位名稱	描述	類型	必填
packetType	頻道消息傳輸命令 (`CHANNEL_CHAT`)	字串	Y
body	請求數據	物件	Y

請求參數 > 主體¶

字段名稱	描述	類型	必需	範例
gameIndex	Hive 遊戲索引	整數	Y	例如 1
from	要發送消息到的帳戶識別符 Hive 玩家 ID	長整數	Y	例如 1234
to	發送頻道消息的頻道 ID 聊天 HTTP API 創建的	字串	Y	例如 "open:1"
message	要發送到頻道的消息 (最多 200 個字符)	字串	Y	例如 "Hello World!"
langCode	Hive 語言代碼 (基於 ISO 639 alpha-2，未被 ISO 639 alpha-2 區分的語言應使用腳本標籤區分)	字串	Y	例如 "en"

回應主體¶

欄位名稱	描述	類型	必填
packetType	對頻道消息傳輸的回應 (`RESPONSE_CHANNEL_CHAT`)	字串	是
status	狀態碼	整數	是
message	狀態消息	字串	是

請求範例¶

{
    "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	回應狀態碼	整數	Y	例如 200

請求範例¶

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

回應範例¶

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

插座伺服器事件消息¶

這解釋了當事件發生時，從伺服器發送到客戶端的消息。

這條消息以 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 字節）	字串	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`)	字串	是
body	請求數據	物件	是

主體¶

欄位名稱	描述	類型	是否必填	範例
gameIndex	Hive 遊戲索引	整數	Y	例如 1
channelId	已退出的頻道 ID	字串	Y	例如 "open:10"
playerId	已退出頻道的帳號識別碼 Hive 玩家 ID	長整數	Y	例如 2222
extraData	用戶附加信息 (`UTF-8` 編碼) (最大 256 字節)	字串	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"

樣本¶

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

頻道消息¶

字段名称	描述	类型	必需
packetType	通道消息 (`NOTIFY_CHANNEL_CHAT`)	字符串	是
body	请求数据	对象	是

主體¶

欄位名稱	描述	類型	必需	範例
gameIndex	Hive 遊戲索引	整數	Y	例如 1
from	發送頻道消息的帳戶識別碼 Hive 玩家 ID	長整數	Y	例如 2222
fromExtra	用戶附加信息（`UTF-8` 基礎）（最大 256 字節）	字串	Y	例如 "bbbb"
to	發送頻道消息的頻道 ID	字串	Y	例如 "open:10"
langCode	Hive 語言代碼（基於 ISO 639 alpha-2，未由 ISO 639 alpha-2 區分的語言應通過附加腳本標籤來區分）	字串	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`)	字串	是
body	請求資料	物件	是

主體¶

字段名称	描述	类型	必需	示例
gameIndex	Hive 游戏索引	整数	Y	例如 1
from	1:1 消息发送者账户标识符 Hive 玩家 ID	长整型	Y	例如 1234
fromExtra	用户附加信息（`UTF-8` 编码）（最大 256 字节）	字符串	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 未区分的语言通过脚本标签分隔）	字符串	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"
  }
}