コンテンツにスキップ

WebSocket API

概要

WebSocket APIはSocketサーバーとWebSocket通信を行い、チャットサービスを提供します。 ゲームクライアントの接続、チャネルメッセージの送信などをサポートしています。

WebSocket APIの主な機能は以下の通りです。

  • クライアント接続 / 切断
  • PING / PONG
  • チャットメッセージの送信 / 受信
    • チャンネルチャット
    • 1:1 チャット
  • ブロックしたユーザーのフィルタリング
    • ブロックしたユーザーにメッセージを送信しない
    • ブロックしたユーザーからメッセージを受信しない
  • チャンネルの入退室通知

基本情報

WebSocket APIを使用する際に、共通して知っておくべき基本情報を案内します。

主要用語

  • チャンネル: チャットルーム
  • チャンネルメッセージ: 参加したチャンネルのすべてのユーザーに送信されるチャットメッセージ
  • 1:1メッセージ: 特定のユーザーにのみ送信されるチャットメッセージ

パケットタイプ

ソケットサーバーと送受信するパケットタイプは以下の通りです。

パケット名 説明
CONNECT ソケットサーバー接続
RESPONSE_CONNECT CONNECTリクエストに対する応答
DISCONNECT ソケットサーバー接続解除
RESPONSE_DISCONNECT DISCONNECTリクエストに対する応答
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"
    }
}

ソケット通信構造

  • 'RESPONSE_'で始まるパケットタイプのJSON形式 

    {
        "packetType":"パケットタイプ",
        "status":"ステータスコード",
        "message":"ステータスメッセージ",
        "body": JSONオブジェクト
}

  • その他のパケット形式

    {
        "packetType":"パケットタイプ",
        "body":{
                //packetType に応じた JSON データ
        }
}

サーバー側でWebSocket接続が切断される場合は、以下の通りです。

  • クライアント側で1分間何のリクエストもない場合
  • JSON形式でない場合
  • status値が401、403の時
    • 401 unauthorized
    • 403 forbidden

応答コード

応答ステータスコードです。

ステータスコード ステータスメッセージ 説明
200 成功 成功
400 不正なリクエスト 不正なリクエスト
401 認証エラー 権限なし
403 禁止 サーバーで拒否されました
408 リクエストタイムアウト クライアントから60秒間リクエストがなかったため、サーバーが接続を解除しました
409 競合 ユーザーのリクエストがサーバーの状態と競合しています (例: 1:1チャット相手がオフラインの場合)
500 内部サーバーエラー 内部サーバーエラー

WebSocket API 機能

チャットサービスに利用されるWebSocket APIの機能別APIリクエストおよび応答、例のコードを説明します。

クライアント接続

リクエストパラメータ

フィールド名 説明 タイプ 必須かどうか
packetType クライアント接続コマンド (CONNECT) string Y
body リクエストデータ object Y
リクエストパラメータ > 本文
フィールド名 説明 タイプ 必須 여부 例
gameIndex Hive ゲーム インデックス integer Y e.g. 1
playerId アカウント識別子
Hive プレイヤー ID		 long Y e.g. 1234
loginKey 接続時に使用するトークン
チャット Http APIで発行		 string Y "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY"
extraData ユーザー追加情報 (UTF-8 基準)
(最大 256 Byte)		 string N e.g. "{\"nickname\":\"Test1234\",\"guildname\":\"together\"}"

レスポンスボディ

フィールド名 説明 タイプ 必須 여부
packetType 接続要求に対する応答 (RESPONSE_CONNECT) string Y
status ステータスコード integer Y
message ステータスメッセージ string Y
body 返却データ object Y
レスポンスボディ > ボディ
フィールド名 説明 タイプ 必須かどうか 例
sessionId 接続成功時に返される値 string Y 例: "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"

リクエストサンプル

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "loginKey": JWT generated by API server,
                "extraData": Additional information
    }
}

レスポンスサンプル

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

クライアント接続解除

リクエストパラメータ

