コンテンツにスキップ

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_NOTICE ユーザー通知メッセージ
NOTIFY_CHANNEL_CHAT チャネルチャットメッセージ
NOTIFY_DIRECT_CHAT 1:1チャットメッセージ

ソケット接続プロセス

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

  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
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 接続成功時に返される値 string Y 例: "005056fffea3fd10-000400fd-00000797-f67881178d98d1cd-64ae9a76"

リクエストサンプル

{
    "packetType": "CONNECT",
    "body":{
        "gameIndex":1,
        "playerId": 1234,
        "langCode": "en",
        "loginKey": "eyJhbGciOiJIUzI1NiJ9.eyJnYW1lSW5kZXgiOjEsInBsYXllcklkIjoxMjM0LCJpYXQiOjE3MzAzNjY4MjksImV4cCI6MTczMDM3MDQyOX0.fpg6kqwqp1QN3KuYcjVBr8j0mzjN2doefJ_D6xFxcFY" // API 서버에서 생성한 JWT
    }
}

レスポンスサンプル

{
    "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
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
レスポンスボディ > ボディ
フィールド名 説明 タイプ 必須 例
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 generated from 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 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 例: "こんにちは世界!"
extraData メッセージの追加情報 (UTF-8 ベース)
(最大256バイト)		 文字列 Y 例: "bbbb"
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!",
        "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 メッセージ送信者アカウント識別子
Hive プレイヤーID		 長整数 Y 例: 1234
to 1:1 メッセージ受信者アカウント識別子
Hive プレイヤー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"
}

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

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

このメッセージはパケットタイプ NOTIFY で始まります。

チャンネルエントリーメッセージ

フィールド名 説明 タイプ 必須
packetType チャンネルエントリーメッセージ (NOTIFY_ENTER_CHANNEL) 文字列 Y
body リクエストデータ オブジェクト Y

本文

フィールド名 説明 タイプ 必須 例
gameIndex Hive ゲームインデックス 整数 Y 例: 1
channelId 入力されたチャンネルID 文字列 Y 例: "open:10"
playerId チャンネルに入ったアカウントの識別子
Hive プレイヤーID		 長整数 Y 例: 1234
timestamp チャンネルへの入場日時 (基準 UTC+0, フォーマット yyyy-MM-dd'T'HH:mm:ss.SSSZ) 文字列 Y 例: "2024-11-12T08:59:59.497Z"
timestampMillis チャンネルへの入場日時 (Unix タイムスタンプミリ秒) 長整数 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 チャネルから終了したアカウントの識別子
Hive プレイヤー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

サンプル

// 특정 채널에 공지
{
  "packetType": "NOTIFY_CHANNEL_NOTICE",
  "body": {
    "gameIndex": 1,
    "channelId": "open:10",
    "from": "SYSTEM",
    "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 message for a specific user
{
  "packetType": "NOTIFY_NOTICE",
  "body": {
    "gameIndex": 1,
    "playerId": 123123,
    "from": "SYSTEM",
    "message": "공지 메시지 입니다.",
    "timestamp": "2024-11-13T05:06:29.198Z",
    "timestampMillis": 1731401989
  }
}

チャンネルメッセージ

フィールド名 説明 タイプ 必須
packetType チャンネルメッセージ (NOTIFY_CHANNEL_CHAT) 文字列 Y
body リクエストデータ オブジェクト Y

本文

フィールド名 説明 タイプ 必須 例
gameIndex Hive ゲームインデックス 整数 Y 例: 1
from チャンネルメッセージを送信したアカウントの識別子
Hive プレイヤー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 メッセージ送信者アカウント識別子
Hive プレイヤーID		 長整数 Y 例: 1234
to 1:1 メッセージ受信者アカウント識別子
Hive プレイヤー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": "안녕하세요. 1:1 채팅입니다.",
    "extraData": "abcd",
    "timestamp": "2024-11-13T05:12:50.060Z",
    "timestampMillis": 1731401989
  }
}