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をリクエストします
-
ゲームクライアントからソケットサーバーへの接続要求
- WebSocket通信
- ステップ1で発行されたトークンを使用
- 接続が成功すると、ソケットサーバーは以下の情報を返します
ソケット切断¶
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 ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
リクエストパラメータ > 本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
gameIndex | Hive ゲームインデックス | 整数 | Y | 例: 1 |
playerId | アカウント識別子 Hive プレイヤーID | 長整数 | Y | 例: 1234 |
loginKey | アクセスに使用されるトークン Chat Http API から発行 | 文字列 | Y | "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" |
extraData | ユーザーの追加情報 (UTF-8 ベース)(最大 256 バイト) | 文字列 | 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": "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 ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
リクエストパラメータ > 本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
gameIndex | Hive ゲームインデックス | 整数 | Y | 例: 1 |
playerId | アカウント識別子 Hive プレイヤーID | 長整数 | Y | 例: 1234 |
loginKey | アクセスに使用されるトークン Chat Http API 発行 | 文字列 | Y | "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" |
extraData | ユーザーの追加情報 (UTF-8 ベース)(最大 256 バイト) | 文字列 | N | 例: "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}" |
レスポンスボディ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
packetType | 再接続要求への応答 (RESPONSE_RECONNECT ) | 文字列 | Y |
status | ステータスコード | 整数 | Y |
message | ステータスメッセージ | 文字列 | Y |
body | 返されたデータ | オブジェクト | Y |
レスポンスボディ > ボディ¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
sessionId | 接続成功時に返される値 | string | Y | 例: "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76" |
channelIds | 以前参加したチャンネルの中で成功裏に入ったチャンネルのリスト | array | Y | 例: ["ch:1", "ch:2"] |
failChannelIds | 以前参加したチャンネルの中で入れなかったチャンネルのリスト | array | Y | 例: [] |
リクエストサンプル¶
{
"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
}
}
ピン / ポン¶
- リクエストは、ソケットサーバーとCONNECTが完了したときのみ有効です。
- PONGレスポンスがない場合は再ログインが必要です
リクエストパラメータ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
packetType | PINGリクエストコマンド(PING ) | string | Y |
レスポンスボディ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
packetType | PONGレスポンスコマンド(PONG ) | 文字列 | Y |
リクエストサンプル¶
応答サンプル¶
チャンネルメッセージ送信¶
リクエストパラメータ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
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 | 例: "こんにちは世界!" |
langCode | Hive 言語コード (ISO 639 alpha-2に基づく、ISO 639 alpha-2で区別されない言語はスクリプトタグで区別する必要があります) | 文字列 | Y | 例: "ja" |
レスポンスボディ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
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"
}
}
レスポンスサンプル¶
1:1 メッセージ送信¶
リクエストパラメータ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
packetType | 1:1 メッセージ送信コマンド (DIRECT_CHAT ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
リクエストパラメータ > 本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
gameIndex | Hive ゲームインデックス | 整数 | Y | 例: 1 |
from | 1:1 メッセージ送信者アカウント識別子 Hive プレイヤーID | 長整数 | Y | 例: 1234 |
to | 1:1 メッセージ受信者アカウント識別子 Hive プレイヤーID | 長整数 | Y | 例: 2222 |
message | 1:1で送信されるメッセージ (最大200文字) | 文字列 | Y | 例: "こんにちは世界!" |
langCode | Hive 言語コード (ISO 639 alpha-2に基づく。ISO 639 alpha-2で区別されない言語はスクリプトタグで区切る必要があります) | 文字列 | Y | 例: "ja" |
応答本文¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
packetType | 1:1メッセージ送信への応答 (RESPONSE_DIRECT_CHAT ) | 文字列 | Y |
status | ステータスコード | 整数 | Y |
message | ステータスメッセージ | 文字列 | Y |
レスポンスボディ > body¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
status | レスポンスステータスコード | 整数 | Y | 例: 200 |
リクエストサンプル¶
{
"packetType": "DIRECT_CHAT",
"body": {
"gameIndex": 1,
"from": 2222,
"to": 1234,
"message": "안녕하세요",
"langCode": "ko"
}
}
応答サンプル¶
ソケットサーバーイベントメッセージ¶
これは、イベントが発生したときにサーバーからクライアントに送信されるメッセージについて説明しています。
このメッセージは、packetTypeがNOTIFY
で始まります。
チャンネルエントリーメッセージ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
packetType | チャンネルエントリーメッセージ (NOTIFY_ENTER_CHANNEL ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
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 ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
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 ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
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 ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
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 ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
本文¶
フィールド名 | 説明 | 型 | 必須 | 例 |
---|---|---|---|---|
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" |