Banner list

Provides a list of information required to configure banners. The API response is divided into three types according to the Request Body type_banner value.

small: Delivers information required for general banners, notices, and rolling banners together.
great: Delivers only the information required for full-screen banners.
rolling: Delivers only the information required for rolling banners.
Request URL

Production URL	https://promotion.qpyou.cn/api/banner
Sandbox URL	https://sandbox-promotion.qpyou.cn/api/banner
HTTP Method	POST
Content-Type	text/html
Data Format	JSON

Header

Field name	Description	Type	Required
Authorization	Determines the validity of certificationKey with Bearer Authorization	String	N

Request Body

Field name	Description	Type	Required
user	User information	Object	Y
ㄴ uid	Hive membership UID	String	N
ㄴ vid	PlayerID managed by Hive authentication v4	String	N
ㄴ player_token	User authentication information	String	N
ㄴ did	Unique device ID issued by Hive provisioning	String	Y
ㄴ world	Game server information	String	Y
ㄴ language	Game or device setting language code (ISO 639-1 standard)	String	Y
ㄴ hive_country	If there is no requested country information value, the country is determined based on the request IP	String	N
ㄴ age_gate_u13	Whether the 13-year age restriction required for COPPA applies. Pass the result value from the Hive SDK function call as is from the game true: Restrict users under 13 false: No restriction	Boolean	Y
game	Game information	Object	Y
ㄴ appid	AppID of the game using the banner	String	Y
ㄴ app_version	Game version checked to determine banner exposure for review	String	Y
promotion	Promotion campaign information	Object	Y
ㄴ type_camp	Promotion campaign type (selected or entered directly when registering a campaign in Hive Console) all: All types event: Event type notice: Notice type cross: Cross campaign type Other: User-defined notice type, up to 10 lowercase English letters	String	Y
ㄴ type_banner	Campaign banner type small: General banner (strip banner) great: Full-screen banner rolling: Rolling banner	String	Y

Call 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

Request example

> 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

Response (Request Body type_banner value is small: general banner, notice, rolling banner)

Field name	Description	Type	Required
result_code	Response code 200: Validation successful Others: Failure	Integer	Y
result_message	Response message	String	Y
count	Number of banners	Integer	Y
banner	Banner list If no banners are registered, the array is empty ([])	Array	Y
ㄴ pid	Promotion campaign ID	String	N
ㄴ image	Campaign banner image URL	String	N
ㄴ link	URL to move to when clicking the campaign banner	String	N
ㄴ image_direction	Image direction information landscape: Horizontal portrait: Vertical	String	N
ㄴ start_date	Campaign start time	String	N
ㄴ end_date	Campaign end time	String	N
ㄴ start_unixtimestamp	Campaign start time (Unix timestamp)	Integer	N
ㄴ end_unixtimestamp	Campaign end time (Unix timestamp)	Integer	N
ㄴ type_link	Type of move when clicking the campaign banner (selected when registering a campaign in Hive Console) webview: Move to internal link webbrowser: Move to external link market: Move to market (app store) notice: Move to Hive notice text: Move to promotion text notice interwork: Move to a path specified in the game none: No move	String	N
ㄴ interwork_data	Provides API and parameters to move to a specific location in the game (if no information, NULL)	Object	N
ㄴㄴ api	API URI	String	N
ㄴㄴ param	Query string parameter value to use in API URI	String	N
ㄴ type_banner	Campaign banner type small: General banner rolling: Rolling banner	String	N
ㄴ type_camp	Promotion campaign type event: Event type notice: Notice type permit: Review banner cross: Cross banner	String	N
ㄴ badge	Badge information that notifies imminent event end and gift collection period. Only general banners return this field value. Rolling banners always return `NULL`. If there is no badge information set in Hive Console period notification badge, general banners also return `NULL`. Notices do not have this field at all.	Object	N
ㄴㄴ title	Badge text	String	N
ㄴㄴ type	Badge type displayed shutdown: Imminent event end badge gift: Gift collection period notification badge	String	N
ㄴㄴ start_date	Badge display start date (ISO-8601 format)	String	N
ㄴㄴ end_date	Badge display end date (ISO-8601 format)	String	N
ㄴㄴ start_unixtimestamp	Badge display start time (Unix TimeStamp)	Integer	N
ㄴㄴ end_unixtimestamp	Badge display end time (Unix TimeStamp)	Integer	N
notice_count	Number of notices	Integer	Y
notice	Notice post information	Array	Y
ㄴ nid	Notice post ID	String	N
ㄴ notice_type	Notice post type	String	N
ㄴ title	Notice post title	String	N
ㄴ link	Notice post link URL	String	N
ㄴ start_date	Post display start time	String	N
ㄴ end_date	Post display end time	String	N
ㄴ start_unixtimestamp	Post display start time (Unix timestamp)	String	N
ㄴ end_unixtimestamp	Post display end time (Unix timestamp)	String	N
ㄴ view_count	Post view count	String	N
ㄴ game_index	Post game index information	String	N
ㄴ language	Post setting language code (ISO 639-1 standard)	String	N
rolling_count	Number of rolling banners	Integer	Y
rolling	Rolling banner information	Array	Y
ㄴ pid	Promotion campaign ID	String	N
ㄴ image	Campaign banner image URL	String	N
ㄴ link	URL to move to when clicking the banner	String	N
ㄴ image_direction	Image direction information landscape: Horizontal portrait: Vertical	String	N
ㄴ start_date	Campaign start time	String	N
ㄴ end_date	Campaign end time	String	N
ㄴ start_unixtimestamp	Campaign start time (Unix timestamp)	String	N
ㄴ end_unixtimestamp	Campaign end time (Unix timestamp)	String	N
ㄴ type_link	Type of move when clicking the campaign banner (selected when registering a campaign in Hive Console) webview: Move to internal link webbrowser: Move to external link market: Move to market (app store) notice: Move to Hive notice text: Move to promotion text notice interwork: Move to a path specified in the game none: No move	String	N
ㄴ type_banner	Campaign banner type small: General banner rolling: Rolling banner	String	N
ㄴ type_camp	Promotion campaign type event: Event type notice: Notice type permit: Review banner cross: Cross banner	String	N
ㄴ interwork_data	Provides API and parameters to move to a specific location in the game (if no information, NULL)	Object	N
ㄴㄴ api	API URI	String	N
ㄴㄴ param	Query string parameter value to use in API URI	String	N

