コンテンツにスキップ

ゲーム通知

このガイドでは、ゲームお知らせ照会 API の使用方法を説明します。

API を呼び出す前に、Hive コンソールでゲームに表示するお知らせを登録する必要があります。

概要

ゲームお知らせ照会 API は、ゲームからサーバー間通信で直接呼び出し、照会方法に応じて以下の 2 種類のインターフェースをサポートします。

  • 全お知らせ照会: 特定のゲーム（game_index）に該当するすべてのお知らせ一覧を一括照会します。
  • ページ単位お知らせ照会: 特定のゲーム（game_index）に該当するお知らせ一覧をページ単位（Pagination）で分割して照会します。

API 呼び出し時、リクエストヘッダーの Authorization に認証トークン（Hive 認証キー）を必ず含める必要があります。レスポンスには お知らせ基本情報、言語別詳細情報、ゲームサーバー ID 一覧、国コード一覧 が含まれます。

レスポンスにお知らせが返されるのは、以下の条件をすべて満たす場合のみです。

  • status = 1: アクティブ状態
  • start_time <= 現在時刻: 現在時刻が表示開始時刻以降
  • end_time >= 現在時刻: 現在時刻が表示終了時刻以前
Note

すべての時刻は KST (UTC+9) 基準です。

共通レスポンス仕様

ゲームお知らせ照会 API の呼び出し時に共通で適用されるレスポンス例およびレスポンスコードを説明します。

成功レスポンス例

{
  "result_code": 0,
  "result_msg": "Success",
  "data": { ... }
}

エラーレスポンス例

{
  "result_code": 1100,
  "result_msg": "Unknown error"
}

レスポンスコード

HTTP ステータスコード コード メッセージ 説明
200 0 Success 正常処理
500 1100 Unknown error 原因不明エラー
500 1101 Internal server error サーバー内部エラー
400 1201 詳細メッセージ
(例: Missing required parameter: game_index)		 リクエスト形式エラー
400 1202 詳細メッセージ
(例: `game_index` must be a positive integer)		 パラメータ値エラー
401 1203 Unauthorized 権限エラー
405 1204 Method not allowed HTTP リクエストメソッドエラー


全お知らせ照会

特定のゲーム（game_index）に該当するお知らせの全件一覧を返します。

リクエスト情報

項目 内容
商用 URL https://social-api.qpyou.cn/games/{game_index}/notices
サンドボックス URL https://sandbox-social-api.qpyou.cn/games/{game_index}/notices
HTTP Method GET
Response Format JSON

リクエストデータ

リクエストヘッダー

フィールド タイプ 必須 説明 備考
Authorization string Y Bearer トークン
(Hive 認証キー)		 AppCenter > プロジェクト管理 > ゲーム詳細 > 基本情報 > Hive 認証キー

リクエストヘッダー例

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

パスパラメータ

フィールド タイプ 必須 説明
game_index int Y ゲームインデックス（正の整数）

リクエストボディ

なし（GET リクエスト）

リクエスト例

curl -X GET "https://sandbox-social-api.qpyou.cn/games/313/notices" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"

レスポンスデータ

レスポンスボディ

フィールド タイプ 説明
result_code int レスポンス結果コード
result_msg string 結果メッセージ
data object レスポンスデータ
ㄴ list array お知らせ一覧（お知らせ基本情報 オブジェクトの配列、結果がない場合は []）

レスポンス例

{
  "result_code": 0,
  "result_msg": "Success",
  "data": {
    "list": [
      {
        "notice_id": 123,
        "status": 1,
        "type": "N",
        "view_count": 500,
        "registrant": "admin",
        "top_placed": 1,
        "start_time": "2026-03-01 00:00:00",
        "end_time": "2026-03-31 23:59:59",
        "company_index": 1,
        "game_index": 313,
        "country_expose_type": "W",
        "details": {
          "ko": {
            "game_name": "테스트게임",
            "title": "공지사항 제목",
            "content": "공지사항 내용",
            "crop_image": "https://example.com/img/123_kor.png"
          },
          "en": {
            "game_name": "TestGame",
            "title": "Notice Title",
            "content": "Notice Content",
            "crop_image": "https://example.com/img/123_eng.png"
          }
        },
        "game_servers": ["server1", "server2"],
        "country_codes": ["KR", "US"]
      }
    ]
  }
}

ページ単位お知らせ照会

特定のゲーム（game_index）に該当するお知らせ一覧をページングして返します。

全お知らせ照会 にクエリパラメータとして page または per_page のいずれかが含まれている場合、ページ単位お知らせ照会モードで動作します。

リクエスト情報

項目 内容
商用 URL https://social-api.qpyou.cn/games/{game_index}/notices?page={page}&per_page={per_page}
サンドボックス URL https://sandbox-social-api.qpyou.cn/games/{game_index}/notices?page={page}&per_page={per_page}
HTTP Method GET
Response Format JSON

