コンテンツにスキップ

キャンペーン登録

`## Integration prerequisites

To integrate with the campaign registration API, obtain an authentication token (API key). If you already have a token, request only the additional permissions. See Hive Server API > Notification > Push v4 > Authentication for instructions on issuing a token and requesting permissions.

キャンペーン登録 API

基本情報およびリクエストパラメータ

Method POST
URL /push/campaigns
Section Field name Description Type Required
Header Content-Type application/json;charset=utf-8
Authorization bearer {{API KEY}}
Body id Required when updating a campaign Integer △
status Required when updating a campaign Integer △
company Company
  • gamevil: Com2uS Holdings
  • com2us: Com2uS
  • gcp: Com2uS Platform
String O
companyIndex Company code (company number registered in AppCenter) Integer O
description Campaign description String O
notice Whether this is an announcement notification (default: true).
• true: Sent as an announcement notification.
Not sent to recipients who have not opted in. If sent at night (21:00–08:00), recipients must also have opted in to nighttime notifications. See Announcement notification behavior.
• false: Sent as an operational app notification, regardless of user consent.
Note: Notifications may not be delivered if blocked at the device or OS level, regardless of whether this field is true or false.
Boolean X
type Send type
  • B: Bulk push
  • T: Targeting push
String O
targetingId Targeting ID. Required for targeting campaigns. Integer △
registrant name Registrant name String X
id Registrant ID String O
reservation localizing Flag that determines whether the schedule is applied according to the user's time zone when sending notifications.
  • true: Send notifications according to the user's local time zone.
  • false: Determine the time zone for sending notifications using gmtOffset.
Boolean O
startDate startDate is the date scheduled notification delivery begins, and endDate is the date it ends.
Push notifications are sent at the specified time (the time field) during this period.
(ISO 8601 format, YYYY-MM-DD)
String O
endDate String O
time Send time (HH:mm) String O
gmtOffset When localizing is false, this field specifies the time zone used for notification delivery. It represents the offset from UTC in seconds and can range from -43200 to 50400. The default is 32400, the Korea Standard Time (KST) offset.
-18000 represents UTC-5 (EST).
32400 represents UTC+9 (KST).
Example:
If startDate is 2025-11-06, time is 17:00, and gmtOffset is -18000, delivery starts at 2025-11-06T17:00-5:00.
Long X
repeat Flag indicating whether to repeat notification delivery during a specified period. Boolean O
weekday Days of the week on which to send notifications when repeating.
  • 1: Monday
  • 2: Tuesday
  • 3: Wednesday
  • 4: Thursday
  • 5: Friday
  • 6: Saturday
  • 7: Sunday
Integer[] X
skip Dates to skip during the repeat period String[] X
distribution enable Whether to enable distributed sending Boolean X
interval Interval between distributed sends Integer X
count Number of notifications per distribution interval Integer X
countries Selected countries (see Country codes) String[] O
game gameindex Game index Integer O
serverIds List of server IDs String[] X
apps[] appindex App index Integer O
appid App ID String O
defaultLanguage Default language (see Language codes) String O
notification {{LANGUAGE}} Message data. See the Message structure and example below. Message X
option badge Push notification badge Integer X
overwrite Whether to enable push overwrite Boolean X
collapseKey Key used when push overwrite is enabled String X
engagement User engagement String X
comment Comment String X
groupKey Group key used to display notifications together on iOS and Android devices. Notification settings configured in the device OS apply by default. See the following documentation for details. String X
android icon Name of the icon image file displayed with the push notification on the user's device. The image must be in /src/main/res/drawable. See Android documentation for supported formats. To display an image hosted on the web, enter its URL instead of a file name. If this field is empty, the app icon is displayed. String X
sound Name of the sound file played when the push notification appears on the user's device. The sound file must be included in the app bundle and placed in /src/main/res/raw. If this field is empty, the system default sound is used. String X
priority Priority of the message sent to Android devices. This FCM setting controls message delivery timing. Values are NORMAL or HIGH; the default is NORMAL. See the Firebase documentation for details.
  • NORMAL = Default priority for data messages. Normal-priority messages are delivered immediately when the device is not in Doze mode. When the device is idle, delivery may be delayed to preserve battery until it exits Doze mode. Choose normal priority for messages that are not time-critical, such as new email notifications, UI synchronization, or background app data synchronization.
  • HIGH = FCM attempts to deliver high-priority messages immediately. If needed, FCM may wake the device and allow limited processing, including limited network access. High-priority messages should generally result in the user interacting with the app or notification.
enum(NORMAL, HIGH) X
ios sound Name of the sound file played when the push notification appears on the user's device. The file must be in the app container's Library/Sounds directory or the app's main bundle. If this field is empty, it is automatically set to "default" and the Apple system default sound is used. String X
    <tr>
        <td class="custom-basic" colspan="2">comment</td>
        <td class="custom-basic">Comment</td>
        <td class="custom-basic">String</td>
        <td class="custom-basic">X</td>
    </tr>
    <tr>
        <td class="custom-basic" colspan="2">groupKey</td>
        <td class="custom-basic">Group key used to display notifications together on iOS and Android devices. Notification settings configured in the device OS apply by default. See the following documentation for details.
            <ul>
                <li><a href="https://developer.apple.com/documentation/usernotifications/unmutablenotificationcontent/1649872-threadidentifier">iOS</a></li>
                <li><a href="https://developer.android.com/develop/ui/views/notifications/group">Android</a></li>
            </ul>
        </td>
        <td class="custom-basic">String</td>
        <td class="custom-basic">X</td>
    </tr>
    <tr>
        <td class="custom-basic" rowspan="3">android</td>
        <td class="custom-basic">icon</td>
        <td class="custom-basic">Name of the icon image file displayed with the push notification on the user's device. The image must be in <em>/src/main/res/drawable</em>. See <a href="https://developer.android.com/guide/topics/resources/drawable-resource">Android documentation</a> for supported formats. To display an image hosted on the web, enter its URL instead of a file name. If this field is empty, the app icon is displayed.</td>
        <td class="custom-basic">String</td>
        <td class="custom-basic">X</td>
    </tr>
    <tr>
        <td class="custom-basic">sound</td>
        <td class="custom-basic">Name of the sound file played when the push notification appears on the user's device. The sound file must be included in the app bundle and placed in <em>/src/main/res/raw</em>. If this field is empty, the system default sound is used.</td>
        <td class="custom-basic">String</td>
        <td class="custom-basic">X</td>
    </tr>
    <tr>
        <td class="custom-basic">priority</td>
        <td>Priority of the message sent to Android devices. This FCM setting controls message delivery timing. Values are NORMAL or HIGH; the default is NORMAL. See the <a href="https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#androidconfig">Firebase documentation</a> for details.
            <ul>
                <li>NORMAL = Default priority for data messages. Normal-priority messages are delivered immediately when the device is not in Doze mode. When the device is idle, delivery may be delayed to preserve battery until it exits Doze mode. Choose normal priority for messages that are not time-critical, such as new email notifications, UI synchronization, or background app data synchronization.</li>
                <li>HIGH = FCM attempts to deliver high-priority messages immediately. If needed, FCM may wake the device and allow limited processing, including limited network access. High-priority messages should generally result in the user interacting with the app or notification.</li>
            </ul>
        </td>
        <td>enum(NORMAL, HIGH)</td>
        <td>X</td>
    </tr>
    <tr>
        <td class="custom-basic">ios</td>
        <td class="custom-basic">sound</td>
        <td class="custom-basic">Name of the sound file played when the push notification appears on the user's device. The file must be in the app container's <em>Library/Sounds</em> directory or the app's main bundle. If this field is empty, it is automatically set to "default" and the <a href="https://developer.apple.com/documentation/usernotifications/unnotificationsound">Apple system default sound</a> is used.</td>
        <td class="custom-basic">String</td>
        <td class="custom-basic">X</td>
    </tr>
</tbody>

お知らせ通知の動作

Announcement notifications are sent only to app users who have opted in to receive them. If an announcement notification is sent between 21:00 and 08:00 the next day, consent to nighttime notifications is also required.

Details about announcement notification behavior are as follows.

  • If a user has not opted in to announcement notifications, messages configured as announcements are not sent.
  • Users can opt in to nighttime notifications only after opting in to announcement notifications.
Warning

Regulations for advertising announcement notifications to users in Korea

When sending announcement notifications to users in Korea, comply with Article 50 of Korea's Network Act because they are treated as advertising notifications. Advertising notification messages must include wording indicating that the message is an advertisement and instructions for opting out.

  • Example advertising notification: (Ad) {message_body} (Opt out: change in settings)
Note

For details about the option field, see each market's guidelines.

メッセージ構造

区分 フィールド名 説明 型 必須
Message android title タイトル String O
message 本文 String O
messageExpanded 本文拡張 String X
imageUrl 画像パス String X
ticker ティッカー String X
summaryText 本文要約 String X
iOS title タイトル String O
message 本文 String O
mediaUrl 画像パス String X

メッセージ例

{
"ko": {
      "android": {
        "messageExpanded": "(광고) TEST(수신거부: 설정에서 변경 가능)",
        "ticker": "gg",
        "title": "(광고)test",
        "message": "(광고) test (수신거부: 설정에서 변경 가능)",
        "summaryText": "",
        "imageUrl": ""
      },
      "ios": {
        "mediaUrl": "",
        "title": "푸시",
        "message": "(광고) TEST (수신거부: 설정에서 변경 가능)"
      }
    }
}

出力結果

Header Content-Type application/json;charset=utf-8
UUID {{UUID}}
Body 成功時、Body は空です

レスポンスステータスコード

キー 値 説明
200 成功 (Body는 비어 있음)
400 Bad Request POST データ不足
JSON 形式エラー
データ内の必須要素が不足しているか無効です
Body の reason メッセージでエラーの追加確認ができます
401 Unauthorized リクエストメッセージの Authorization ヘッダーがないか、値が無効です
認証トークン(API KEY)が登録されていません
該当 API へのアクセス権限がありません
403 Forbidden Authorization ヘッダーの認証スキームが Bearer ではありません(現在 Bearer のみ対応)
404 Not Found リクエスト URL が正しくありません
500 Internal Server Error サーバー内部で問題が発生しました
502 Bad Gateway Push Gateway サーバー過負荷
ネットワークが誤った接続を試行しました
503 Service Unavailable API サーバーまたは認証サーバーが停止しています

サンプルコード

キャンペーン登録

  • 呼び出し
curl -v -L \
-H "Content-Type: application/json"  \
-H "Authorization: Bearer {API KEY}" \
-d '{
    "description": "TEST",
    "status": 1,
    "company": "gcp",
    "companyIndex": 3,
    "type": "B",
    "targetingId": 0,
    "reservation": {
        "localizing": false,
        "startDate": "2025-11-06",
        "endDate": "2025-11-06",
        "time": "17:00:00",
        "gmtOffset": 32400,
        "repeat": false,
        "periodType": "",
        "weekday": [],
        "skip": []
    },
    "game": {
        "gameName": "스탭 바이 스탭",
        "gameindex": 597,
        "serverIds": [],
        "apps": [
            {
                "appindex": 20009,
                "appid": "com.gcp.stepbystep.android.google.global.normal",
                "versions": []
            }
        ],
        "serverAll": true
    },
    "distribution": {
        "enable": false,
        "interval": 0,
        "count": 0
    },
    "defaultLanguage": "ko",
    "option": {
        "badge": 1,
        "engagement": "",
        "overwrite": false,
        "collapseKey": "0",
        "comment": "",
        "groupKey": "",
        "android": {
            "icon": "",
            "sound": "",
            "priority": "high"
        },
        "ios": {
            "sound": ""
        }
    },
    "registrant": {
        "id": "test",
        "name": "테스트"
    },
    "notification": {
        "ko": {
            "android": {
                "title": "TEST",
                "message": "(광고) TEST (수신거부: 설정에서 변경 가능)",
                "messageExpanded": "",
                "ticker": "",
                "summaryText": "",
                "imageUrl": ""
            },
            "ios": {
                "title": "TEST",
                "message": "(광고) TEST (수신거부: 설정에서 변경 가능)",
                "mediaUrl": ""
            }
        }
    },
    "countries": [
        "KR"
    ]
}' \
https://sandbox-notification.qpyou.cn/push/campaigns
  • リクエスト
> POST /push/campaigns HTTP/1.1
> User-Agent: curl/7.29.0
> Host: sandbox-notification.qpyou.cn
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer {API KEY}
> Content-Length: 1314
> Expect: 100-continue
  • レスポンス
< HTTP/1.1 100 Continue
< HTTP/1.1 200 OK
< Content-Length: 1491
< Content-Type: application/json
<: 3d18420b-4cf3-48a8-a3bf-6c9ac6cbe86a
<
{
    "uuid": "3d18420b-4cf3-48a8-a3bf-6c9ac6cbe86a",
    "status": 1,
    "modify": true,
    "id": 10163,
    "type": "B",
    "company": "gcp",
    "companyIndex": 3,
    "description": "TEST",
    "targetingId": 0,
    "reservation": {
        "localizing": false,
        "startDate": "2025-11-06",
        "endDate": "2025-11-06",
        "time": "17:00:00",
        "repeat": false,
        "gmtOffset": 32400
    },
    "distribution": {
        "count": 0,
        "interval": 0,
        "enable": false
    },
    "countries": [
        "KR"
    ],
    "lastEndTime": 1762448400,
    "lastEndTimestamp": 1762416000,
    "tasks": {
        "17:00:00": {
            "startTime": 1762448400,
            "endTime": 1762448400,
            "time": "17:00:00",
            "gmtOffset": 32400,
            "zones": [
                "Asia/Seoul"
            ],
            "startTimestamp": 1762416000,
            "endTimestamp": 1762416000
        }
    },
    "game": {
        "gameindex": 597,
        "gameName": "스탭 바이 스탭",
        "apps": [
            {
                "appid": "com.gcp.stepbystep.android.google.global.normal",
                "appindex": 20009
            }
        ]
    },
    "defaultLanguage": "ko",
    "notification": {
        "ko": {
            "android": {
                "messageExpanded": "",
                "ticker": "",
                "summaryText": "",
                "imageUrl": "",
                "title": "TEST",
                "message": "(광고) TEST (수신거부: 설정에서 변경 가능)"
            },
            "ios": {
                "title": "TEST",
                "message": "(광고) TEST (수신거부: 설정에서 변경 가능)",
                "mediaUrl": ""
            }
        }
    },
    "option": {
        "badge": 1,
        "engagement": "",
        "overwrite": false,
        "collapseKey": "0",
        "comment": "",
        "groupKey": "",
        "android": {
            "icon": "",
            "priority": "high",
            "sound": ""
        },
        "ios": {
            "sound": ""
        }
    },
    "timestamp": {
        "date": "2024-10-21 15:18:57.923",
        "time": 1729491537923
    },
    "registrant": {
        "name": "테스트",
        "id": "test"
    },
    "dryRun": false,
    "debug": false
}

キャンペーン更新

  • 呼び出し
curl -v -L
-H "Content-Type: application/json"  \
-H "Authorization: Bearer {API KEY}" \
-d '{
    "id": 10163,
    "description": "TEST",
    "status": 1,
    "company": "gcp",
    "companyIndex": 3,
    "type": "B",
    "targetingId": 0,
    "reservation": {
        "localizing": false,
        "startDate": "2025-11-06",
        "endDate": "2025-11-06",
        "time": "17:00:00",
        "gmtOffset": -18000,
        "repeat": false,
        "periodType": "",
        "weekday": [],
        "skip": []
    },
    "game": {
        "gameName": "스탭 바이 스탭",
        "gameindex": 597,
        "serverIds": [],
        "apps": [
            {
                "appindex": 20009,
                "appid": "com.gcp.stepbystep.android.google.global.normal",
                "versions": []
            }
        ],
        "serverAll": true
    },
    "distribution": {
        "enable": false,
        "interval": 0,
        "count": 0
    },
    "defaultLanguage": "ko",
    "option": {
        "badge": 1,
        "engagement": "",
        "overwrite": false,
        "collapseKey": "0",
        "comment": "",
        "groupKey": "",
        "android": {
            "icon": "",
            "sound": "",
            "priority": "high"
        },
        "ios": {
            "sound": ""
        }
    },
    "timestamp": {
        "time": 0,
        "date": ""
    },
    "registrant": {
        "id": "test",
        "name": "테스트"
    },
    "notification": {
        "ko": {
            "android": {
                "title": "TEST",
                "message": "(광고) TEST (수신거부: 설정에서 변경 가능)",
                "messageExpanded": "",
                "ticker": "",
                "summaryText": "",
                "imageUrl": ""
            },
            "ios": {
                "title": "TEST",
                "message": "(광고) TEST (수신거부: 설정에서 변경 가능)",
                "mediaUrl": ""
            }
        }
    },
    "countries": [
        "KR"
    ]
}' \
https://sandbox-notification.qpyou.cn/push/campaigns
  • リクエスト
> POST /push/campaigns HTTP/1.1
> User-Agent: curl/7.29.0
> Host: sandbox-notification.qpyou.cn
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer {API KEY}
> Content-Length: 1314
> Expect: 100-continue
  • レスポンス
< HTTP/1.1 100 Continue
< HTTP/1.1 200 OK
< Content-Length: 1491
< Content-Type: application/json
< UUID: 65420989-ab96-4587-b19a-195fe13f9086
<
{
    "uuid": "65420989-ab96-4587-b19a-195fe13f9086",
    "status": 1,
    "id": 10163,
    "type": "B",
    "company": "gcp",
    "companyIndex": 3,
    "description": "TEST",
    "targetingId": 0,
    "reservation": {
        "localizing": false,
        "startDate": "2025-11-06",
        "endDate": "2025-11-06",
        "time": "17:00:00",
        "repeat": false,
        "gmtOffset": -18000
    },
    "distribution": {
        "count": 0,
        "interval": 0,
        "enable": false
    },
    "countries": [
        "KR"
    ],
    "lastEndTime": 1762498800,
    "lastEndTimestamp": 1762466400,
    "tasks": {
        "07:00:00": {
            "startTime": 1762498800,
            "endTime": 1762498800,
            "time": "07:00:00",
            "gmtOffset": -18000,
            "zones": [
                "Asia/Seoul"
            ],
            "startTimestamp": 1762466400,
            "endTimestamp": 1762466400
        }
    },
    "game": {
        "gameindex": 597,
        "gameName": "스탭 바이 스탭",
        "apps": [
            {
                "appid": "com.gcp.stepbystep.android.google.global.normal",
                "appindex": 20009
            }
        ]
    },
    "defaultLanguage": "ko",
    "notification": {
        "ko": {
            "android": {
                "messageExpanded": "",
                "ticker": "",
                "summaryText": "",
                "imageUrl": "",
                "title": "TEST",
                "message": "(광고) TEST (수신거부: 설정에서 변경 가능)"
            },
            "ios": {
                "title": "TEST",
                "message": "(광고) TEST (수신거부: 설정에서 변경 가능)",
                "mediaUrl": ""
            }
        }
    },
    "option": {
        "badge": 1,
        "engagement": "",
        "overwrite": false,
        "collapseKey": "0",
        "comment": "",
        "groupKey": "",
        "android": {
            "icon": "",
            "priority": "high",
            "sound": ""
        },
        "ios": {
            "sound": ""
        }
    },
    "timestamp": {
        "date": "2024-10-21 15:25:45.611",
        "time": 1729491945611
    },
    "registrant": {
        "name": "테스트",
        "id": "test"
    },
    "dryRun": false,
    "debug": false
}

国コード

Continent Country Code Country Code
Africa Angola AO Madagascar MG
Burkina Faso BF Mali ML
Burundi BI Mauritania MR
Benin BJ Mauritius MU
Botswana BW Malawi MW
Democratic Republic of the Congo CD Mozambique MZ
Central African Republic CF Namibia NA
Republic of the Congo CG Niger NE
Ivory Coast CI Nigeria NG
Cameroon CM Reunion RE
Cape Verde CV Rwanda RW
Djibouti DJ Seychelles SC
Algeria DZ Sudan SD
Egypt EG Saint Helena SH
Western Sahara EH Sierra Leone SL
Eritrea ER Senegal SN
Ethiopia ET Somalia SO
Gabon GA South Sudan SS
Ghana GH Sao Tome and Principe ST
Gambia GM Swaziland SZ
Guinea GN Chad TD
Equatorial Guinea GQ French Southern Territories TF
Guinea-Bissau GW Togo TG
British Indian Ocean Territory IO Tunisia TN
Kenya KE Tanzania TZ
Comoros KM Uganda UG
Liberia LR Mayotte YT
Lesotho LS South Africa ZA
Libya LY Zambia ZM
Morocco MA Zimbabwe ZW
Americas Antigua and Barbuda AG Honduras HN
Anguilla AI Haiti HT
Argentina AR Jamaica JM
Aruba AW Saint Kitts and Nevis KN
Barbados BB Cayman Islands KY
Saint Barthélemy BL Saint Lucia LC
Bermuda BM Saint Martin MF
Bolivia BO Martinique MQ
Bonaire, Saint Eustatius and Saba BQ Montserrat MS
Brazil BR Mexico MX
Bahamas BS Nicaragua NI
Belize BZ Panama PA
Canada CA Peru PE
Chile CL Saint Pierre and Miquelon PM
Colombia CO Puerto Rico PR
Costa Rica CR Paraguay PY
Cuba CU Suriname SR
Curaçao CW El Salvador SV
Dominica DM Sint Maarten SX
Dominican Republic DO Turks and Caicos Islands TC
Ecuador EC Trinidad and Tobago TT
Falkland Islands FK United States Minor Outlying Islands UM
Grenada GD United States US
French Guiana GF Uruguay UY
Greenland GL Saint Vincent and the Grenadines VC
Guadeloupe GP Venezuela VE
South Georgia and the South Sandwich Islands GS British Virgin Islands VG
Guatemala GT U.S. Virgin Islands VI
Guyana GY
Asia United Arab Emirates AE Lebanon LB
Afghanistan AF Sri Lanka LK
Armenia AM Myanmar MM
Azerbaijan AZ Mongolia MN
Bangladesh BD Macao MO
Bahrain BH Maldives MV
Brunei BN Malaysia MY
Bhutan BT Nepal NP
China CN Oman OM
Georgia GE Philippines PH
Hong Kong HK Pakistan PK
Indonesia ID Palestinian Territory PS
Israel IL Qatar QA
India IN Saudi Arabia SA
Iraq IQ Singapore SG
Iran IR Syria SY
Jordan JO Thailand TH
Japan JP Tajikistan TJ
Kyrgyzstan KG East Timor TL
Cambodia KH Turkmenistan TM
North Korea KP Turkey TR
South Korea KR Taiwan TW
Kuwait KW Uzbekistan UZ
Kazakhstan KZ Vietnam VN
Laos LA Yemen YE
Europe Andorra AD Iceland IS
Albania AL Italy IT
Austria AT Jersey JE
Aland Islands AX Liechtenstein LI
Bosnia and Herzegovina BA Lithuania LT
Belgium BE Luxembourg LU
Bulgaria BG Latvia LV
Belarus BY Monaco MC
Switzerland CH Moldova MD
Cyprus CY Montenegro ME
Czech Republic CZ Macedonia MK
Germany DE Malta MT
Denmark DK Netherlands NL
Estonia EE Norway NO
Spain ES Poland PL
Finland FI Portugal PT
Faroe Islands FO Romania RO
France FR Serbia RS
United Kingdom GB Russia RU
Guernsey GG Sweden SE
Gibraltar GI Slovenia SI
Greece GR Svalbard and Jan Mayen SJ
Croatia HR Slovakia SK
Hungary HU San Marino SM
Ireland IE Ukraine UA
Isle of Man IM Vatican VA
Oceania American Samoa AS Niue NU
Australia AU New Zealand NZ
Cocos Islands CC French Polynesia PF
Cook Islands CK Papua New Guinea PG
Christmas Island CX Pitcairn PN
Fiji FJ Palau PW
Micronesia FM Solomon Islands SB
Guam GU Tokelau TK
Kiribati KI Tonga TO
Marshall Islands MH Tuvalu TV
Northern Mariana Islands MP Vanuatu VU
New Caledonia NC Wallis and Futuna WF
Norfolk Island NF Samoa WS
Nauru NR
Polar Antarctica AQ

言語コード

言語コード 言語
ko 韓国語
zh-hans 簡体字中国語
zh-hant 繁体字中国語
en 英語
ja 日本語
ar アラビア語
fr フランス語
de ドイツ語
es スペイン語
pt ポルトガル語
th タイ語
it イタリア語
ru ロシア語
id インドネシア語
vi ベトナム語
tr トルコ語
tl フィリピン語