横幅列表

提供了配置横幅所需信息的列表。API 响应根据请求体 type_banner 值分为三种类型。

small: 提供一般横幅、通知和滚动横幅所需的信息。
great: 仅提供全屏横幅所需的信息。
rolling: 仅提供滚动横幅所需的信息。
请求 URL

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

头部

字段名称	描述	类型	必需
Authorization	确定 certificationKey 与 Bearer Authorization 的有效性	字符串	否

请求体

字段名称	描述	类型	必需
user	用户信息	对象	Y
ㄴ uid	Hive 会员 UID	字符串	N
ㄴ vid	由 Hive 身份验证 v4 管理的 PlayerID	字符串	N
ㄴ player_token	用户身份验证信息	字符串	N
ㄴ did	Hive 配置颁发的唯一设备 ID	字符串	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 控制台注册活动时选择或直接输入）	字符串	Y
ㄴ type_banner	活动横幅类型	字符串	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

请求示例

> 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
ㄴ image_direction	图像方向信息 landscape: 横向 portrait: 纵向	字符串	N
ㄴ start_date	活动开始时间	字符串	N
ㄴ end_date	活动结束时间	字符串	N
ㄴ start_unixtimestamp	活动开始时间 (Unix 时间戳)	整数	N
ㄴ end_unixtimestamp	活动结束时间 (Unix 时间戳)	整数	N
ㄴ type_link	点击活动横幅时的跳转类型（在 Hive 控制台注册活动时选择） webview: 跳转到内部链接 webbrowser: 跳转到外部链接 market: 跳转到市场（应用商店） notice: 跳转到 Hive 通知 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
ㄴ nid	通知帖子 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
ㄴ image_direction	图像方向信息 landscape: 横向 portrait: 纵向	字符串	N
ㄴ start_date	活动开始时间	字符串	N
ㄴ end_date	活动结束时间	字符串	N
ㄴ start_unixtimestamp	活动开始时间（Unix 时间戳）	字符串	N
ㄴ end_unixtimestamp	活动结束时间（Unix 时间戳）	字符串	N
ㄴ type_link	点击活动横幅时的跳转类型（在 Hive 控制台注册活动时选择） webview: 跳转到内部链接 webbrowser: 跳转到外部链接 market: 跳转到市场（应用商店） notice: 跳转到 Hive 通知 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",
            "image_direction": "landscape",
            "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": "Gift Collection Period",
                "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": "",
            "image_direction": "landscape",
            "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",
            "image_direction": "landscape",
            "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": "Guide",
            "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",
            "image_direction": "landscape",
            "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": "Success."
}

响应（请求体 type_banner 值为 great 或 rolling：全屏横幅或滚动横幅）

字段名称	描述	类型	必需
result_code	响应代码 200: 验证成功其他: 失败	字符串	是
result_message	响应消息	字符串	是
count	横幅数量	整数	是
banner	横幅列表如果没有注册横幅，则数组为空 ([])	数组	是
ㄴ pid	推广活动 ID	字符串	否
ㄴ image	活动横幅图像 URL	字符串	否
ㄴ link	点击活动横幅时移动的 URL	字符串	否
ㄴ image_direction	图像方向信息 landscape: 横向 portrait: 纵向	字符串	否
ㄴ start_date	活动开始时间	字符串	否
ㄴ end_date	活动结束时间	字符串	否
ㄴ start_unixtimestamp	活动开始时间 (Unix 时间戳)	整数	否
ㄴ end_unixtimestamp	活动结束时间 (Unix 时间戳)	整数	否
ㄴ type_link	点击活动横幅时的移动类型（在 Hive 控制台注册活动时选择） webview: 移动到内部链接 webbrowser: 移动到外部链接 market: 移动到市场（应用商店） notice: 移动到 Hive 通知 text: 移动到推广文本通知 interwork: 移动到游戏中指定的路径 none: 不移动	字符串	否
ㄴ interwork_data	提供 API 和参数以移动到游戏中的特定位置（如果没有信息，则为 NULL）	对象	否
ㄴㄴ api	API URI	字符串	否
ㄴㄴ param	用于 API URI 的查询字符串参数值	字符串	否
ㄴ type_banner	活动横幅类型 great: 全屏横幅 small: 一般横幅（条形横幅） rolling: 滚动横幅	字符串	否
ㄴ type_camp	推广活动类型（在 Hive 控制台注册活动时选择或直接输入） event: 事件类型 notice: 通知类型 permit: 审核横幅 cross: 交叉横幅	字符串	否
ㄴ badge	通知即将结束的事件和礼物领取期限的徽章信息。滚动横幅和全屏横幅始终返回 `NULL`。	对象	否
ㄴㄴ title	徽章文本	字符串	否
ㄴㄴ type	显示的徽章类型 shutdown: 即将结束事件的徽章 gift: 礼物领取期限通知徽章	字符串	否
ㄴㄴ start_date	徽章显示开始日期（ISO-8601 格式）	字符串	否
ㄴㄴ end_date	徽章显示结束日期（ISO-8601 格式）	字符串	否
ㄴㄴ start_unixtimestamp	徽章显示开始时间（Unix 时间戳）	整数	否
ㄴㄴ end_unixtimestamp	徽章显示结束时间（Unix 时间戳）	整数	否

结果代码

代码	消息	描述
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",
            "image_direction": "landscape",
            "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",
            "image_direction": "landscape",
            "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",
            "image_direction": "landscape",
            "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",
            "image_direction": "landscape",
            "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",
            "image_direction": "landscape",
            "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."
}