싱글 푸시
연동 준비사항¶
싱글 푸시 API를 연동하려면 인증토큰(API KEY)을 발급받아야 합니다. 토큰을 이미 발급받았다면 추가할 권한만 요청합니다. HIVE Server API > 노티피케이션 > 푸시 v4 > 인증에서 인증토큰 발급과 요청 방법을 확인하세요.
Note
싱글 푸시 API는 비동기(asynchronous) 방식으로 처리되며 API 요청 > 토큰 조회 > 발송 순으로 진행됩니다.
- API 요청 단계에서는 요청 데이터를 검증하고, 요청에 대한 응답 상태 코드를 반환합니다.
- 토큰 조회 단계에서는 요청 데이터에 대한 푸시 토큰을 조회합니다. 토큰이 없는 경우도 있을 수 있습니다.
- 발송 단계에서는 데이터를 각 마켓의 푸시 서버(ADM, APNS, FCM)로 전송합니다. 마켓으로부터 받은 응답으로 처리 결과를 알 수 있습니다.
- 토큰 조회와 발송 단계에서 처리 실패 시 푸시 서버를 호출한 클라이언트로 별도의 응답을 전송하지 않습니다. 발송 후 10분 내로 푸시가 도착하지 않으면 컴투스플랫폼 테크AM실 솔루션아키텍트팀으로 문의바랍니다.
환경별 접근 URL¶
서버 | URL |
---|---|
Production | https://notification.withhive.com |
Sandbox | https://sandbox-notification.withhive.com |
기본 정보 및 요청 변수¶
Method | POST | ||||
---|---|---|---|---|---|
URL | /push/send | ||||
구분 | 필드명 | 설명 | 타입 | 필수여부 | |
Header | Content-Type | application/json;charset=utf-8 | |||
Authorization | bearer {{API KEY}} | ||||
Body | notice | 공지 알림 설정여부 (기본값: false )
true false 수신 동의 항목은 공지 알림과 야간 알림으로 이루어져 있음 | Boolean | O | |
identifiers | 식별자 정보 (최대 100개)identifier 구조와 예제는 아래에서 확인 | identifier[] | O | ||
game | gameid | 게임ID | String | O | |
appids | AppID 목록 식별자에 매핑되는 AppID가 유효하지 않을 경우 미발송 처리 권장사항
| String[] | X | ||
enableLocale | 언어 로케일 적용 여부
true false | Boolean | O | ||
payload | single | enableLocale=false 일 경우 single 필드로 요청 Message 구조는 아래에서 확인 | Message | O | |
defaultLanguage | enableLocale=true 일 경우 기본 언어로 설정 | String | |||
locale {{LANGUAGE}} | enableLocale=true 일 경우 locale 필드로 설정single 필드 Message 정보와 동일 | Message | |||
option | Option 정보는 아래에서 확인 | Option | X | ||
actionInfo | android | ActionPayload 정보는 아래에서 확인 | ActionPayload | X | |
ios | ActionPayload 정보는 아래에서 확인 | ActionPayload | X |
Note
- 원활한 싱글 푸시 수신을 위해서 appids와 identifiers 필드는 단 건의 데이터 입력을 권장합니다.
- 다수의 identifier, 다수의 appid가 요청에 포함하는 경우 조회 조건을 특정할 수 없기 때문에 푸시 발송에 지연이 발생할 수 있습니다.
- identifier 값은 우선순위가 높은 값을 지정하는 것을 권장하고, did 값 만으로 identifier를 구성하는 것은 지양합니다.
- game 필드에 gameid만 지정된 요청은 지양합니다.
- appids 필드에 데이터가 없는 경우 gameid에 포함되는 모든 appid를 대상으로 조회하기 때문에 푸시 발송에 지연이 발생할 수 있습니다.
identifier 구조¶
구분 | 필드명 | 설명 | 타입 | 필수여부 | |
---|---|---|---|---|---|
identifier | identifier | 두 가지 중 하나 이상은 반드시 포함되어야 함 적용 우선순위는 playerId, did 순 | Long | O | |
playerId | |||||
did |
identifier 예제¶
Message 구조¶
구분 | 필드명 | 설명 | 타입 | 필수여부 | |
---|---|---|---|---|---|
Message | android | title | 제목 | String | O |
message | 본문 | String | O | ||
messageExpanded | 본문 확장 | String | O | ||
imageUrl | 이미지 경로 | String | X | ||
ticker | 티커 | String | X | ||
summaryText | 본문 간략히 | String | X | ||
ios | title | 제목 | String | O | |
message | 본문 | String | O | ||
mediaUrl | 이미지 경로 | String | X |
Option 정보¶
구분 | 필드명 | 설명 | 타입 | 필수여부 | |
---|---|---|---|---|---|
Option | badge | 푸시를 수신할 때 앱 아이콘 위에 표시하는 숫자값(기본값: 1) | Integer | X | |
overwrite | Android의 푸시 덮어쓰기 기능 사용 여부(기본값: false) | Boolean | X | ||
collapseKey | 푸시 덮어쓰기 기능을 사용할 때 키값(숫자의 문자열 형식: "123") | 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 |
ActionPayload¶
ActionPayload는 싱글 푸시 API의 부가 기능인 푸시 액션 버튼을 사용 시 전달하는 데이터 포맷입니다.
푸시 액션 버튼은 SDK에서 사용할 수 있는 노티피케이션 기능 중 하나로 푸시 알림을 길게 누르면 표시되는 시스템 버튼입니다.
푸시 액션 버튼에 대한 상세한 내용은 아래 가이드를 참고세요.
Warning
푸시 액션 버튼을 사용 시 유의 사항은 아래와 같습니다.
- SDK Android & iOS 4.25.5.0 이상에서만 사용할 수 있습니다.
identifiers
필드에 최대 1개의identifer
만 유효하며,playerId
가 필수로 포함되어야 합니다.- 푸시 액션 버튼으로 호출된 URL에 대한 보안 검증 절차에 대한 책임은 개발사에게 있습니다.
ActionPayload 데이터 구조¶
싱글 푸시 API 요청 시, ActionPayload에 포함되는 데이터는 아래와 같습니다.
필드명 | 설명 | 타입 | 필수 여부 |
---|---|---|---|
category | 푸시 액션 버튼 세트의 카테고리식별자 로 액션 버튼 세트를 식별하는데 사용됩니다. Hive SDK는 디폴트 푸시 액션 버튼 세트를 제공합니다.디폴드 푸시 액션 버튼 세트 확인하기 카테고리에 대한 자세한 내용은 Apple 개발자 사이트 내용을 참고하세요. iOS: 필수, Android: 생략 가능 및 무시 | String | O iOS X Android |
actions | 푸시 알림에 표시할 시스템 버튼 목록 (Android: 최대 3개 / iOS는 푸시 액션 버튼 세트 구성에 따름) Action 정보는 아래에서 확인 | Action [] (Action의 배열) | O |
Action¶
Action은 ActionPayload를 구성하는 각각의 시스템 버튼과 관련된 데이터입니다. Action에 포함되는 본문 파라미터는 아래와 같습니다.
필드명 | 설명 | 타입 | 필수 여부 |
---|---|---|---|
actionId | 푸시 액션 버튼 세트의 액션식별자 로 푸시 알림에 표시되는 시스템 버튼을 식별하기 위한 식별자 입니다.액션식별자에 대한 자세한 내용은 Apple 개발자 가이드를 참고하세요. iOS: 필수, Android: 생략 가능 및 무시됨 | String | O iOS X Android |
titles | 버튼 다국어 텍스트로 요청 변수 중 enableLocale 의 기준에 따라 적용되며 유효한 언어 코드를 찾지 못하는 경우 default 로 적용됩니다. key = 언어코드로 default key는 필수로 포함되어합니다, value = 버튼명입력한 버튼명이 길 경우, 일부 텍스트가 말줄임표로 표시될 수 있습니다. 적절한 길이로 설정해 주세요. Android 전용 | Map | O Android X iOS |
actionType | 동작 유형 (CURL , CLOSE ) 기본값:CLOSE CURL 은 action 필드의 값으로 URL 호출을 실행합니다.CLOSE 는 푸시를 닫습니다. | enum(CURL, CLOSE) | O |
action | 동작 유형에 따른 실행할 액션 예: https://.... actionType 이 CURL 인 경우에는 필수입니다. | String | X |
출력 결과 > 응답 파라미터 구조¶
구분 | 필드명 | 설명 |
---|---|---|
Header | Content-Type | application/json;charset=utf-8 |
UUID | {{UUID}} | |
Body | - | 성공일 경우 Body는 비어있음 |
응답 상태 코드¶
키 | 값 | 설명 |
---|---|---|
200 | 성공 | (Body는 비어있음) |
400 | Bad Request | POST 데이터 누락JSON 포맷 오류데이터 내 필수 요소가 누락되었거나 유효하지 않음 |
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 서버 또는 인증 서버 다운 상태 |
예제 코드¶
- 호출 ("enableLocale":false)
POST /push/send HTTP/1.1
Host: sandbox-notification.qpyou.cn
Content-Type: application/json
Authorization: Bearer {API KEY}
Content-Length: [자동 계산됨]
{
"notice": false,
"identifiers": [
{
"playerId": 200001358,
"did": 300010915
}
],
"game": {
"gameid": "com.com2us.hivesdk",
"appids": [
"com.com2us.hivesdk.normal.freefull.google.global.android.common",
"com.com2us.hivesdk.normal.freefull.apple.global.ios.universal"
]
},
"enableLocale": false,
"payload": {
"single": {
"android": {
"title": "android title",
"message": "android message",
"messageExpanded": "",
"imageUrl": "",
"ticker": "",
"summaryText": ""
},
"ios": {
"title": "ios title",
"message": "ios message",
"mediaUrl": ""
}
},
"option": {
"badge": "1",
"overwrite": false,
"collapseKey": "",
"engagement": "",
"groupKey": "",
"android": {
"icon": "",
"sound": "",
"priority": "normal"
},
"ios": {
"sound": ""
}
}
},
"actionInfo": {
"android": {
"actions": [
{
"titles": {
"default": "OK"
},
"actionType": "CURL",
"action": "https://examplecurl.com"
},
{
"titles": {
"default": "Cancel"
},
"actionType": "CLOSE",
"action": ""
}
]
},
"ios": {
"category": "CONFIRM_CATEGORY",
"actions": [
{
"actionId": "CONFIRM_ID",
"actionType": "CURL",
"action": "https://examplecurl.com"
},
{
"actionId": "CLOSE_ID",
"actionType": "CLOSE",
"action": ""
}
]
}
}
}
- 호출 ("enableLocale":true)
POST /push/send HTTP/1.1 Host: sandbox-notification.qpyou.cn Content-Type: application/json Authorization: Bearer {API KEY} Content-Length: [자동 계산됨] { "notice": false, "identifiers": [ { "playerId": 200001358, "did": 300010915 } ], "game": { "gameid": "com.com2us.hivesdk", "appids": [ "com.com2us.hivesdk.normal.freefull.google.global.android.common", "com.com2us.hivesdk.normal.freefull.apple.global.ios.universal" ] }, "enableLocale": true, "payload": { "defaultLanguage": "en", "locale": { "ko": { "android": { "title": "테스트_한국어 제목", "message": "테스트_한국어 메세지" }, "ios": { "title": "테스트_한국어 제목", "message": "테스트_한국어 메세지" } }, "en": { "android": { "title": "test_English title", "message": "test_English message" }, "ios": { "title": "test_English title", "message": "test_English message" } } }, "option": { "badge": 1, "overwrite": true, "collapseKey": "99", "groupKey": "", "android": { "icon": "GoogleIcon", "sound": "GoogleSound", "priority": "normal" }, "ios": { "sound": "AppleSound" } } }, "actionInfo": { "android": { "actions": [ { "titles": { "default": "OK", "en": "OK", "ko": "확인" }, "actionType": "CURL", "action": "https://examplecurl.com" }, { "titles": { "default": "Cancel", "en": "Cancel", "ko": "취소" }, "actionType": "CLOSE", "action": "" } ] }, "ios": { "category": "CONFIRM_CATEGORY", "actions": [ { "actionId": "CONFIRM_ID", "actionType": "CURL", "action": "https://examplecurl.com" }, { "actionId": "CLOSE_ID", "actionType": "CLOSE", "action": "" } ] } } }
Note
서버에서 로그 기록을 즉시 확인할 수 있도록 호출 데이터는 개행 문자 없이 한 줄로 발송 하기를 권장합니다.
- 응답