跳轉至

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格式無效時，會以此封包類型回應

插座連接過程

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

  2. 遊戲客戶端向 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"
  }
}