캠페인 등록
연동 준비사항¶
캠페인 등록 API를 연동하려면 인증토큰(API KEY)을 발급받아야 합니다. 토큰을 이미 발급받았다면 추가할 권한만 요청합니다. HIVE Server API > 노티피케이션 > 푸시 v4 > 인증에서 인증토큰 발급과 요청 방법을 확인하세요.
캠페인 등록 API¶
기본 정보 및 요청 변수¶
Method | POST | ||||||
URL | /push/campaigns | ||||||
구분 | 필드명 | 설명 | 타입 | 필수 여부 | |||
---|---|---|---|---|---|---|---|
sound | Header | Content-Type | application/json;charset=utf-8 | ||||
Authorization | bearer {{API KEY}} | - | |||||
Body | id | 캠페인 수정 시 필수 입력 사항 | Integer | △ | |||
status | 캠페인 수정 시 필수 입력 사항 | Integer | △ | ||||
company | 회사 구분
| String | O | ||||
companyIndex | 회사 코드 (앱 센터에 등록된 회사 번호) | Integer | O | ||||
description | 캠페인 설명 | String | O | ||||
notice | 공지 푸시 여부 | Boolean | X | ||||
type | 발송 구분
| String | O | ||||
targetingId | 타게팅 ID 타게팅 캠페인일 경우 필수 입력 사항 | Integer | △ | ||||
registrant | name | 등록자 이름 | String | X | |||
id | 등록자 id | String | O | ||||
reservation | localizing | 현지 시간 고려 여부 (일괄 발송 사용/미사용) | Boolean | O | |||
startDate | 반복 발송 기간 (YYYY-MM-DD) | String | O | ||||
endDate | String | O | |||||
time | 발송 시간 (HH:mm) | String | O | ||||
repeat | 반복 발송 여부 | Boolean | O | ||||
weekday | 주말을 제외한 반복 발송 요일 | Integer[] | X | ||||
skip | 반복 발송 기간에 발송을 건너뛸 날짜 | String[] | X | ||||
distribution | enable | 분산 발송 여부 | Boolean | X | |||
interval | 분산 발송 간격 | Integer | X | ||||
count | 분산 발송 갯수 | Integer | X | ||||
continents | 선택된 대륙별 국가 정보 목록 (국가코드 참고) CampaignContinent 구조와 예제는 아래에서 확인 | CampaignContinent[] | O | ||||
countries | 선택된 국가 정보 (국가코드 참고) | String[] | O | ||||
game | gameindex | 게임 인덱스 | Integer | O | |||
serverIds | 서버 ID 목록 | String[] | X | ||||
apps[] | appindex | 앱 인덱스 | Integer | O | |||
appid | 앱 아이디 | String | O | ||||
defaultLanguage | 기본 언어값 (언어코드 참고) | String | O | ||||
notification | {{LANGUAGE}} | 메시지 정보 Message 구조와 예제는 아래에서 확인 | Message | X | |||
option | badge | 푸시 알림 뱃지 | Integer | X | |||
overwrite | 푸시 덮어쓰기 기능 사용여부 | Boolean | X | ||||
collapseKey | 푸시 덮어쓰기 기능을 사용할 때 키값 | String | X | ||||
engagement | 유저 인게이지먼트 | String | X | ||||
comment | 문구 | String | X | ||||
groupKey | iOS와 Android OS 사용 기기에서 알림 수신 시, 알림을 같은 그룹끼리 묶어 노출하기 위한 그룹 키 값입니다. 기기 OS에 설정된 알림 옵션이 기본 적용됩니다. 옵션에 관한 자세한 내용은 아래 문서를 참고하세요. | String | X | ||||
android | icon | 유저 기기에 푸시 알림이 뜰 때 노출되는 아이콘 이미지 파일명입니다. 이미지 파일은 /src/main/res/drawable에 존재해야 합니다. 지원하는 이미지 파일 형식은 다음을 확인하세요. 웹에 있는 이미지를 노출하고 싶다면 이미지 파일명 대신 이미지 URL을 이 필드에 입력하세요. 이 필드가 비어있으면 앱 아이콘 이미지를 노출합니다. | String | X | |||
sound | 유저 기기에 푸시 알림이 뜰 때 재생할 알림 음원 파일명입니다. 앱 번들에 포함된 음원 파일을 지정할 수 있으며 음원 파일은 /src/main/res/raw에 존재해야 합니다. 이 필드가 비어있으면 시스템 기본 음원을 사용합니다. | String | X | ||||
priority | Android 기기로 전송할 메시지의 우선순위입니다. 이 우선순위는 메시지 전송 시기를 제어하는 FCM 개념입니다. NORMAL 또는 HIGH 값을 가질 수 있으며, 기본값은 NORMAL 입니다. 자세한 내용은 Firebase 가이드를 참고하세요.
| enum(NORMAL, HIGH) | X | ||||
ios | sound | 유저 기기에 푸시 알림이 뜰 때 재생할 알림 음원 파일명입니다. 음원 파일은 앱 컨테이너의 Library/Sounds 또는 앱 메인 번들에 존재해야 합니다. 이 필드가 비어있으면 "default"로 자동 설정되며 유저 애플 기기 시스템 기본 음원을 사용합니다. | String | X |
Note
option
필드에 관한 자세한 정보는 각 마켓의 가이드 라인을 참고하세요. (Facebook의 경우 option 필드가 적용되지 않습니다.)
- iOS: Generating a remote notification
- Android: FirebaseNotification
CampaignContinent 구조¶
구분 | 필드명 | 설명 | 타입 | 필수여부 |
---|---|---|---|---|
CampaignContinent | continent | 대륙 구분 | String | O |
countries | 대륙에 속한 국가 코드 | String[] | O |
CampaignContinent 예제¶
[
{
"name": "Africa",
"countries": [
"Algeria",
"Angola",
"Benin",
"Sudan",
"Swaziland",
"Tanzania",
"Togo",
"Tunisia",
"Zambia",
"Zimbabwe"
]
}
]
Message 구조¶
구분 | 필드명 | 설명 | 타입 | 필수여부 | |
---|---|---|---|---|---|
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 | title | 제목 (1~30자 이내) | String | O |
body | 본문 (10~180자 이내) | String | O | ||
media | 이미지 URL | String | O |
Message 예제¶
{
"ko": {
"android": {
"messageExpanded": "(광고) TEST(수신거부: 설정에서 변경 가능)",
"ticker": "gg",
"title": "(광고)test",
"message": "(광고) test (수신거부: 설정에서 변경 가능)",
"summaryText": "",
"imageUrl": ""
},
"ios": {
"mediaUrl": "",
"title": "푸시",
"message": "(광고) TEST (수신거부: 설정에서 변경 가능)"
},
"facebook": {
"title" : "Title",
"body" : "Push Message Body",
"media" : "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"
}
}
}
출력 결과¶
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","repeat":false,"periodType":"","weekday":[],"skip":[]},"game":{"gameName":"스탭 바이 스탭","gameindex":592,"serverIds":[],"apps":[{"appindex":20002,"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":"soollung","name":"박기찬"},"notification":{"ko":{"android":{"title":"TEST","message":"(광고) TEST (수신거부: 설정에서 변경 가능)","messageExpanded":"","ticker":"","summaryText":"","imageUrl":""},"ios":{"title":"TEST","message":"(광고) TEST (수신거부: 설정에서 변경 가능)","mediaUrl":""},"facebook":{"title":"TEST", "body":"TEST MESSAGE BODY", "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"}}},"countries":["KR"],"continents":[{"name":"Africa","countries":[]},{"name":"Americas","countries":[]},{"name":"Asia","countries":["South Korea"]},{"name":"Europe","countries":[]},{"name":"Oceania","countries":[]},{"name":"Polar","countries":[]}]}' \
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": 532,
"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
},
"distribution": {
"count": 0,
"interval": 0,
"enable": false
},
"continents": [
{
"name": "Africa",
"countries": []
},
{
"name": "Americas",
"countries": []
},
{
"name": "Asia",
"countries": [
"South Korea"
]
},
{
"name": "Europe",
"countries": []
},
{
"name": "Oceania",
"countries": []
},
{
"name": "Polar",
"countries": []
}
],
"countries": [
"KR"
],
"lastEndTime": 1762448400,
"tasks": {
"17:00:00": {
"startTime": 1762448400,
"endTime": 1762448400,
"time": "17:00:00",
"gmtOffset": 32400,
"zones": [
"Asia/Seoul"
]
}
},
"game": {
"gameindex": 592,
"gameName": "스탭 바이 스탭",
"apps": [
{
"appid": "com.gcp.stepbystep.android.google.global.normal",
"appindex": 20002
}
]
},
"defaultLanguage": "ko",
"notification": {
"ko": {
"android": {
"messageExpanded": "",
"ticker": "",
"summaryText": "",
"imageUrl": "",
"title": "TEST",
"message": "(광고) TEST (수신거부: 설정에서 변경 가능)"
},
"ios": {
"title": "TEST",
"message": "(광고) TEST (수신거부: 설정에서 변경 가능)",
"mediaUrl": ""
},
"facebook": {
"media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg",
"title": "TEST",
"body": "TEST MESSAGE BODY"
}
}
},
"option": {
"badge": 1,
"engagement": "",
"overwrite": false,
"collapseKey": "0",
"comment": "",
"groupKey": "",
"android": {
"icon": "",
"sound": "",
"priority": "high"
},
"ios": {
"sound": ""
}
},
"timestamp": {
"date": "2023-05-22 15:19:24.726",
"time": 1684736364726
},
"registrant": {
"name": "박기찬",
"id": "soollung"
},
"dryRun": false,
"debug": false
}
캠페인 수정¶
- 호출
curl -v -L
-H "Content-Type: application/json" \
-H "Authorization: Bearer {API KEY}" \
-d '{"id":475,"description":"TEST 475","status":1,"company":"gcp","companyIndex" : 3,"type":"B","targetingId":0,"reservation":{"localizing":false,"startDate":"2020-11-06","endDate":"2020-11-06","time":"17:00:00","repeat":false,"periodType":"","weekday":[],"skip":[]},"game":{"gameName":"스탭 바이 스탭","gameindex":592,"serverIds":[],"apps":[{"appindex":20002,"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":"","android":{"icon":"","sound":"","priority":"high"},"ios":{"sound":""}, "groupKey":"test"},"timestamp":{"time":0,"date":""},"registrant":{"id":"soollung","name":"박기찬"},"notification":{"ko":{"android":{"title":"TEST","message":"(광고) TEST (수신거부: 설정에서 변경 가능)","messageExpanded":"","ticker":"","summaryText":"","imageUrl":""},"ios":{"title":"TEST","message":"(광고) TEST (수신거부: 설정에서 변경 가능)","mediaUrl":""},"facebook":{"title":"TEST", "body":"TEST MESSAGE BODY", "media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"}}},"countries":["KR"],"continents":[{"name":"Africa","countries":[]},{"name":"Americas","countries":[]},{"name":"Asia","countries":["South Korea"]},{"name":"Europe","countries":[]},{"name":"Oceania","countries":[]},{"name":"Polar","countries":[]}]}' \
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": 475,
"type": "B",
"company": "gcp",
"companyIndex": 3,
"description": "TEST475",
"targetingId": 0,
"reservation": {
"localizing": false,
"startDate": "2020-11-06",
"endDate": "2020-11-06",
"time": "17:00:00",
"repeat": false
},
"distribution": {
"count": 0,
"interval": 0,
"enable": false
},
"continents": [{
"name": "Africa",
"countries": []
}, {
"name": "Americas",
"countries": []
}, {
"name": "Asia",
"countries": ["South Korea"]
}, {
"name": "Europe",
"countries": []
}, {
"name": "Oceania",
"countries": []
}, {
"name": "Polar",
"countries": []
}],
"countries": ["KR"],
"lastEndTime": 1604682000,
"tasks": {
"17:00:00": {
"startTime": 1604682000,
"endTime": 1604682000,
"time": "17:00:00",
"gmtOffset": 32400,
"zones": ["Asia/Seoul"]
}
},
"game": {
"gameindex": 592,
"gameName": "스탭바이스탭",
"apps": [{
"appid": "com.gcp.stepbystep.android.google.global.normal",
"appindex": 20002
}]
},
"defaultLanguage": "ko",
"notification": {
"ko": {
"android": {
"title": "TEST",
"message": "(광고) TEST (수신거부: 설정에서 변경 가능)",
"messageExpanded": "",
"ticker": "",
"summaryText": "",
"imageUrl": ""
},
"ios": {
"title": "TEST",
"message": "(광고) TEST (수신거부: 설정에서 변경 가능)",
"mediaUrl": ""
},
"facebook": {
"title": "TEST",
"body": "TEST MESSAGE BODY",
"media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"
}
}
},
"option": {
"badge": 1,
"engagement": "",
"overwrite": false,
"collapseKey": "0",
"comment": "",
"android": {
"icon": "",
"sound": "",
"priority": "high"
},
"ios": {
"sound": ""
},
"groupKey": "test"
},
"timestamp": {
"date": "2020-03-23 11:03:43.094",
"time": 1584929023094
},
"registrant": {
"name": "박기찬",
"id": "soollung"
},
"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 | 터키어 |