コンテンツにスキップ

ゲーム通知

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

事前準備

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

動作方式

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

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

アプリお知らせ照会 API は JWT 認証方式で動作します。

API 呼び出し時、リクエストヘッダーの X-Access-Token に認証トークン（JWT Access Token、OAuth Token 発行参照）を必ず含める必要があります。レスポンスには お知らせ基本情報、言語別詳細情報、アプリサーバー ID 一覧、国コード一覧 が含まれます。

応答値のうち、以下の条件を満たす場合にのみお知らせを照会することができます。

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

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

共通レスポンス仕様

アプリお知らせ照会 API 呼び出し時に返却される成功および失敗レスポンスデータ例とステータスコードを説明します。

成功レスポンス例

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

エラーレスポンス例

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

JWT 検証失敗例

{
  "result_code": 1203,
  "result_msg": "Unauthorized",
  "token_validation": {
    "result_code": 2408,
    "result_msg": "JWT token expired"
  }
}

ステータスコード

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 JWT 検証に失敗しました（詳細はtoken_validation 参照）
405 1204 Method not allowed HTTPリクエストメソッドエラー
Note

JWT 検証に失敗した場合は、token_validationフィールドで詳細なエラー情報を確認できます。詳しくは、JWT 検証エラーコードを参照してください。


全お知らせ照会

特定のアプリ（game_index）に対応するお知らせの完全なリストを返します。

リクエスト情報

区分 情報
商用 URL https://social-api.qpyou.cn/v2/games/{game_index}/notices
サンドボックス URL https://sandbox-social-api.qpyou.cn/v2/games/{game_index}/notices
HTTP Method GET
Response Format JSON

リクエストデータ

「全お知らせ照会」を呼び出すときに送信するデータについて説明します。

リクエストヘッダー

フィールド タイプ 必須 説明 備考
X-Access-Token string Y JWT Access Token 発行方法は OAuth Token 発行 参照

リクエストヘッダー例

X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...

パスパラメータ

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

リクエストボディ

なし（GET リクエスト）

リクエスト例

「全お知らせ照会」呼び出しの例は次のとおりです。

curl -X GET "https://sandbox-social-api.qpyou.cn/v2/games/539/notices" \
  -H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..."

レスポンスデータ

「全お知らせ照会」を呼び出すと応答するデータを説明します。

レスポンスボディ

フィールド タイプ 説明
result_code int レスポンス結果コード
result_msg string 結果メッセージ
token_validation object JWT 検証結果
ㄴ result_code int JWT 検証結果コード（0 = 成功、詳細はJWT 検証エラーコードを参照）
ㄴ result_msg string JWT 検証結果メッセージ
data object レスポンスデータ(JWT 検証失敗時には含まれない)
ㄴ list array お知らせリスト（お知らせ基本情報オブジェクト配列、結果がない場合は[]）

レスポンス例

「全お知らせ照会」を呼び出すときの応答の例を次に示します。

{
  "result_code": 0,
  "result_msg": "Success",
  "token_validation": { 
    "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": 4,
        "game_index": 539,
        "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/v2/games/{game_index}/notices?page={page}&per_page={per_page}
サンドボックス URL https://sandbox-social-api.qpyou.cn/v2/games/{game_index}/notices?page={page}&per_page={per_page}
HTTP Method GET
Response Format JSON

リクエストデータ

「ページ単位のお知らせ照会」呼び出し時に送信するデータについて説明します。

リクエストヘッダー

フィールド タイプ 必須 説明 備考
X-Access-Token string Y JWT Access Token 発行方法は OAuth Token 発行 参照

リクエストヘッダー例

X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0...

パスパラメータ

フィールド タイプ 必須 説明
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/v2/games/539/notices?page=1&per_page=20" \
  -H "X-Access-Token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InByb2plY3RfYWJjMTIzIn0..."

レスポンスデータ

「ページ単位お知らせ照会」を呼び出したときに返信されるデータを説明します。

レスポンスボディ

フィールド タイプ 説明
result_code int レスポンス結果コード
result_msg string 結果メッセージ
token_validation object JWT 検証結果
ㄴ result_code int JWT 検証結果コード（0 = 成功、詳細はJWT 検証エラーコードを参照）
ㄴ result_msg string JWT 検証結果メッセージ
data object レスポンスデータ(JWT 検証失敗時には含まれない)
ㄴ 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",
  "token_validation": {
    "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": 4,
        "game_index": 539,
        "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"]
      }
    ]
  }
}

レスポンスデータ詳細

アプリお知らせ照会 API でサポートする全レスポンスデータの詳細を説明します。

お知らせ基本情報

フィールド タイプ 説明
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 規格