フィールド名 説明 タイプ 必須かどうか
packetType クライアント接続解除コマンド (DISCONNECT) string Y
body リクエストデータ object Y
リクエストパラメータ > 本文
フィールド名 説明 タイプ 必須かどうか 例
sessionId 接続成功時に返される sessionId string N e.g. "6c2408fffe8c91a8-00002f24-00000032-093b757cdc668383-54b4fbc1"
  • sessionId を指定しない場合、websocket に割り当てられた sessionId に対する切断処理
  • sessionId を指定する場合、該当値に対する切断処理

レスポンスボディ

フィールド名 説明 タイプ 必須 여부
packetType 接続解除リクエストに対する応答 (RESPONSE_DISCONNECT) string Y
status ステータスコード integer Y
message ステータスメッセージ string Y

リクエストサンプル

  • sessionIdを指定していない場合 

    {
        "packetType":"DISCONNET"
}

  • sessionIdを指定する場合 

    {
        "packetType":"DISCONNECT",
        "body":{
                "sessionId":"6c2408fffe8c91a8-00002f24-00000032-093b757cdc668383-54b4fbc1"
        }
}

レスポンスサンプル

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

PING / PONG

  • ソケットサーバーとCONNECTが完了した状態でのみリクエストが有効です
  • PONG応答がない場合は再ログインが必要です

リクエストパラメータ

フィールド名 説明 タイプ 必須かどうか
packetType PING リクエストコマンド (PING) string Y

レスポンスボディ

フィールド名 説明 タイプ 必須 여부
packetType PONG 応答コマンド (PONG) string Y

リクエストサンプル

{
    "packetType":"PING"   
}

レスポンスサンプル

{
    "packetType": "PONG"   
}

チャンネルメッセージ送信

リクエストパラメータ

フィールド名 説明 タイプ 必須かどうか
packetType チャンネルメッセージ送信コマンド (CHANNEL_CHAT) string Y
body リクエストデータ object Y
リクエストパラメータ > 本文
フィールド名 説明 タイプ 必須 例
gameIndex Hiveゲームインデックス integer Y e.g. 1
from チャンネルにメッセージを送信するアカウント識別子
HiveプレイヤーID		 long Y e.g. 1234
to チャンネルメッセージを送信するチャンネルID
チャットHttp APIで生成		 string Y e.g. "open:1"
message チャンネルに送信するメッセージ
(最大200文字)		 string Y e.g. "Hello World!"
langCode Hive言語コード
(ISO 639 alpha-2に基づき、ISO 639 alpha-2で区別されない言語はスクリプトタグを付けて区別)		 string Y e.g. "en"

レスポンスボディ

フィールド名 説明 タイプ 必須かどうか
packetType チャンネルメッセージ送信に対する応答 (RESPONSE_CHANNEL_CHAT) string Y
status ステータスコード integer Y
message ステータスメッセージ string Y

リクエストサンプル

{
    "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) string Y
body リクエストデータ object Y
リクエストパラメータ > 本文
フィールド名 説明 タイプ 必須 여부 例
gameIndex Hive ゲーム インデックス integer Y 例: 1
from 1:1 メッセージを送信するアカウント識別子
Hive プレイヤー ID		 long Y 例: 1234
to 1:1 メッセージを受信するアカウント識別子
Hive プレイヤー ID		 long Y 例: 2222
message 1:1で送信するメッセージ
(最大 200文字)		 string Y 例: "Hello World!"
langCode Hive 言語コード
(ISO 639 alpha-2を基準とし、ISO 639 alpha-2で区別されない言語はScriptタグを付けて区別)		 string Y 例: "en"

レスポンスボディ

フィールド名 説明 タイプ 必須 여부
packetType 1:1 メッセージ送信に対する応答 (RESPONSE_DIRECT_CHAT) string Y
status 状態コード integer Y
message 状態メッセージ string Y
レスポンスボディ > body
フィールド名 説明 タイプ 必須かどうか 例
status 応答ステータスコード integer Y e.g. 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) string Y
body リクエストデータ object Y

本文

