배너 목록

배너 구성에 필요한 정보를 리스트 형태로 제공합니다. API 응답은 Request Body type_banner값에 따라 3개로 나뉩니다.

1. small: 일반 배너, 공지사항, 롤링 배너 구성에 필요한 정보를 함께 전달합니다.

2. great: 전면 배너 구성에 필요한 정보만 전달합니다.

3. rolling: 롤링 배너 구성에 필요한 정보만 전달합니다.

  • Request URL
상용 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
필드명 설명 타입 필수여부
Authorization Bearer Authorization으로 certificationKey 유효 판단 String N
  • Request Body
필드명 설명 타입 필수여부
user 사용자 정보 Object Y
ㄴ uid 플랫폼에서 관리하는 유저 ID String N
ㄴ vid 통합 모듈 로그인 센터가 관리하는 VID 또는 Hive 인증 v4에서 관리하는 PlayerID. Hive SDK v4가 아닌 C2S 개별모듈 사용 시, 이 필드 값은 존재하지 않음. String N
ㄴ player_token 유저 인증 정보 String N
ㄴ did Hive 프로비저닝에서 발급하는 기기의 고유 ID String Y
ㄴ world 게임 서버 정보 String Y
ㄴ language 게임 또는 기기 설정 언어 코드 (ISO 639-1 기준) String Y
ㄴ hive_country 요청하는 국가 정보 값이 없을 경우 요청 IP를 기준으로 국가를 결정 String N
ㄴ age_gate_u13 COPPA 적용에 필요한 13세 나이 제한 여부 Hive SDK 함수 호출 결과 값을 게임에서 그대로 전달
  • true: 13세 미만 유저 제한
  • false: 제한 없음
Boolean Y
game 게임 정보 Object Y
ㄴ appid 배너를 활용할 게임의 AppID String Y
ㄴ app_version 검수 배너 노출 여부를 결정할 때 확인하는 게임 버전 String Y
promotion 프로모션 캠페인 정보 Object Y
ㄴ type_camp 프로모션 캠페인 타입 (Hive 콘솔에서 캠페인 등록 시 선택 또는 직접 입력)
  • all: 모든 타입
  • event: 이벤트 타입
  • notice: 공지 타입
  • cross: 크로스 캠페인 타입
  • 기타: 사용자가 정의하는 공지 타입으로, 최대 10자 영소문자로 구성 가능
String Y
ㄴ type_banner 캠페인 배너 타입
  • small: 일반 배너 (띠배너)
  • great: 전면 배너
  • rolling: 롤링 배너
String 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
  • Response (Request Body type_banner값이 small: 일반 배너, 공지사항, 롤링 배너)
필드명 설명 타입 필수여부
result_code 응답 코드
  • 200: 검증 성공
  • 그 외: 실패
Integer Y
result_message 응답 메시지 String Y
count 배너 개수 Integer Y
banner 배너 목록
배너를 등록하지 않은 경우 배열이 비어 있음 ([])		 Array Y
ㄴ pid 프로모션 캠페인 ID String N
ㄴ image 캠페인 배너 이미지 URL String N
ㄴ link 캠페인 배너를 클릭했을 때 이동하는 URL String N
ㄴ start_date 캠페인 시작 시각 String N
ㄴ end_date 캠페인 종료 시각 String N
ㄴ start_unixtimestamp 캠페인 시작 시각 (Unix timestamp) Integer N
ㄴ end_unixtimestamp 캠페인 종료 시각 (Unix timestamp) Integer N
ㄴ type_link 캠페인 배너를 클릭했을 때 이동하는 타입 (Hive 콘솔에서 캠페인 등록 시 선택하는 항목)
  • webview: 내부 링크로 이동
  • webbrowser: 외부 링크로 이동
  • market: 마켓(앱스토어)으로 이동
  • notice: Hive 공지로 이동
  • text: 프로모션 텍스트 공지로 이동
  • interwork: 게임에서 지정된 경로로 이동
  • none: 이동 안 함
String N
ㄴ interwork_data 게임 내 특정 위치로 이동할 수 있도록 API와 파라미터 제공 (해당하는 정보가 없는 경우 NULL) Object N
ㄴㄴ api API URI String N
ㄴㄴ param API URI에서 사용할 쿼리 스트링 파라미터 값 String N
ㄴ type_banner 캠페인 배너 타입
  • small: 일반 배너
  • rolling: 롤링 배너
String N
ㄴ type_camp 프로모션 캠페인 타입
  • event: 이벤트 타입
  • notice: 공지 타입
  • permit: 검수 배너
  • cross: 크로스 배너
String N
ㄴ badge 이벤트 종료 임박 여부와 선물 수령 기간을 알리는 배지 정보입니다. 일반 배너만 이 필드값을 반환합니다. 롤링 배너는 항상 NULL을 반환합니다. 일반 배너도 Hive 콘솔기간 알림 배지에서 설정한 배지 정보가 없으면 NULL을 반환합니다. 공지사항은 이 필드 자체가 존재하지 않습니다. Object N
ㄴㄴ title 배지 문구 String N
ㄴㄴ type 노출하는 배지 타입
  • shutdown: 이벤트 종료 임박 배지
  • gift: 선물 수령 기간 알림 배지
