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聊天消息

套接字连接过程¶

通过游戏服务器的聊天 Http API 请求令牌发行。※ 发行的令牌用于连接聊天 Socket 服务器
- 使用 Hive 认证密钥请求用户令牌发行 API

应用客户端请求连接到 Socket 服务器

WebSocket 通信
使用第 1 步中发放的令牌
如果连接成功，Socket 服务器将返回以下信息

{
    "packetType":"响应连接",
    "status": 200,
    "message": "好的",
    "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
langCode	Hive 语言代码 (基于 ISO 639 alpha-2，未通过 ISO 639 alpha-2 区分的语言由脚本标签分隔)	字符串	是	例如 "en"
loginKey	用于访问的令牌由 Chat Http API 发放	字符串	是	"eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"

响应主体¶

字段名称	描述	类型	必需
packetType	对连接请求的响应（`RESPONSE_CONNECT`）	字符串	是
status	状态码	整数	是
message	状态消息	字符串	是
body	返回的数据	对象	是

响应体 > body¶

字段名称	描述	类型	必需	示例
sessionId	成功连接时返回的值	字符串	Y	例如 "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"

请求示例¶

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "langCode": "en",
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" // API 서버에서 생성한 JWT
    }
}

响应示例¶

{
    "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
langCode	Hive 语言代码 (基于 ISO 639 alpha-2，ISO 639 alpha-2 无法区分的语言由脚本标签分隔)	字符串	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 generated from 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 successfully joined from previously participated channels
        "failChannelIds":[]                // List of channels that failed to join from previously participated channels
    }
}

Ping / Pong¶

请求仅在套接字服务器和连接完成时有效。
如果没有 PONG 响应，则需要重新登录。

请求参数¶

字段名称	描述	类型	必需
packetType	PING 请求命令 (`PING`)	字符串	Y

响应主体¶

字段名称	描述	类型	必需
packetType	PONG 响应命令（`PONG`）	字符串	是

请求示例¶

{
    "packetType":"PING"   
}

响应示例¶

{
    "packetType": "PONG"   
}

频道消息发送¶

请求参数¶

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

请求参数 > 正文¶

字段名称	描述	类型	必需	示例
gameIndex	Hive 游戏索引	整数	是	例如 1
from	发送消息到频道的账户标识符 Hive 玩家ID	长整型	是	例如 1234
to	发送消息到频道的频道ID 聊天HTTP API 创建的	字符串	是	例如 "open:1"
message	发送到频道的消息 (最多200个字符)	字符串	是	例如 "Hello World!"
extraData	消息的附加信息 (`UTF-8` 基础) (最多256字节)	字符串	是	例如 "bbbb"
langCode	发送消息的语言代码 Hive 语言代码 (基于ISO 639 alpha-2，未通过ISO 639 alpha-2区分的语言应通过脚本标签分隔)	字符串	是	例如 "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`)	字符串	是
body	请求数据	对象	是

请求参数 > 正文¶

字段名称	描述	类型	必需	示例
gameIndex	Hive 游戏索引	整数	是	例如 1
from	1:1 消息发送者账户标识符 Hive 玩家 ID	长整型	是	例如 1234
to	1:1 消息接收者账户标识符 Hive 玩家 ID	长整型	是	例如 2222
message	要发送的 1:1 消息 (最多 200 个字符)	字符串	是	例如 "Hello World!"
extraData	附加消息信息 (`UTF-8` 基础) (最多 256 字节)	字符串	是	例如 "bbbb"
langCode	发送消息的语言代码 Hive 语言代码 (基于 ISO 639 alpha-2，ISO 639 alpha-2 未区分的语言应使用 Script 标签分隔)	字符串	是	例如 "en"

响应主体¶

字段名称	描述	类型	必需
packetType	对1:1消息传输的响应（`RESPONSE_DIRECT_CHAT`）	字符串	是
status	状态代码	整数	是
message	状态消息	字符串	是

响应体 > body¶

字段名称	描述	类型	必需	示例
status	响应状态码	整数	是	例如 200

请求示例¶

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

响应示例¶

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

套接字服务器事件消息¶

这描述了事件发生时从服务器发送到客户端的消息。

此消息以 packetType NOTIFY 开头。

渠道入口消息¶

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

正文¶