フィールド名 説明 タイプ 必須 여부 例
gameIndex Hive ゲーム インデックス integer Y e.g. 1
channelId 入場したチャンネル ID string Y e.g. "open:10"
playerId チャンネルに入場したアカウント識別子
Hive プレイヤー ID		 long Y e.g. 1234
extraData ユーザー追加情報 (UTF-8 基準)
(最大 256 Byte)		 string Y e.g. "abcd"
timestamp チャンネルに入場した日時 (UTC+0 基準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) string Y e.g. "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) string Y
body リクエストデータ object Y

本文

フィールド名 説明 タイプ 必須かどうか 例
gameIndex Hive ゲームインデックス integer Y e.g. 1
channelId 退出したチャンネル ID string Y e.g. "open:10"
playerId チャンネルで退出したアカウント識別子
Hive プレイヤー ID		 long Y e.g. 2222
extraData ユーザー追加情報 (UTF-8 基準)
(最大 256 Byte)		 string Y e.g. "abcd"
timestamp チャンネルで退出した日時 (UTC+0 基準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) string Y e.g. "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) string Y
body リクエストデータ object Y

本文

フィールド名 説明 タイプ 必須かどうか 例
gameIndex Hive ゲームインデックス integer Y e.g. 1
channelId 削除したチャンネル ID string Y e.g. "open:10"
timestamp チャンネルを削除した日時 (UTC+0 基準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) string Y e.g. "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) string Y
body リクエストデータ object Y

本文

フィールド名 説明 タイプ 必須かどうか 例
gameIndex Hive ゲーム インデックス integer Y e.g. 1
channelId お知らせメッセージを受信したチャンネル ID string N e.g. "open:10"
from お知らせメッセージを送信したアカウント識別子 string Y e.g. SYSTEM
message お知らせメッセージの内容 string Y e.g. "お知らせメッセージです。"
timestamp お知らせメッセージを送信した日時 (UTC+0 基準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) string Y e.g. "2024-11-13T05:06:29.198Z"

サンプル

// Announcement to specific channel
{
  "packetType": "NOTIFY_CHANNEL_NOTICE",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "from": "SYSTEM",
    "message": "Announcement message.",
    "timestamp": "2024-11-13T05:06:29.198Z"
  }
}

チャンネルメッセージ

フィールド名 説明 タイプ 必須かどうか
packetType チャンネルメッセージ (NOTIFY_CHANNEL_CHAT) string Y
body リクエストデータ object Y

本文

フィールド名 説明 タイプ 必須かどうか 例
gameIndex Hive ゲームインデックス integer Y e.g. 1
from チャンネルメッセージを送信したアカウント識別子
Hive プレイヤー ID		 long Y e.g. 2222
fromExtra ユーザー追加情報 (UTF-8 基準)
(最大 256 Byte)		 string Y e.g. "bbbb"
to チャンネルメッセージを送信したチャンネル ID string Y e.g. "open:10"
langCode Hive 言語コード
(ISO 639 alpha-2を基準としており、ISO 639 alpha-2で区別されない言語はScriptタグを付けて区別)		 string Y e.g. "ko"
timestamp チャンネルメッセージを送信した日時 (UTC+0 基準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) string Y e.g. "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) string Y
body リクエストデータ object Y

本文

フィールド名 説明 タイプ 必須かどうか 例
gameIndex Hive ゲームインデックス integer Y e.g. 1
from 1:1 メッセージを受け取ったアカウント識別子
Hive プレイヤー ID		 long Y e.g. 1234
fromExtra ユーザー追加情報 (UTF-8 基準)
(最大 256 Byte)		 string Y e.g. "abcd"
to 1:1 メッセージを送信したアカウント識別子
Hive プレイヤー ID		 long Y e.g. 2222
message 1:1 メッセージ内容 string Y e.g. "こんにちは。1:1 チャットです。"
langCode Hive 言語コード
(ISO 639 alpha-2を基準とし、ISO 639 alpha-2で区分されない言語はScriptタグを付けて区分)		 string Y e.g. "ko"
timestamp 1:1 メッセージを送信した日時 (UTC+0 基準, yyyy-MM-dd'T'HH:mm:ss.SSSZ 形式) string Y e.g. "2024-11-13T05:12:50.060Z"

サンプル

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