String N
ㄴㄴ start_date 배지 노출 시작 날짜 (ISO-8601 포맷) String N
ㄴㄴ end_date 배지 노출 종료 날짜 (ISO-8601 포맷) String N
ㄴㄴ start_unixtimestamp 배지 노출 시작 시간 (Unix TimeStamp) Integer N
ㄴㄴ end_unixtimestamp 배지 노출 종료 시간 (Unix TimeStamp) Integer N
notice_count 공지 개수 Integer Y
notice 공지 게시글 정보 Array Y
ㄴ nid 공지 게시글 ID String N
ㄴ notice_type 공지 게시글 타입 String N
ㄴ title 공지 게시글 제목 String N
ㄴ link 공지 게시글 연결 URL String N
ㄴ start_date 게시글 노출 시작 시각 String N
ㄴ end_date 게시글 노출 종료 시각 String N
ㄴ start_unixtimestamp 게시글 노출 시작 시각 (Unix timestamp) String N
ㄴ end_unixtimestamp 게시글 노출 종료 시각 (Unix timestamp) String N
ㄴ view_count 게시글 조회 수 String N
ㄴ game_index 게시글 게임 인덱스 정보 String N
ㄴ language 게시글 설정 언어 코드((ISO 639-1 기준) String N
rolling_count 롤링 배너 개수 Integer Y
rolling 롤링 배너 정보 Array Y
ㄴ pid 프로모션 캠페인 ID String N
ㄴ image 캠페인 배너 이미지 URL String N
ㄴ link 배너 클릭 시 이동하는 URL String N
ㄴ start_date 캠페인 시작 시각 String N
ㄴ end_date 캠페인 종료 시각 String N
ㄴ start_unixtimestamp 캠페인 시작 시각 (Unix timestamp) String N
ㄴ end_unixtimestamp 캠페인 종료 시각 (Unix timestamp) String N
ㄴ type_link 캠페인 배너를 클릭했을 때 이동하는 타입 (Hive 콘솔에서 캠페인 등록 시 선택하는 항목)
  • webview: 내부 링크로 이동
  • webbrowser: 외부 링크로 이동
  • market: 마켓(앱스토어)으로 이동
  • notice: Hive 공지로 이동
  • text: 프로모션 텍스트 공지로 이동
  • interwork: 게임에서 지정된 경로로 이동
  • none: 이동 안 함
 String N
ㄴ type_banner 캠페인 배너 타입
  • small: 일반 배너
  • rolling: 롤링 배너
String N
ㄴ type_camp 프로모션 캠페인 타입
  • event: 이벤트 타입
  • notice: 공지 타입
  • permit: 검수 배너
  • cross: 크로스 배너
String N
ㄴ interwork_data 게임 내 특정 위치로 이동할 수 있도록 API와 파라미터 제공(정보가 없는 경우 NULL) Object N
ㄴㄴ api API URI String N
ㄴㄴ param API URI에서 사용할 쿼리 스트링 파라미터 값 String N
  • Result code
코드 메시지 설명
200 Success 데이터 전달 성공
  • 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": "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": "안내",
            "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": "이벤트",
            "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 (Request Body type_banner값이 great 또는 rolling: 전면 배너 또는 롤링 배너)
필드명 설명 타입 필수여부
result_code 응답 코드
  • 200: 검증 성공
  • 그 외: 실패
String Y
result_message 응답 메시지 String Y
count 배너 개수 Integer Y
banner 배너 목록
배너를 등록하지 않은 경우 배열이 비어 있음 ([])		 Array Y
ㄴ pid 프로모션 캠페인 ID String N
ㄴ image 캠페인 배너 이미지 URL String N
ㄴ link 캠페인 배너를 클릭했을 때 이동하는 URL String N
ㄴ start_date 캠페인 시작 시각 String N
ㄴ end_date 캠페인 종료 시각 String N
ㄴ start_unixtimestamp 캠페인 시작 시각 (Unix timestamp) Integer N
ㄴ end_unixtimestamp 캠페인 종료 시각 (Unix timestamp) Integer N
ㄴ type_link 캠페인 배너를 클릭했을 때 이동하는 타입 (Hive 콘솔에서 캠페인 등록 시 선택하는 항목)
  • webview: 내부 링크로 이동
  • webbrowser: 외부 링크로 이동
  • market: 마켓(앱스토어)으로 이동
  • notice: Hive 공지로 이동
  • text: 프로모션 텍스트 공지로 이동
  • interwork: 게임에서 지정된 경로로 이동
  • none: 이동 안 함
String N
ㄴ interwork_data 게임 내 특정 위치로 이동할 수 있도록 API와 파라미터 제공(정보가 없는 경우 NULL) Object N
ㄴㄴ api API URI String N
ㄴㄴ param API URI에서 사용할 쿼리 스트링 파라미터 값 String N
ㄴ type_banner 캠페인 배너 타입
  • great: 전면 배너
  • small: 일반 배너 (띠배너)
  • rolling: 롤링 배너
String N
ㄴ type_camp 프로모션 캠페인 타입 (Hive 콘솔에서 캠페인 등록 시 선택 또는 직접 입력)
  • event: 이벤트 타입
  • notice: 공지 타입
  • permit: 검수 배너
  • cross : 크로스 배너
    		String N
    ㄴ badge 이벤트 종료 임박 여부와 선물 수령 기간을 알리는 배지 정보입니다. 롤링 배너와 전면 배너는 항상 NULL을 반환합니다. Object N
    ㄴㄴ title 배지 문구 String N
    ㄴㄴ type 노출하는 배지 타입
    • shutdown: 이벤트 종료 임박 배지
    • gift: 선물 수령 기간 알림 배지
    		String N
    ㄴㄴ start_date 배지 노출 시작 날짜 (ISO-8601 포맷) String N
    ㄴㄴ end_date 배지 노출 종료 날짜 (ISO-8601 포맷) String N
    ㄴㄴ start_unixtimestamp 배지 노출 시작 시간 (Unix TimeStamp) Integer N
    ㄴㄴ end_unixtimestamp 배지 노출 종료 시간 (Unix TimeStamp) Integer N
    • Result code
    코드 메시지 설명
    200 Success 데이터 전달 성공
    • 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": "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."
}