横幅列表
以列表格式提供横幅配置所需的信息。根据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 內容類型 text/html 數據格式 JSON
- 標題
字段名稱 描述 類型 是否必填 授權 CertificationKey 透過 Bearer 授權有效 字串 否
- 標題
欄位名稱 描述 類型 是否必填 授權 透過 Bearer 授權的 CertificationKey 有效 字串 否
- 請求 主體
欄位名稱 描述 類型 必填 user 用戶信息 對象 是 ㄴ uid 平台管理的用戶ID 字符串 否 ㄴ vid 集成模塊的登錄中心管理的VID，或由Authenticaion v4管理的PlayerID。該值在個別模塊中為空。 字符串 否 ㄴ player_token 使用者認證資訊 字串 N ㄴ did 每個設備的唯一ID，由Provisioning生成 字符串 是 ㄴ world 遊戲伺服器資訊 字符串 是 ㄴ language 在遊戲或設備上設置的語言代碼（基於ISO 639-1） 字符串 是 ㄴ hive_country 請求的國家資訊 如果沒有值，則根據請求IP確定該字段。 字符串 否 ㄴ age_gate_u13 是否根據COPPA限制13歲以下的用戶 遊戲工作室從在Hive SDK中實現相關功能的返回值中發送。 - `true`: 限制13歲以下的用戶
- `false`: 無限制
布林值 是 game 遊戲資訊 物件 是 ㄴ appid 嘗試顯示橫幅的遊戲的AppID 字符串 是 ㄴ app_version 確定是否顯示檢查橫幅所需的遊戲版本 字符串 是 promotion 促銷活動數據 物件 是 ㄴ type_camp 促銷活動類型（在Hive控制台註冊活動時選擇或直接輸入） - all: 所有類型
- event: 事件類型
- notice: 通知類型
- cross: 跨活動類型
- Others: 用戶定義的通知類型，最多10個字母小寫字母
字符串 是 ㄴ type_banner 活動橫幅類型 - small: 正常橫幅（條形橫幅）
- great: 插頁式橫幅
- rolling: 滾動橫幅
字符串 是
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: 打開市場（應用商店）頁面 + 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": "成功." }
- 回應（請求 主體中的
type_banner值為great或rolling：插頁式橫幅或滾動橫幅）欄位名稱 描述 類型 是否必填 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：打開市場（應用商店）頁面
- notice：打開公告頁面
- text：打開促銷文本公告
- interwork：移動到遊戲中的指定頁面
- none：停留在頁面上
字串 否 ㄴ interwork_data 提供API和參數以移動到遊戲中的特定頁面（如果沒有信息則為NULL） 物件 否 ㄴㄴ api API URI 字串 N ㄴㄴ 參數 要在 API URI 中使用的查詢字串參數值 字串 N ㄴ type_banner 活動橫幅類型 - great: 插頁橫幅
- small: 正常橫幅（條形橫幅）
- rolling: 滾動橫幅
字串 N ㄴ type_camp 促銷活動類型（在 Hive 控制台註冊活動時選擇或直接輸入） - event: 活動類型
- notice: 通知類型
- permit: 審查橫幅
- cross: 交叉橫幅
字串 N ㄴ badge 通知事件即將結束的徽章信息，以及通知可以領取禮物的可用期間的徽章。滾動橫幅和插頁橫幅始終返回 NULL。物件 N ㄴㄴ 標題 徽章中的文本 字串 N ㄴㄴ 類型 徽章的類型 - shutdown: 通知事件即將結束的徽章
- gift: 通知可獲得禮物的期間的徽章。
字串 N ㄴㄴ start_date 徽章曝光的開始日期（ISO-8601格式） 字串 N ㄴㄴ end_date 徽章曝光的結束日期（ISO-8601格式） 字串 N ㄴㄴ start_unixtimestamp 徽章曝光的開始時間（Unix 時間戳） 整數 N ㄴㄴ end_unixtimestamp 徽章曝光的結束時間（Unix 時間戳） 整數 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": "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." }