コンテンツにスキップ

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チャットメッセージ

ソケット接続プロセス

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

  2. アプリクライアントはSocketサーバーへの接続を要求します

    • WebSocket通信
    • ステップ1で発行されたトークンを使用します
    • 接続が成功すると、Socketサーバーは以下の情報を返します
    {
        "packetType":"RESPONSE_CONNECT",
        "status": 200,
        "message": "OK",
        "body":{
            "sessionId":"005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"
        }
    }
    

ソケットの切断

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
}


以下はサーバーメッセージパケットのフォーマットです。

{
        "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 アカウント識別子
プレイヤー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":"PING"   
}

レスポンスサンプル

{
    "packetType": "PONG"   
}

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

リクエストパラメータ

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

レスポンスサンプル

{
    "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 メッセージを送信するアカウント識別子
プレイヤー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": "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 チャンネルに入ったアカウント識別子
プレイヤー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

サンプル

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