横幅列表

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

标题

字段名称 描述类型必需

授权通过Bearer授权的CertificationKey有效字符串否

标题

字段名称 描述类型 是否必填

授权通过Bearer授权的CertificationKey有效字符串否

请求主体

字段名称	描述	类型	必需
用户	用户信息	对象	是
ㄴ uid	平台管理的用户ID	字符串	否
ㄴ vid	由集成模块的登录中心管理的VID，或由认证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: 滚动横幅	字符串	是

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: 验证成功 + 其他: 失败	整数	是
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	字符串	否
ㄴㄴ param	用于API URI的查询字符串参数值	字符串	否
ㄴ type_banner	活动横幅类型 + small: 普通横幅 + rolling: 滚动横幅	字符串	否
ㄴ type_camp	推广活动的类型 + event: 事件类型 + notice: 通知类型 + permit: 审查横幅 + cross: 跨界横幅	字符串	否
ㄴ badge	通知活动即将结束的徽章信息，以及通知可以领取礼物的可用期限的徽章。只有普通横幅返回此字段值。滚动横幅始终返回`NULL`。如果在Hive控制台的期间通知徽章设置中没有设置徽章信息，普通横幅也返回`NULL`。通知类型没有此字段。	对象	否
ㄴㄴ title	徽章中的文本	字符串	否
ㄴㄴ type	徽章曝光的类型 + shutdown: 通知活动即将结束的徽章 + gift: 通知可领取礼物的可用期限的徽章。	字符串	否
ㄴㄴ start_date	徽章曝光的开始日期（ISO-8601格式）	字符串	否
ㄴㄴ end_date	徽章曝光的结束日期（ISO-8601格式）	字符串	否
ㄴㄴ start_unixtimestamp	徽章曝光的开始时间（Unix时间戳）	整数	否
ㄴㄴ end_unixtimestamp	徽章曝光的结束时间（Unix时间戳）	整数	否
notice_count	通知的数量	整数	是
notice	发布通知的信息	数组	是
ㄴ pid	发布通知的ID	字符串	否
ㄴ notice_type	发布通知的类型	字符串	否
ㄴ title	发布通知的标题	字符串	否
ㄴ link	发布通知的URL	字符串	否
ㄴ start_date	发布的曝光开始时间	字符串	否
ㄴ end_date	发布的曝光结束时间	字符串	否
ㄴ start_unixtimestamp	发布的曝光开始时间（Unix时间戳）	字符串	否
ㄴ end_unixtimestamp	发布的曝光结束时间（Unix时间戳）	字符串	否
ㄴ view_count	发布的浏览次数	字符串	否
ㄴ game_index	发布的游戏索引信息	字符串	否
ㄴ language	为发布设置的语言代码（基于ISO 639-1）	字符串	否
rolling_count	滚动横幅的数量	整数	是
rolling	滚动横幅的信息	数组	是
ㄴ pid	推广活动ID	字符串	否
ㄴ image	活动横幅的图片URL	字符串	否
ㄴ link	点击横幅时要转到的URL	字符串	否
ㄴ 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	成功	数据传输成功

Response Example (普通横幅, 通知, 滚动横幅)

< 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": "测试",
                        "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
ㄴㄴ param	在 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": "成功."
}

常用 URL	https://promotion.qpyou.cn/api/banner
沙盒 URL	https://sandbox-promotion.qpyou.cn/api/banner
HTTP 方法	POST
内容类型	text/html
数据格式	JSON