Websocket api
概要¶
WebSocket APIは、WebSocketを介してソケットサーバーと通信することにより、チャットサービスを提供します。ゲームクライアントの接続、チャンネルメッセージの送信などをサポートしています。
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サーバーは以下の情報を返します
ソケットの切断¶
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
}
以下はサーバーメッセージパケットのフォーマットです。
サーバーは、次のような場合に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 | アカウント識別子 プレイヤー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_CONNECT ) | 文字列 | Y |
status | ステータスコード | 整数 | Y |
message | ステータスメッセージ | 文字列 | Y |
body | 戻りデータ | オブジェクト | Y |
レスポンスボディ > ボディ¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
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で区別されない言語はスクリプトタグで区切られます) | 文字列 | Y | 例: "en" |
loginKey | 接続に使用されるトークン Chat Http APIによって発行される | 文字列 | Y | "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" |
レスポンスボディ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
packetType | 再接続リクエストへの応答 (RESPONSE_RECONNECT ) | 文字列 | Y |
status | ステータスコード | 整数 | Y |
message | ステータスメッセージ | 文字列 | Y |
body | 戻りデータ | オブジェクト | Y |
レスポンスボディ > 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¶
- リクエストは、ソケットサーバーとCONNECTが正常に完了したときのみ有効です
- PONGレスポンスがない場合は、再ログインが必要です
リクエストパラメータ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
packetType | PINGリクエストコマンド(PING ) | 文字列 | Y |
レスポンスボディ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
packetType | PONGレスポンスコマンド(PONG ) | 文字列 | Y |
リクエストサンプル¶
レスポンスサンプル¶
チャンネルメッセージを送信¶
リクエストパラメータ¶
フィールド名 | 説明 | タイプ | 必須 |
---|---|---|---|
packetType | チャンネルメッセージ送信コマンド (CHANNEL_CHAT ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
リクエストパラメータ > 本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
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 ) | 文字列 | Y |
status | ステータスコード | 整数 | Y |
message | ステータスメッセージ | 文字列 | Y |
リクエストサンプル¶
{
"packetType":"CHANNEL_CHAT",
"body": {
"gameIndex": 1,
"from": 1234,
"to": "open:1",
"message": "Hello World!",
"extraData": "bbbb",
"langCode": "en"
}
}
レスポンスサンプル¶
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 | 例: "こんにちは世界!" |
extraData | 追加のメッセージ情報 (基づく UTF-8 )(最大256バイト) | 文字列 | Y | 例: "bbbb" |
langCode | 送信されるメッセージの言語コード Hive 言語コード (ISO 639 alpha-2 に基づき、ISO 639 alpha-2 で区別されない言語はスクリプトタグで分けられます) | 文字列 | Y | 例: "ja" |
レスポンスボディ¶
フィールド名 | 説明 | 型 | 必須 |
---|---|---|---|
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": "안녕하세요",
"extraData": "bbbb",
"langCode": "ko"
}
}
レスポンスサンプル¶
ソケットサーバーイベントメッセージ¶
このセクションでは、イベントが発生したときにサーバーからクライアントに送信されるメッセージについて説明します。
これらのメッセージは、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 | チャンネルからの退出時間 (UnixTimestamp ミリ秒) | 長整数 | 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 ) | 文字列 | 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" |
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 ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
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 ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
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 | 通知メッセージ送信時刻(UnixTimestampミリ秒) | 長整数 | 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 ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
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 | チャンネルメッセージ送信時刻(UnixTimestampミリ秒) | 長整数 | 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 ) | 文字列 | Y |
body | リクエストデータ | オブジェクト | Y |
本文¶
フィールド名 | 説明 | タイプ | 必須 | 例 |
---|---|---|---|---|
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 |