コンテンツにスキップ

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形式が無効な場合、このパケットタイプで応答します

ソケット接続プロセス

  1. ゲームサーバーのチャットHttp APIを通じてトークン発行をリクエストします。※ 発行されたトークンはチャットSocketサーバーへの接続に使用されます

  2. ゲームクライアントからソケットサーバーへの接続要求

    • WebSocket通信
    • ステップ1で発行されたトークンを使用
    • 接続が成功すると、ソケットサーバーは以下の情報を返します
    {
        "packetType":"RESPONSE_CONNECT",
        "status": 200,
        "message": "OK",
        "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) 文字列 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":"PING"   
}

応答サンプル

{
    "packetType": "PONG"   
}

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

リクエストパラメータ

フィールド名 説明 タイプ 必須
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"
    }
}

レスポンスサンプル

{
    "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 メッセージ送信者アカウント識別子
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": "RESPONSE_DIRECT_CHAT",
    "status": 200,
    "message":"OK"
}

ソケットサーバーイベントメッセージ

これは、イベントが発生したときにサーバーからクライアントに送信されるメッセージについて説明しています。

このメッセージは、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"

サンプル

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