横幅列表

以列表格式提供橫幅配置所需的信息。根據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

Request Body Example

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

請求範例<

> POST /api/banner HTTP/1.1
> User-Agent: curl/7.29.0
> Host: sandbox-promotion.qpyou.cn
> Accept: /    > Content-Type: application/json
> Content-Length: 292

回應（請求主體中的 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": "成功."
}

常用 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