跳轉至

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_NOTICE 用戶通知消息
NOTIFY_CHANNEL_CHAT 頻道聊天消息
NOTIFY_DIRECT_CHAT 1:1聊天消息

插座連接過程

  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 matching the response to the request",
        "body": {
                //JSON data according to packetType
        }
}


以下是响应数据包格式。

{
        "packetType":"Packet type (starts with RESPONSE)",
        "correlationId":"Identifier 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 遊戲索引 整數 Y 例如 1
playerId 帳戶識別碼
玩家 ID		 長整數 Y 例如 1234
langCode Hive 語言代碼
(基於 ISO 639 alpha-2，未被 ISO 639 alpha-2 區分的語言由 Script 標籤分隔)		 字串 Y 例如 "en"
loginKey 用於連接的令牌
由 Chat Http API 發出		 字串 Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"

回應主體

欄位名稱 描述 類型 必需
packetType 連接請求的回應 (RESPONSE_CONNECT) 字串 是
status 狀態碼 整數 是
message 狀態訊息 字串 是
body 返回數據 物件 是
回應主體 > 主體
欄位名稱 描述 類型 必填 範例
sessionId 成功連接後返回的值 字串 Y 例如 "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"

請求範例

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "langCode": "en",
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" // JWT created by the API server
    }
}

回應範例

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

客戶端重新連接

WebSocket 提供了一個重新連接的功能，因為連接可能會根據網絡情況而終止。如果在 WebSocket 斷開連接後的 10 分鐘內發出 RECONNECT 請求，它將重新加入之前加入的頻道。

請求參數

欄位名稱 描述 類型 必需
packetType 客戶端重新連接命令 (RECONNECT) 字串 Y
body 請求數據 物件 Y
請求參數 > 主體
欄位名稱 描述 類型 是否必填 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
playerId 帳戶識別碼
玩家 ID		 長整數 Y 例如 1234
langCode Hive 語言代碼
(基於 ISO 639 alpha-2，未由 ISO 639 alpha-2 區分的語言由 Script 標籤分隔)		 字串 Y 例如 "en"
loginKey 用於連接的令牌
由 Chat Http API 發出		 字串 Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"

回應主體

欄位名稱 描述 類型 是否必需
packetType 重新連接請求的回應 (RESPONSE_RECONNECT) 字串 是
status 狀態碼 整數 是
message 狀態訊息 字串 是
body 返回數據 物件 是
回應主體 > 主體
欄位名稱 描述 類型 必需 範例
sessionId 成功連接後返回的值 字串 Y 例如 "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
channelIds 從先前加入的頻道成功重新加入的頻道列表 字串陣列 Y 例如 ["ch:1", "ch:2"]
failChannelIds 從先前加入的頻道未能重新加入的頻道列表 字串陣列 Y 例如 []

請求範例

{
    "packetType": "RECONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "langCode": "en",
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" // JWT created by the API server
    }
}

回應範例

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

PING / PONG

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

請求參數

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

回應主體

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

請求範例

{
    "packetType":"PING"   
}

回應範例

{
    "packetType": "PONG"   
}

發送頻道消息

請求參數

字段名稱 描述 類型 必需
packetType 頻道消息發送命令 (CHANNEL_CHAT) 字串 是
body 請求數據 物件 是
請求參數 > 主體
字段名称 描述 类型 必需 示例
gameIndex Hive 游戏索引 整数 Y 例如 1
from 发送消息到频道的账户标识符
玩家 ID		 长整型 Y 例如 1234
to 发送频道消息的频道 ID
聊天 HTTP API中创建		 字符串 Y 例如 "open:1"
message 要发送到频道的消息
(最多 200 个字符)		 字符串 Y 例如 "Hello World!"
extraData 附加消息信息 (基于 UTF-8)
(最多 256 字节)		 字符串 Y 例如 "bbbb"
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!",
        "extraData": "bbbb",
        "langCode": "en"
    }
}

回應範例

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

發送 1:1 訊息

請求參數

欄位名稱 描述 類型 是否必填
packetType 1:1 訊息發送命令 (DIRECT_CHAT) 字串 Y
body 請求資料 物件 Y
請求參數 > 主體
字段名稱 描述 類型 必需 示例
gameIndex Hive 遊戲索引 整數 Y 例如 1
from 發送 1:1 消息的帳號識別符
玩家 ID		 長整數 Y 例如 1234
to 接收 1:1 消息的帳號識別符
玩家 ID		 長整數 Y 例如 2222
message 要發送的 1:1 消息
(最多 200 個字符)		 字串 Y 例如 "Hello World!"
extraData 附加消息信息 (基於 UTF-8)
(最多 256 字節)		 字串 Y 例如 "bbbb"
langCode 發送消息的語言代碼
Hive 語言代碼
(基於 ISO 639 alpha-2，ISO 639 alpha-2 無法區分的語言由 Script 標籤分隔)		 字串 Y 例如 "en"

回應主體

欄位名稱 描述 類型 必需
packetType 回應 1:1 訊息發送 (RESPONSE_DIRECT_CHAT) 字串 是
status 狀態碼 整數 是
message 狀態訊息 字串 是
回應主體 > 主體
欄位名稱 描述 類型 必填 範例
status 回應狀態碼 整數 Y 例如 200

請求範例

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

回應範例

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

Socket 伺服器事件消息

本節描述了當事件發生時，從伺服器發送到客戶端的消息。

這些消息在 packetType 中以 NOTIFY 開頭。

頻道條目消息

