跳轉至

活动注册

`## 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 菲律賓語