バナーリスト
バナー設定に必要な情報をリスト形式で提供します。Request Body タイプ_banner 値に応じて、3つのAPIレスポンスがあります。
small: 通常のバナー、通知、ロールバナーを設定するために必要な情報を返します。great: インタースティシャルバナーを設定するために必要な情報のみを返します。rolling: ロールバナーを設定するために必要な情報のみを返します。
- リクエスト URL
共通URL https://promotion.qpyou.cn/api/banner サンドボックスURL https://sandbox-promotion.qpyou.cn/api/banner HTTPメソッド POST Content-Type text/html データ形式 JSON
- ヘッダー
フィールド名 説明 タイプ 必須 認証 Bearer認証を通じて有効なCertificationKey 文字列 N
- ヘッダー
フィールド名 説明 タイプ 必須 認証 Bearer認証を通じて有効なCertificationKey 文字列 N
- リクエスト ボディ
フィールド名 説明 タイプ 必須 user ユーザー情報 オブジェクト はい ㄴ uid プラットフォームが管理するユーザーID 文字列 いいえ ㄴ vid 統合モジュールのログインセンターが管理するVID、または認証v4が管理するPlayerID。個別モジュールでは値は空です。 文字列 いいえ ㄴ player_token ユーザー認証情報 文字列 N ㄴ did プロビジョニングが生成する各デバイスのユニークID 文字列 Y ㄴ world ゲームサーバー情報 文字列 Y ㄴ language ゲームまたはデバイスに設定された言語コード（ISO 639-1に基づく） 文字列 Y ㄴ hive_country 要求された国情報 値が存在しない場合、フィールドはリクエストIPに基づいて決定されます。 文字列 N ㄴ age_gate_u13 COPPAに従って13歳未満のユーザーを制限するかどうか ゲームスタジオは、Hive SDKで関連機能を実装した際の戻り値を送信します。 - `true`: 13歳未満のユーザーを制限
- `false`: 制限なし
ブール値 Y game ゲーム情報 オブジェクト Y ㄴ appid バナーを表示しようとするゲームのAppID 文字列 Y ㄴ app_version バナーを表示するかどうかを判断するために必要なゲームのバージョン 文字列 Y promotion プロモーションキャンペーンデータ オブジェクト Y ㄴ type_camp プロモーションキャンペーンの種類（Hive コンソールでキャンペーンを登録する際に選択または直接入力） - all: すべてのタイプ
- event: イベントタイプ
- notice: お知らせタイプ
- cross: クロスキャンペーンタイプ
- Others: ユーザーが定義したお知らせタイプ、最大10文字の小文字アルファベット
文字列 Y ㄴ type_banner キャンペーンバナーの種類 - small: 通常のバナー（ストリップバナー）
- great: インタースティシャルバナー
- rolling: ローリングバナー
文字列 Y
curl -L -v \
-d '{
"user": {
"uid": "107812001",
"vid": "10053342680",
"player_token" : "61738cb65677c2451cb5c41e1a3bbc",
"did": "5115990249",
"world": "100006",
"language": "ko",
"hive_country": "KO",
"age_gate_u13": false
},
"game": {
"appid": "com.com2us.hivesdk.normal.freefull.google.global.android.common",
"app_version": "1.1"
},
"promotion": {
"type_camp": "all",
"type_banner": "small"
}
}' \
-H "Content-Type: application/json" \
https://sandbox-promotion.qpyou.cn/api/banner
- 応答（リクエストボディの
type_banner値がsmallの場合：通常のバナー、通知、ロールバナー）
| フィールド名 | 説明 | タイプ | 必須 |
|---|---|---|---|
| result_code | レスポンスコード + 200: 検証成功 + その他: 失敗 | 整数 | Y |
| result_message | レスポンスメッセージ | 文字列 | Y |
| count | バナーの数 | 整数 | Y |
| banner | バナーのリスト バナー登録がない場合、配列は空([])です。 | 配列 | Y |
| ㄴ pid | プロモーションキャンペーンID | 文字列 | N |
| ㄴ image | キャンペーンバナーの画像URL | 文字列 | N |
| ㄴ link | ユーザーがキャンペーンバナーをクリックしたときに開くURL | 文字列 | N |
| ㄴ start_date | キャンペーンの開始日 | 文字列 | N |
| ㄴ end_date | キャンペーンの終了日 | 文字列 | N |
| ㄴ start_unixtimestamp | キャンペーンの開始時間 (Unixタイムスタンプ) | 整数 | N |
| ㄴ end_unixtimestamp | キャンペーンの終了時間 (Unixタイムスタンプ) | 整数 | N |
| ㄴ type_link | ユーザーがキャンペーンバナーをクリックしたときにページを開くタイプ (キャンペーン登録時に選択) + webview: 内部リンクを開く + webbrowser: 外部リンクを開く + market: マーケット (App Store) ページを開く + notice: お知らせページを開く + text: プロモーションテキストのお知らせを開く + interwork: ゲーム内の指定ページに移動 + none: ページに留まる | 文字列 | N |
| ㄴ interwork_data | ゲーム内の特定ページに移動するためのAPIとパラメータを提供 (対応情報がない場合はNULL) オブジェクト | N | |
| ㄴㄴ api | API URI | 文字列 | N |
| ㄴㄴ param | API URIで使用されるクエリ文字列パラメータの値 | 文字列 | N |
| ㄴ type_banner | キャンペーンバナーのタイプ + small: 通常のバナー + rolling: ローリングバナー | 文字列 | N |
| ㄴ type_camp | プロモーションのキャンペーンタイプ + event: イベントタイプ + notice: お知らせタイプ + permit: 審査バナー + cross: クロスバナー | 文字列 | N |
| ㄴ badge | イベントが間もなく終了することを通知するバッジの情報と、ギフトを受け取れる期間を通知するバッジの情報。通常のバナーのみがこのフィールド値を返します。ローリングバナーは常にNULLを返します。通常のバナーは、Hive コンソールの期間通知バッジ設定にバッジ情報が設定されていない場合もNULLを返します。お知らせタイプにはこのフィールドがありません。 | オブジェクト | N |
| ㄴㄴ title | バッジ内のテキスト | 文字列 | N |
| ㄴㄴ type | 表示されるバッジのタイプ + shutdown: イベントの終了が迫っていることを通知するバッジ + gift: ギフトを受け取れる期間を通知するバッジ。 | 文字列 | N |
| ㄴㄴ start_date | バッジ表示の開始日 (ISO-8601形式) | 文字列 | N |
| ㄴㄴ end_date | バッジ表示の終了日 (ISO-8601形式) | 文字列 | N |
| ㄴㄴ start_unixtimestamp | バッジ表示の開始時間 (Unixタイムスタンプ) | 整数 | N |
| ㄴㄴ end_unixtimestamp | バッジ表示の終了時間 (Unixタイムスタンプ) | 整数 | N |
| notice_count | お知らせの数 | 整数 | Y |
| notice | 投稿されたお知らせの情報 | 配列 | Y |
| ㄴ pid | 投稿されたお知らせのID | 文字列 | N |
| ㄴ notice_type | 投稿されたお知らせのタイプ | 文字列 | N |
| ㄴ title | 投稿されたお知らせのタイトル | 文字列 | N |
| ㄴ link | 投稿されたお知らせのURL | 文字列 | N |
| ㄴ start_date | 投稿の露出開始時間 | 文字列 | N |
| ㄴ end_date | 投稿の露出終了時間 | 文字列 | N |
| ㄴ start_unixtimestamp | 投稿の露出開始時間 (Unixタイムスタンプ) | 文字列 | N |
| ㄴ end_unixtimestamp | 投稿の露出終了時間 (Unixタイムスタンプ) | 文字列 | N |
| ㄴ view_count | 投稿のビュー数 | 文字列 | N |
| ㄴ game_index | 投稿からのゲームのインデックス情報 | 文字列 | N |
| ㄴ language | 投稿に設定された言語コード (ISO 639-1に基づく) | 文字列 | N |
| rolling_count | ローリングバナーの数 | 整数 | Y |
| rolling | ローリングバナーの情報 | 配列 | Y |
| ㄴ pid | プロモーションキャンペーンID | 文字列 | N |
| ㄴ image | キャンペーンバナーの画像URL | 文字列 | N |
| ㄴ link | バナーをクリックしたときに移動するURL | 文字列 | N |
| ㄴ start_date | キャンペーンの開始日 | 文字列 | N |
| ㄴ end_date | キャンペーンの終了日 | 文字列 | N |
| ㄴ start_unixtimestamp | キャンペーンの開始時間 (Unix タイムスタンプ) | 文字列 | N |
| ㄴ end_unixtimestamp | キャンペーンの終了時間 (Unix タイムスタンプ) | 文字列 | N |
| ㄴ type_link | ユーザーがキャンペーンバナーをクリックしたときにページを開くタイプ (キャンペーン登録時に選択) + webview: 内部リンクを開く + webbrowser: 外部リンクを開く + market: マーケット (App Store) ページを開く + notice: お知らせページを開く + text: プロモーションテキストのお知らせを開く + interwork: ゲーム内の指定ページに移動 + none: ページに留まる | 文字列 | N |
| ㄴ type_banner | キャンペーンバナータイプ + small: 通常のバナー + rolling: ローリングバナー | 文字列 | N |
| ㄴ type_camp | プロモーションのキャンペーンタイプ + event: イベントタイプ + notice: お知らせタイプ + permit: 審査バナー + cross: クロスバナー | 文字列 | N |
| ㄴ interwork_data | ゲーム内の特定ページに移動するためのAPIとパラメータを提供 (情報がない場合はNULL) | オブジェクト | N |
| ㄴㄴ api | API URI | 文字列 | N |
| ㄴㄴ param | API URIで使用されるクエリ文字列パラメータの値 | 文字列 | N |
- 結果 コード
| コード | メッセージ | 説明 |
| 200 | 成功 | データの送信が成功しました |
- レスポンス 例 (通常バナー、通知、ロールバナー)
< HTTP/1.1 200 OK < Server: nginx < Date: Tue, 15 Mar 2022 03:22:54 GMT < Content-Type: text/html; charset=UTF-8 { "banner": [ { "pid": "202456", "image": "http://hive-fn.qpyou.cn/hivepromotion/banner/2008/6227_1598855945930_crosscopy.jpg", "link": "http://test-promotion.qpyou.cn/news/direct/202456", "start_date": "2020-08-31 15:32:00", "end_date": "2023-08-10 18:30:00", "start_unixtimestamp": 1598855520, "end_unixtimestamp": 1691659800, "type_link": "market", "type_banner": "small", "type_camp": "cross", "interwork_data": null, "badge": { "title": "ギフト収集期間", "type": "gift", "start_date": "2023-03-23T16:30:00+09:00", "end_date": "2023-10-28T16:25:00+09:00", "start_unixtimestamp": 1679556600, "end_unixtimestamp": 1698477900 } { "pid": "203408", "image": "http://hive-fn.qpyou.cn/hivepromotion/banner/2302/3064_1675413872939_5017_1649923083718_0418_one_640_ko.jpg", "link": "", "start_date": "2023-02-03 16:30:00", "end_date": "2023-02-06 17:43:00", "start_unixtimestamp": 1675409400, "end_unixtimestamp": 1675672980, "type_link": "none", "type_banner": "small", "type_camp": "cross", "interwork_data": null, "badge" : null }, { "pid": "203392", "image": "http://hive-fn.qpyou.cn/hivepromotion/banner/2301/5210_1675144150263_landscape.png", "link": "http://test-promotion.qpyou.cn/news/direct/203392", "start_date": "2023-01-31 14:48:00", "end_date": "2023-02-28 14:48:00", "start_unixtimestamp": 1675144080, "end_unixtimestamp": 1677563280, "type_link": "interwork", "type_banner": "small", "type_camp": "event", "interwork_data": { "api": "/language", "param": "param=japanese" }, "badge" : null } ], "count": 3, "notice": [ { "nid": "96274", "notice_type": "notice", "title": "all23", "link": "http://test-promotion.qpyou.cn/news/notice/96274", "start_date": "2022-07-14 09:55:00", "end_date": "9999-12-31 00:00:00", "start_unixtimstamp": 1657760100, "end_unixtimstamp": 253402182000, "view_count": "0", "game_index": "2790", "language": "ko" }, { "nid": "70268", "notice_type": "event", "title": "test", "link": "http://test-promotion.qpyou.cn/news/notice/70268", "start_date": "2020-10-01 11:12:00", "end_date": "9999-12-31 00:00:00", "start_unixtimstamp": 1601518320, "end_unixtimstamp": 253402182000, "view_count": "0", "game_index": "2790", "language": "ko" } ], "notice_count": 2, "rolling": [ { "pid": "202855", "image": "http://hive-fn.qpyou.cn/hivepromotion/banner/2212/9529_1672308134293_2206_1620884709352_1206_1609131801104_pngitem_1172768.png", "link": "http://test-promotion.qpyou.cn/news/direct/202855", "start_date": "2021-05-13 14:44:00", "end_date": "2023-05-19 14:44:00", "start_unixtimestamp": 1620884640, "end_unixtimestamp": 1684475040, "type_link": "webview", "type_banner": "small", "type_camp": "notice", "interwork_data": null , "badge" : null } ], "rolling_count": 1, "result_code": 200, "result_message": "成功." }
- レスポンス (the
type_bannervalue in the リクエスト ボディ isgreatorrolling: interstitial banner or rolling banner)フィールド名 説明 タイプ 必須 result_code レスポンスコード - 200: 検証成功
- その他: 失敗
文字列 はい result_message レスポンスメッセージ 文字列 はい count バナーの数 整数 はい banner バナーのリスト バナー登録がない場合、配列は空([])です。 配列 はい ㄴ pid プロモーションキャンペーンID 文字列 いいえ ㄴ image キャンペーンバナーの画像URL 文字列 いいえ ㄴ link ユーザーがキャンペーンバナーをクリックしたときに開くURL 文字列 いいえ ㄴ start_date キャンペーンの開始日 文字列 いいえ ㄴ end_date キャンペーンの終了日 文字列 いいえ ㄴ start_unixtimestamp キャンペーンの開始時間 (Unixタイムスタンプ) 整数 いいえ ㄴ end_unixtimestamp キャンペーンの終了時間 (Unixタイムスタンプ) 整数 いいえ ㄴ type_link ユーザーがキャンペーンバナーをクリックしたときにページを開くタイプ (キャンペーン登録時に選択) - webview: 内部リンクを開く
- webbrowser: 外部リンクを開く
- market: マーケット (App Store) ページを開く
- notice: お知らせページを開く
- text: プロモーションテキストのお知らせを開く
- interwork: ゲーム内の指定ページに移動する
- none: ページに留まる
文字列 いいえ ㄴ interwork_data ゲーム内の特定ページに移動するためのAPIとパラメータを提供 (情報がない場合はNULL) オブジェクト いいえ ㄴㄴ api API URI 文字列 N ㄴㄴ param API URIで使用されるクエリ文字列パラメータの値 文字列 N ㄴ type_banner キャンペーンバナータイプ - great: インタースティシャルバナー
- small: 通常バナー（ストリップバナー）
- rolling: ローリングバナー
文字列 N ㄴ type_camp プロモーションキャンペーンタイプ（Hive コンソールでキャンペーンを登録する際に選択または直接入力） - event: イベントタイプ
- notice: お知らせタイプ
- permit: 審査バナー
- cross: クロスバナー
文字列 N ㄴ バッジ イベントを通知するバッジの情報はまもなく終了し、ギフトを受け取ることができる期間を通知するバッジです。ロールバナーとインタースティシャルバナーは常に NULLを返します。オブジェクト N ㄴㄴ タイトル バッジ内のテキスト 文字列 N ㄴㄴ タイプ バッジの種類を表示 - shutdown: イベントの終了が迫っていることを通知するバッジ
- gift: ギフトを受け取ることができる期間を通知するバッジ。
文字列 N ㄴㄴ start_date バッジ表示の開始日（ISO-8601形式） 文字列 N ㄴㄴ end_date バッジ表示の終了日（ISO-8601形式） 文字列 N ㄴㄴ start_unixtimestamp バッジ表示の開始時間（Unixタイムスタンプ） 整数 N ㄴㄴ end_unixtimestamp バッジ表示の終了時間（Unixタイムスタンプ） 整数 N
- Result コード
| コード | メッセージ | 説明 |
| 200 | 成功 | データ送信に成功しました |
- 応答 例 (インタースティシャルバナーまたはロールバナー)
< HTTP/1.1 200 OK < Server: nginx < Date: Tue, 15 Mar 2022 03:22:54 GMT < Content-Type: text/html; charset=UTF-8 { "banner": [ { "pid": "203327", "image": "http://hive-fn.qpyou.cn/hivepromotion/banner/2212/2242_1671774095448_9554_1659585211300_pet3.png", "link": "http://test-promotion.qpyou.cn/news/direct/203327", "start_date": "2022-12-23 14:39:00", "end_date": "2024-01-28 14:39:00", "start_unixtimestamp": 1671773940, "end_unixtimestamp": 1706420340, "type_link": "market", "type_banner": "great", "type_camp": "cross", "interwork_data": null, "badge" : null }, { "pid": "200903", "image": "http://hive-fn.qpyou.cn/hivepromotion/banner/2007/4544_1593745965875_4221_1530011573_nuclear_h480.jpg", "link": "http://test-promotion.qpyou.cn/news/direct/200903", "start_date": "2018-06-26 20:10:00", "end_date": "2026-06-26 20:10:00", "start_unixtimestamp": 1530011400, "end_unixtimestamp": 1782472200, "type_link": "market", "type_banner": "great", "type_camp": "cross", "interwork_data": null, "badge" : null }, { "pid": "202666", "image": "http://hive-fn.qpyou.cn/hivepromotion/banner/2101/9377_1611539481422_inlink_800_ko.png", "link": "http://test-promotion.qpyou.cn/news/direct/202666", "start_date": "2022-11-24 17:00:00", "end_date": "2025-01-31 16:49:00", "start_unixtimestamp": 1669276800, "end_unixtimestamp": 1738309740, "type_link": "webview", "type_banner": "great", "type_camp": "event", "interwork_data": null, "badge" : null }, { "pid": "202667", "image": "http://hive-fn.qpyou.cn/hivepromotion/banner/2202/4588_1645527513984_4656_1643264582739_200225_smon_800_ko.png", "link": "http://test-promotion.qpyou.cn/news/direct/202667", "start_date": "2021-01-21 16:54:00", "end_date": "2023-12-27 16:54:00", "start_unixtimestamp": 1611215640, "end_unixtimestamp": 1703663640, "type_link": "webbrowser", "type_banner": "great", "type_camp": "event", "interwork_data": null, "badge" : null }, { "pid": "202668", "image": "http://hive-fn.qpyou.cn/hivepromotion/banner/2101/5562_1611216401413_marketlink_800_ko.png", "link": "http://test-promotion.qpyou.cn/news/direct/202668", "start_date": "2021-01-21 17:02:00", "end_date": "2025-01-31 17:02:00", "start_unixtimestamp": 1611216120, "end_unixtimestamp": 1738310520, "type_link": "webview", "type_banner": "great", "type_camp": "event", "interwork_data": { "api": "/openurl", "param": "rurl=https%3A%2F%2Fqa-renew-community.summonerswar.com%2Fchronicles%2Fko-kr%2Fboard%2Fdetail%2F22%2F14002" }, "badge" : null } ], "count": 5, "result_code": 200, "result_message": "Success." }