Result code

Code	Message	Description
200	Success	Data delivered successfully

Response example (general banner, notice, rolling banner)

< 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."
}

Response (Request Body type_banner value is great or rolling: full-screen banner or rolling banner)

Field name	Description	Type	Required
result_code	Response code 200: Validation successful Others: Failure	String	Y
result_message	Response message	String	Y
count	Number of banners	Integer	Y
banner	Banner list If no banners are registered, the array is empty ([])	Array	Y
ㄴ pid	Promotion campaign ID	String	N
ㄴ image	Campaign banner image URL	String	N
ㄴ link	URL to move to when clicking the campaign banner	String	N
ㄴ image_direction	Image direction information landscape: Horizontal portrait: Vertical	String	N
ㄴ start_date	Campaign start time	String	N
ㄴ end_date	Campaign end time	String	N
ㄴ start_unixtimestamp	Campaign start time (Unix timestamp)	Integer	N
ㄴ end_unixtimestamp	Campaign end time (Unix timestamp)	Integer	N
ㄴ type_link	Type of move when clicking the campaign banner (selected when registering a campaign in Hive Console) webview: Move to internal link webbrowser: Move to external link market: Move to market (app store) notice: Move to Hive notice text: Move to promotion text notice interwork: Move to a path specified in the game none: No move	String	N
ㄴ interwork_data	Provides API and parameters to move to a specific location in the game (if no information, NULL)	Object	N
ㄴㄴ api	API URI	String	N
ㄴㄴ param	Query string parameter value to use in API URI	String	N
ㄴ type_banner	Campaign banner type great: Full-screen banner small: General banner (strip banner) rolling: Rolling banner	String	N
ㄴ type_camp	Promotion campaign type (selected or entered directly when registering a campaign in Hive Console) event: Event type notice: Notice type permit: Review banner cross: Cross banner	String	N
ㄴ badge	Badge information that notifies imminent event end and gift collection period. Rolling banners and full-screen banners always return `NULL`.	Object	N
ㄴㄴ title	Badge text	String	N
ㄴㄴ type	Badge type displayed shutdown: Imminent event end badge gift: Gift collection period notification badge	String	N
ㄴㄴ start_date	Badge display start date (ISO-8601 format)	String	N
ㄴㄴ end_date	Badge display end date (ISO-8601 format)	String	N
ㄴㄴ start_unixtimestamp	Badge display start time (Unix TimeStamp)	Integer	N
ㄴㄴ end_unixtimestamp	Badge display end time (Unix TimeStamp)	Integer	N

Result code

Code	Message	Description
200	Success	Data delivered successfully

Response example (full-screen banner or rolling banner)

< 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."
}