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.

  1. small: Delivers information required for general banners, notices, and rolling banners together.

  2. great: Delivers only the information required for full-screen banners.

  3. rolling: Delivers only the information required for rolling banners.

  4. Request URL

Production URL https://promotion.qpyou.cn/api/banner
Sandbox URL https://sandbox-promotion.qpyou.cn/api/banner
HTTP Method POST
Content-Type application/json
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: application/json; 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: application/json; 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."
}