欄位名稱 描述 類型 必填
packetType 通道進入消息 (NOTIFY_ENTER_CHANNEL) 字串 Y
body 請求數據 物件 Y

主體

欄位名稱 描述 類型 是否必填 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
channelId 進入的頻道 ID 字串 Y 例如 "open:10"
playerId 進入頻道的帳戶識別碼
玩家 ID		 長整數 Y 例如 1234
timestamp 進入頻道的時間 (UTC+0 標準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式) 字串 Y 例如 "2024-11-12T08:59:59.497Z"
timestampMillis 進入頻道的時間 (UnixTimestamp 毫秒) 長整數 Y 例如 1731401989

範例

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

頻道退出消息

欄位名稱 描述 類型 必需
packetType 通道退出消息 (NOTIFY_EXIT_CHANNEL) 字串 Y
body 請求數據 物件 Y

主體

欄位名稱 描述 類型 必填 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
channelId 退出的頻道ID 字串 Y 例如 "open:10"
playerId 退出頻道的帳號識別碼
玩家ID		 長整數 Y 例如 2222
timestamp 從頻道退出的時間（UTC+0 標準，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式） 字串 Y 例如 "2024-11-12T08:59:59.497Z"
timestampMillis 從頻道退出的時間（Unix時間戳毫秒） 長整數 Y 例如 1731401989

範例

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

頻道刪除訊息

欄位名稱 描述 類型 是否必填
packetType 渠道刪除訊息 (NOTIFY_DELETE_CHANNEL) 字串 是
body 請求資料 物件 是

主體

欄位名稱 描述 類型 必填 範例
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"
timestampMillis 頻道刪除時間（UnixTimestamp 毫秒） 長整數 Y 例如 1731401989

範例

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

頻道通知消息

欄位名稱 描述 類型 是否必填
packetType 通知消息 (NOTIFY_CHANNEL_NOTICE) 字串 是
body 請求數據 物件 是

主體

字段名稱 描述 類型 必需 示例
gameIndex Hive 遊戲索引 整數 Y 例如 1
channelId 接收通知消息的頻道ID 字串 Y 例如 "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"
timestampMillis 發送通知消息的時間（UnixTimestamp 毫秒） 長整數 Y 例如 1731401989

範例

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

使用者通知訊息

欄位名稱 描述 類型 是否必填
packetType 用戶通知消息 (NOTIFY_NOTICE) 字串 是
body 請求數據 物件 是

主體

字段名稱 描述 類型 必需 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
playerId 接收通知消息的玩家ID 長整數 Y 例如 123123
from 發送通知消息的帳戶識別符 字串 Y 例如 SYSTEM
message 通知消息的內容 字串 Y 例如 "這是一條通知消息。"
timestamp 發送通知消息的時間（UTC+0 標準，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式） 字串 Y 例如 "2024-11-13T05:06:29.198Z"
timestampMillis 發送通知消息的時間（Unix時間戳毫秒） 長整數 Y 例如 1731401989

範例

// Notice to a specific user
{
  "packetType": "NOTIFY_NOTICE",
  "body": {
    "gameIndex": 1,
    "playerId": 123123,
    "from": "SYSTEM",
    "message": "This is a notice message.",
    "timestamp": "2024-11-13T05:06:29.198Z",
    "timestampMillis": 1731401989
  }
}

頻道消息

欄位名稱 描述 類型 必需
packetType 頻道消息 (NOTIFY_CHANNEL_CHAT) 字串 是
body 請求數據 物件 是

主體

欄位名稱 描述 類型 必填 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
from 發送頻道消息的帳戶識別符
玩家ID		 長整數 Y 例如 2222
to 接收頻道消息的頻道ID 字串 Y 例如 "open:10"
message 頻道消息的內容 字串 Y 例如 "你好。這是一個頻道聊天。"
extraData 附加消息信息（基於 UTF-8）
（最多 256 字節）		 字串 Y 例如 "bbbb"
timestamp 發送頻道消息的時間（UTC+0 標準，yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式） 字串 Y 例如 "2024-11-13T05:12:18.385Z"
timestampMillis 發送頻道消息的時間（Unix時間戳毫秒） 長整數 Y 例如 1731401989

範例

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

1:1 訊息

欄位名稱 描述 類型 必填
packetType 1:1 訊息 (NOTIFY_DIRECT_CHAT) 字串 是
body 請求數據 物件 是

主體

字段名稱 描述 類型 必需 範例
gameIndex Hive 遊戲索引 整數 Y 例如 1
from 接收 1:1 訊息的帳戶識別碼
玩家 ID		 長整數 Y 例如 1234
to 發送 1:1 訊息的帳戶識別碼
玩家 ID		 長整數 Y 例如 2222
message 1:1 訊息的內容 字串 Y 例如 "你好。這是一個 1:1 聊天。"
extraData 附加訊息資訊 (基於 UTF-8)
(最多 256 字元)		 字串 Y 例如 "abcd"
timestamp 發送 1:1 訊息的時間 (UTC+0 標準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 格式) 字串 Y 例如 "2024-11-13T05:12:50.060Z"
timestampMillis 發送 1:1 訊息的時間 (UnixTimestamp 毫秒) 長整數 Y 例如 1731401989

範例

{
  "packetType": "NOTIFY_DIRECT_CHAT",
  "body": {
    "gameIndex": 1,
    "from": 1234,
    "to": 2222,
    "message": "Hello. This is a 1:1 chat.",
    "extraData": "abcd",
    "timestamp": "2024-11-13T05:12:50.060Z",
    "timestampMillis": 1731401989
  }
}