Banner list

Provides information required for banner configuration in a list format. There are 3 API responses according to the Request Body type_banner value.

  1. small: Returns the information needed to configure normal banners, notices, and rolling banners.
  2. great: Returns only the information needed to configure interstitial banners.
  3. rolling: Returns only the information needed to configure the rolling banner.

 

  • Request URL
    Common 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 CertificationKey valid through Bearer Authorization String N
  • Header
    Field Name Description Type Required
    Authorization CertificationKey valid through Bearer Authorization String N
  • Request Body
    Field Name Description Type Required
    user User information Object Y
    ㄴ uid User ID managed by platform String N
    ㄴ vid VID managed by login center on integration module, or PlayerID managed by Authenticaion v4. The value is empty with individual modules. String N
    ㄴ player_token user authentication information String N
    ㄴ did Unique ID for each device that Provisioning generates String Y
    ㄴ world Game server information String Y
    ㄴ language Language code set on game or device (based on ISO 639-1) String Y
    ㄴ hive_country Requested country information If no value exists, the field is determined based on the request IP. String N
    ㄴ age_gate_u13 Whether to limit users under 13 according to COPPA Game studio sends the return value from implementing relevant functions in Hive SDK.
    • `true`: restrict the users under 13
    • `false`: no restriction
    		 Boolean Y
    game Game information Object Y
    ㄴ appid AppID of a game which attempts to expose the banner String Y
    ㄴ app_version Game version required to determine whether displaying an examination banner or not String Y
    promotion Promotion campaign data Object Y
    ㄴ type_camp Promotion campaign type (select or enter directly when registering a campaign in the Hive Console)
    • all: all types
    • event: event type
    • notice: notice type
    • cross: cross campaign type
    • Others: notice type defined by the user, up to 10 alphabetical lower case letters
    		 String Y
    ㄴ type_banner Campaign banner type
    • small: normal banner (strip banner)
    • great: interstitial banner
    • rolling: Rolling Banner
    		 String 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
  • 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 (the type_banner value in Request Body is small: normal banner, notice, rolling banner)
    Field Name Description Type Required
    result_code response code + 200: verification success + others: failure Integer Y
    result_message response message String Y
    count the number of banners Integer Y
    banner the list of banners The array is empty([]) without banner registration. Array Y
    ㄴ pid promotion campaign ID String N
    ㄴ image The image URL of campaign banner String N
    ㄴ link The URL opening when user clicks a campaign banner String N
    ㄴ start_date The start date of campaign String N
    ㄴ end_date The end date of campaign String N
    ㄴ start_unixtimestamp The start time of campaign (Unix timestamp) Integer N
    ㄴ end_unixtimestamp The end time of campaign (Unix timestamp) Integer N
    ㄴ type_link The type to open pages when user clicks a campaign banner (select when registering campaigns) + webview: Open an internal link + webbrowser: Open an external link + market: Open the market (App Store) page + notice: Open the notice page + text: Open the promotion text notice + interwork: Move to the specified page in the game + none: Stay on the page String N
    ㄴ interwork_data Provides API and parameters to move to a specific page in the game (NULL if there is no corresponding information) Object N
    ㄴㄴ api API URI String N
    ㄴㄴ param Query string parameter value to be used in the API URI String N
    ㄴ type_banner Campaign banner type + small: normal banner + rolling: Rolling Banner String N
    ㄴ type_camp The campaign type of promotion + event: event type + notice: notice type + permit: examination banner + cross: cross banner String N
    ㄴ badge The information of the badge notifying an event will end soon, and the badge notifying the available period one can receive gifts. Only normal banners return this field value. The rolling banners always return NULL. The normal banners also returns NULL if there is no badge information set in the Period Notification Badge Settings of the Hive Console. The notice type does not have this field. Object N
    ㄴㄴ title the texts in the badge String N
    ㄴㄴ type the type of the badge exposed + shutdown: the badge notifying the imminent end of an event + gift: the badge notifying the available period of receiving a gift. String N
    ㄴㄴ start_date the start date of badge exposure (ISO-8601 format) String N
    ㄴㄴ end_date the end date of badge exposure (ISO-8601 format) String N
    ㄴㄴ start_unixtimestamp the start time of badge exposure (Unix timestamp) Integer N
    ㄴㄴ end_unixtimestamp the end time of badge exposure (Unix timestamp) Integer N
    notice_count the number of notices Integer Y
    notice the information of the posted notice Array Y
    ㄴ pid the id of the posted notice String N
    ㄴ notice_type the type of the posted notice String N
    ㄴ title the title of the posted notice String N
    ㄴ link the URL of the posted notice String N
    ㄴ start_date the start time of the exposure of the post String N
    ㄴ end_date the end time of the exposure of the post String N
    ㄴ start_unixtimestamp the start time of the exposure of the post (Unix timestamp) String N
    ㄴ end_unixtimestamp the end time of the exposure of the post (Unix timestamp) String N
    ㄴ view_count the number of views for the post String N
    ㄴ game_index the index information of the game from the post String N
    ㄴ language the language code set for the post (based on ISO 639-1) String N
    rolling_count the number of rolling banners Integer Y
    rolling the information of the rolling banner Array Y
    ㄴ pid promotion campaign ID String N
    ㄴ image The image URL of campaign banner String N
    ㄴ link URL to go to when clicking the banner String N
    ㄴ start_date The start date of campaign String N
    ㄴ end_date The end date of campaign String N
    ㄴ start_unixtimestamp The start time of campaign (Unix timestamp) String N
    ㄴ end_unixtimestamp The end time of campaign (Unix timestamp) String N
    ㄴ type_link The type to open pages when user clicks a campaign banner (select when registering campaigns) + webview: Open an internal link + webbrowser: Open an external link + market: Open the market (App Store) page + notice: Open the notice page + text: Open the promotion text notice + interwork: Move to the specified page in the game + none: Stay on the page String N
    ㄴ type_banner Campaign banner type + small: normal banner + rolling: Rolling Banner String N
    ㄴ type_camp The campaign type of promotion + event: event type + notice: notice type + permit: examination banner + cross: cross banner String N
    ㄴ interwork_data Provides API and parameters to move to a specific page in the game (NULL if there is no information) Object N
    ㄴㄴ api API URI String N
    ㄴㄴ param Query string parameter value to be used in the API URI String N
    • Result code
      • Code Message Description
      200 Success data transmission succeeded
    • Response Example (Normal 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",
                        "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": "",
                        "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": "Success."
}

     

    • Response (the type_banner value in the Request Body is great or rolling: interstitial banner or rolling banner)
      Field Name Description Type Required
      result_code response code
      • 200: verification success
      • others: failure
      		 String Y
      result_message response message String Y
      count the number of banners Integer Y
      banner the list of banners The array is empty([]) without banner registration. Array Y
      ㄴ pid promotion campaign ID String N
      ㄴ image The image URL of campaign banner String N
      ㄴ link The URL opening when user clicks a campaign banner String N
      ㄴ start_date The start date of campaign String N
      ㄴ end_date The end date of campaign String N
      ㄴ start_unixtimestamp The start time of campaign (Unix timestamp) Integer N
      ㄴ end_unixtimestamp The end time of campaign (Unix timestamp) Integer N
      ㄴ type_link The type to open pages when user clicks a campaign banner (select when registering campaigns)
      • webview: Open an internal link
      • webbrowser: Open an external link
      • market: Open the market (App Store) page
      • notice: Open the notice page
      • text: Open the promotion text notice
      • interwork: Move to the specified page in the game
      • none: Stay on the page
      		 String N
      ㄴ interwork_data Provides API and parameters to move to a specific page in the game (NULL if there is no information) Object N
      ㄴㄴ api API URI String N
      ㄴㄴ param Query string parameter value to be used in the API URI String N
      ㄴ type_banner Campaign banner type
      • great: interstitial banner
      • small: normal banner (strip banner)
      • rolling: Rolling Banner
      		 String N
      ㄴ type_camp Promotion campaign type (select or enter directly when registering a campaign in the Hive Console)
      • event: event type
      • notice: notice type
      • permit: examination banner
      • cross: cross banner
      		 String N
      ㄴ badge The information of the badge notifying an event will end soon, and the badge notifying the available period one can receive gifts. The rolling banners and interstitial banners always return NULL. Object N
      ㄴㄴ title the texts in the badge String N
      ㄴㄴ type the type of the badge exposed
      • shutdown: the badge notifying the imminent end of an event
      • gift: the badge notifying the available period of receiving a gift.
      		 String N
      ㄴㄴ start_date the start date of badge exposure (ISO-8601 format) String N
      ㄴㄴ end_date the end date of badge exposure (ISO-8601 format) String N
      ㄴㄴ start_unixtimestamp the start time of badge exposure (Unix timestamp) Integer N
      ㄴㄴ end_unixtimestamp the end time of badge exposure (Unix timestamp) Integer N
    • Result code
      • Code Message Description
      200 Success data transmission succeeded
    • Response Example (Interstitial 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",
                        "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": "Success."
}