跳转至

活动注册

`## 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>

公告通知行为

公告通知仅会发送给已同意接收公告通知的应用用户。如果公告通知的发送时间位于 21:00 至次日 08:00，还需要用户额外同意接收夜间通知。

公告通知行为的详细信息如下。

  • 如果用户未同意接收公告通知，则所有设置为公告的消息都不会发送。
  • 用户只有在同意接收公告通知后，才能同意接收夜间通知。
Warning

面向韩国用户的广告性公告通知规定

向韩国用户发送公告通知时，由于其会被视为广告性通知，因此必须遵守韩国《信息通信网法》第 50 条。广告性通知消息必须包含表示“广告”的文案以及拒收说明。

  • 广告性通知示例：(Ad) {message_body}（拒收：可在设置中更改）
Note

有关 option 字段的详细信息，请参考各应用市场指南。

消息结构

区分 字段名 说明 类型 是否必填
Message android title 标题 String O
message 正文 String O
messageExpanded 正文扩展 String X
imageUrl 图片路径 String X
ticker 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 推送网关服务器过载
网络尝试了错误连接
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 菲律宾语