バナーリスト

バナーを設定するために必要な情報のリストを提供します。APIのレスポンスは、リクエストボディのtype_banner値に応じて3種類に分かれています。

  1. small: 一般的なバナー、通知、ロールバナーに必要な情報をまとめて提供します。

  2. great: フルスクリーンバナーに必要な情報のみを提供します。

  3. rolling: ローリングバナーに必要な情報のみを提供します。

  4. リクエストURL

プロダクションURL https://promotion.qpyou.cn/api/banner
サンドボックスURL https://sandbox-promotion.qpyou.cn/api/banner
HTTPメソッド POST
コンテンツタイプ text/html
データフォーマット JSON
  • ヘッダー
フィールド名 説明 タイプ 必須
Authorization Bearer AuthorizationでcertificationKeyの有効性を決定します 文字列 N
  • リクエストボディ
フィールド名 説明 タイプ 必須
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関数呼び出しの結果値をそのまま渡します
  • true: 13歳未満のユーザーを制限
  • false: 制限なし
ブール値 Y
game ゲーム情報 オブジェクト Y
ㄴ appid バナーを使用するゲームのAppID 文字列 Y
ㄴ app_version バナー表示のレビューを判断するために確認されたゲームバージョン 文字列 Y
promotion プロモーションキャンペーン情報 オブジェクト Y
ㄴ type_camp プロモーションキャンペーンのタイプ(Hiveコンソールでキャンペーンを登録する際に選択または直接入力)
  • all: すべてのタイプ
  • event: イベントタイプ
  • notice: お知らせタイプ
  • cross: クロスキャンペーンタイプ
  • その他: ユーザー定義のお知らせタイプ、最大10文字の小文字英字
文字列 Y
ㄴ type_banner キャンペーンバナータイプ
  • small: 一般的なバナー(ストリップバナー)
  • great: フルスクリーンバナー
  • rolling: ローリングバナー
文字列 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 Consoleでキャンペーンを登録するときに選択)
  • 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 Consoleでバッジ情報が設定されていない場合 期間通知バッジ、一般バナーも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 Consoleでキャンペーンを登録するときに選択)
  • 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: 検証成功
  • その他: 失敗
文字列 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 Consoleでキャンペーンを登録する際に選択)
  • webview: 内部リンクに移動
  • webbrowser: 外部リンクに移動
  • market: マーケット(アプリストア)に移動
  • notice: Hiveのお知らせに移動
  • text: プロモーションテキストのお知らせに移動
  • interwork: ゲーム内で指定されたパスに移動
  • none: 移動しない
文字列 N
ㄴ interwork_data ゲーム内の特定の場所に移動するためのAPIとパラメータを提供(情報がない場合はNULL) オブジェクト N
ㄴㄴ api API URI 文字列 N
ㄴㄴ param API URIで使用するクエリ文字列パラメータの値 文字列 N
ㄴ type_banner キャンペーンバナータイプ
  • great: フルスクリーンバナー
  • small: 一般的なバナー(ストリップバナー)
  • rolling: ローリングバナー
文字列 N
ㄴ type_camp プロモーションキャンペーンタイプ(Hive Consoleでキャンペーンを登録する際に選択または直接入力)
  • event: イベントタイプ
  • notice: お知らせタイプ
  • permit: レビュー用バナー
  • cross: クロスバナー
文字列 N
ㄴ badge 迫るイベント終了とギフト収集期間を通知するバッジ情報。ローリングバナーとフルスクリーンバナーは常に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
  • 結果コード
コード メッセージ 説明
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."
}