字段名称	描述	类型	必需	示例
gameIndex	Hive 游戏索引	整数	是	例如 1
channelId	输入的频道 ID	字符串	是	例如 "open:10"
playerId	进入频道的账户标识符 Hive 玩家 ID	长整型	是	例如 1234
timestamp	进入频道的日期和时间（基于 `UTC+0`，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	字符串	是	例如 "2024-11-12T08:59:59.497Z"
timestampMillis	进入频道的日期和时间（Unix 时间戳毫秒）	长整型	是	例如 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`)	字符串	是
body	请求数据	对象	是

正文¶

字段名称	描述	类型	必需	示例
gameIndex	Hive 游戏索引	整数	是	例如 1
channelId	退出的频道 ID	字符串	是	例如 "open:10"
playerId	从频道退出的账户标识符 Hive 玩家 ID	长整型	是	例如 2222
timestamp	从频道退出的日期和时间（`UTC+0` 标准，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	字符串	是	例如 "2024-11-12T08:59:59.497Z"
timestampMillis	从频道退出的日期和时间（Unix时间戳毫秒）	长整型	是	例如 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 游戏索引	整数	是	例如 1
channelId	删除的频道ID	字符串	是	例如 "open:10"
timestamp	频道删除的日期和时间（基于 `UTC+0`，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	字符串	是	例如 "2024-11-12T08:59:59.497Z"
timestampMillis	频道删除的日期和时间（Unix时间戳毫秒）	长整型	是	例如 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	发送通知消息的日期和时间（Unix时间戳毫秒）	长整型	Y	例如 1731401989

示例¶

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

用户通知消息¶

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

正文¶

字段名称	描述	类型	必需	示例
gameIndex	Hive 游戏索引	整数	是	例如 1
playerId	收到通知消息的玩家ID	长整型	是	例如 123123
from	发送通知消息的账户标识符	字符串	是	例如 `SYSTEM`
message	通知消息的内容	字符串	是	例如 "这是一条通知消息。"
timestamp	发送通知消息的日期和时间（基于 `UTC+0`，格式为 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	字符串	是	例如 "2024-11-13T05:06:29.198Z"
timestampMillis	发送通知消息的日期和时间（Unix时间戳毫秒）	长整型	是	例如 1731401989

示例¶

// Notice message for a specific user
{
  "packetType": "NOTIFY_NOTICE",
  "body": {
    "gameIndex": 1,
    "playerId": 123123,
    "from": "SYSTEM",
    "message": "공지 메시지 입니다.",
    "timestamp": "2024-11-13T05:06:29.198Z",
    "timestampMillis": 1731401989
  }
}

渠道消息¶

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

主题¶

字段名称	描述	类型	必需	示例
gameIndex	Hive 游戏索引	整数	是	例如 1
from	发送频道消息的账户标识符 Hive 玩家 ID	长整型	是	例如 2222
to	发送频道消息的频道 ID	字符串	是	例如 "open:10"
message	频道消息的内容	字符串	是	例如 "你好。这是一个频道聊天。"
extraData	消息的附加信息（`UTF-8` 编码）（最大 256 字节）	字符串	是	例如 "bbbb"
timestamp	发送频道消息的日期和时间（`UTC+0` 基础，格式 `yyyy-MM-dd'T'HH:mm:ss.SSSZ`）	字符串	是	例如 "2024-11-13T05:12:18.385Z"
timestampMillis	发送频道消息的日期和时间（Unix时间戳毫秒）	长整型	是	例如 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 游戏索引	整数	是	例如 1
from	1:1 消息发送者账户标识符 Hive 玩家 ID	长整型	是	例如 1234
to	1:1 消息接收者账户标识符 Hive 玩家 ID	长整型	是	例如 2222
message	1:1 消息内容	字符串	是	例如 "你好。这是一个 1:1 聊天。"
extraData	附加消息信息（`UTF-8` 编码）（最大 256 字节）	字符串	是	例如 "abcd"
timestamp	1:1 消息发送日期和时间（`UTC+0` 基于，`yyyy-MM-dd'T'HH:mm:ss.SSSZ` 格式）	字符串	是	例如 "2024-11-13T05:12:50.060Z"
timestampMillis	1:1 消息发送日期和时间（Unix时间戳毫秒）	长整型	是	例如 1731401989

示例¶

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