リクエストデータ

リクエストヘッダー

フィールド タイプ 必須 説明 備考
Authorization string Y Bearer トークン
(Hive 認証キー)		 AppCenter > プロジェクト管理 > ゲーム詳細 > 基本情報 > Hive 認証キー

リクエストヘッダー例

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

パスパラメータ

フィールド タイプ 必須 説明
game_index int Y ゲームインデックス（正の整数）

クエリパラメータ

Note

page または per_page の値が正の整数でない場合はデフォルト値で代替されます。

パラメータ タイプ 必須 デフォルト値 説明
page int N 1 ページ番号（1から開始）
per_page int N 20 ページあたりの件数

リクエストボディ

なし（GET リクエスト）

リクエスト例

curl -X GET "https://sandbox-social-api.qpyou.cn/games/313/notices?page=1&per_page=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30"

レスポンスデータ

レスポンスボディ

フィールド タイプ 説明
result_code int レスポンス結果コード
result_msg string 結果メッセージ
data object レスポンスデータ
ㄴ pagination object ページングメタ情報
  ㄴ page int 現在のページ番号
  ㄴ per_page int ページあたりの件数
  ㄴ total_count int 全データ件数
  ㄴ total_pages int 全ページ数（ceil(total_count / per_page)、total_count = 0 の場合は 0）
ㄴ list array お知らせ一覧（お知らせ基本情報 オブジェクトの配列、結果がない場合は []）

レスポンス例

{
  "result_code": 0,
  "result_msg": "Success",
  "data": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_count": 50,
      "total_pages": 3
    },
    "list": [
      {
        "notice_id": 123,
        "status": 1,
        "type": "N",
        "view_count": 500,
        "registrant": "admin",
        "top_placed": 1,
        "start_time": "2026-03-01 00:00:00",
        "end_time": "2026-03-31 23:59:59",
        "company_index": 1,
        "game_index": 313,
        "country_expose_type": "W",
        "details": {
          "ko": {
            "game_name": "테스트게임",
            "title": "공지사항 제목",
            "content": "공지사항 내용",
            "crop_image": "https://example.com/img/123_kor.png"
          },
          "en": {
            "game_name": "TestGame",
            "title": "Notice Title",
            "content": "Notice Content",
            "crop_image": "https://example.com/img/123_eng.png"
          }
        },
        "game_servers": ["server1", "server2"],
        "country_codes": ["KR", "US"]
      }
    ]
  }
}

レスポンスデータ詳細

お知らせ基本情報

フィールド タイプ 説明
notice_id int お知らせ固有 ID
status int ステータス（1: アクティブ、常にアクティブ状態のお知らせのみ返却）
type string お知らせ種別（type コード 参照）
view_count int 閲覧数
registrant string 登録者
top_placed int|null 上部固定（1 以上: 固定、null: 非固定）
start_time string 表示開始時刻（yyyy-MM-dd HH:mm:ss、KST）
end_time string 表示終了時刻（yyyy-MM-dd HH:mm:ss、KST）
company_index int 会社インデックス
game_index int ゲームインデックス
country_expose_type string|null 国別露出タイプ（country_expose_type コード 参照、デフォルト値: null）
details object 言語別詳細情報（details 参照）
game_servers array ゲームサーバー ID 一覧（game_servers 参照）
country_codes array 国コード一覧（country_codes 参照）

type コード

コード 説明
I インフォ
C メンテナンス
U アップデート
N お知らせ
A アナウンス
E イベント
D エラー

country_expose_type コード

コード 説明
null 制限なし（すべての国に表示）
W ホワイトリスト（country_codes に含まれる国にのみ表示）
B ブラックリスト（country_codes に含まれる国には非表示）

details

details は言語コードをキーとするオブジェクトです。お知らせに登録されている言語のみ含まれます。詳細情報がない場合は空オブジェクト（{}）を返します。

フィールド タイプ 説明
game_name string ゲーム名
title string お知らせタイトル
content string お知らせ内容
crop_image string クロップ画像 URL

対応言語コード

コード 言語
ko 韓国語
en 英語
ja 日本語
zh-hans 中国語（簡体字）
zh-hant 中国語（繁体字）
de ドイツ語
fr フランス語
ru ロシア語
es スペイン語
pt ポルトガル語
id インドネシア語
th タイ語
vi ベトナム語
it イタリア語
tr トルコ語
ar アラビア語

game_servers

  • ゲームサーバー ID の一覧です。データがない場合は空配列（[]）を返します。
  • 例: ["server1", "server2", "server3"]

country_codes

  • 国コードの一覧です。データがない場合は空配列（[]）を返します。
  • 例: ["KR", "US", "JP"]
  • 参考: ISO 3166 規格