横幅列表
以列表格式提供橫幅配置所需的信息。根據Request Body的type_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
- 標題
欄位名稱 描述 類型 必填 授權 透過 Bearer 授權的 CertificationKey 有效 字串 N
- 標題
字段名稱 描述 類型 是否必填 授權 通過 Bearer 授權的 CertificationKey 有效 字串 N
- 請求 主體
欄位名稱 描述 類型 是否必填 user 用戶信息 物件 是 Hive 會員 UID 字串 否 ㄴ vid 由 Authenticaion v4 管理的 PlayerID。 字串 否 ㄴ player_token 用戶身份驗證信息 字符串 N ㄴ did 每個設備的唯一ID,由Provisioning生成 字串 Y ㄴ world 遊戲伺服器資訊 字串 Y ㄴ language 在遊戲或設備上設定的語言代碼(基於ISO 639-1) 字串 Y ㄴ hive_country 請求的國家資訊 如果不存在值,則根據請求IP確定該字段。 字串 N ㄴ age_gate_u13 是否根據COPPA限制13歲以下的用戶 遊戲工作室從Hive SDK中實現相關功能的返回值。 布林值 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: 打開市場(應用商店)頁面 + 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 ㄴㄴ title 徽章中的文本 字符串 N ㄴㄴ 類型 徽章的類型 - 關閉:通知事件即將結束的徽章
- 禮物:通知可接收禮物的期間的徽章。
字串 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": "成功." }