싱글 푸시
연동 준비사항¶
싱글 푸시 API를 연동하려면 인증토큰(API KEY)을 발급받아야 합니다. 토큰을 이미 발급받았다면 추가할 권한만 요청합니다. HIVE Server API > 노티피케이션 > 푸시 v4 > 인증에서 인증토큰 발급과 요청 방법을 확인하세요.
Note
싱글 푸시 API는 비동기(asynchronous) 방식으로 처리되며 API 요청 > 토큰 조회 > 발송 순으로 진행됩니다.
- API 요청 단계에서는 요청 데이터를 검증하고, 요청에 대한 응답 상태 코드를 반환합니다.
- 토큰 조회 단계에서는 요청 데이터에 대한 푸사 토큰을 조회합니다. 토큰이 없는 경우도 있을 수 있습니다.
- 발송 단계에서는 데이터를 각 마켓의 푸시 서버(ADM, APNS, FCM, Facebook)로 전송합니다. 마켓으로부터 받은 응답으로 처리 결과를 알 수 있습니다.
- 토큰 조회와 발송 단계에서 처리 실패 시 푸시 서버를 호출한 클라이언트로 별도의 응답을 전송하지 않습니다. 발송 후 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 |
Note
- 원활한 싱글 푸시 수신을 위해서 appids와 identifiers 필드는 단 건의 데이터 입력을 권장합니다.
- 다수의 identifier, 다수의 appid가 요청에 포함하는 경우 조회 조건을 특정할 수 없기 때문에 푸시 발송에 지연이 발생할 수 있습니다.
- identifier 값은 우선순위가 높은 값을 지정하는 것을 권장하고, did 값 만으로 identifier를 구성하는 것은 지양합니다.
- game 필드에 gameid만 지정된 요청은 지양합니다.
- appids 필드에 데이터가 없는 경우 gameid에 포함되는 모든 appid를 대상으로 조회하기 때문에 푸시 발송에 지연이 발생할 수 있습니다.
- Facebook의 경우 option 필드가 적용되지 않습니다.
identifier 구조¶
구분 | 필드명 | 설명 | 타입 | 필수여부 | |
---|---|---|---|---|---|
identifier | identifier | playerId | 4가지 중 하나 이상은 반드시 포함되어야 함 적용 우선순위는 playerId, vid, uid, did 순 | Long | O |
vid | |||||
uid | |||||
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 | ||
title | 제목 (1~30자 이내) | String | O | ||
body | 본문 (10~180자 이내) | String | O | ||
media | 이미지 URL | String | O |
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 |
출력 결과¶
구분 | 필드명 | 설명 |
---|---|---|
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)
```curl
curl -L -v
> -d '{"notice":false,"identifiers":[{"vid":19239,"did":300010915}],"game":{"gameid":"com.com2us.hivesdk","appids":["com.com2us.hivesdk.normal.freefull.google.global.android.common"]},"enableLocale":false,"payload":{"single":{"android":{"title":"TEST","message":"TEST","messageExpanded":"","imageUrl":"","ticker":"","summaryText":""},"ios":{"title":"","message":"","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","overwrite":false,"collapseKey":"","engagement":"","groupKey": "", "android":{"icon":"","sound":"", "priority": "normal"},"ios":{"sound":""}}}}'
> -H "Content-Type: application/json"
> -H "Authorization: Bearer {API KEY}"
> https://sandbox-notification.qpyou.cn/push/send
```
+ 호출 ("enableLocale":true)
```java
{
"notice": false,
"identifiers": [
{
"playerId": 30000028045
}
],
"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": "테스트_한국어 메세지"
},
"facebook": {
"title": "테스트_한국어 제목",
"body": "테스트_한국어 메시지",
"media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"
}
},
"en": {
"android": {
"title": "test_English title",
"message": "test_English message"
},
"ios": {
"title": "test_English title",
"message": "test_English message"
},
"facebook": {
"title": "test_English title",
"body": "test_English message",
"media": "https://image.newdaily.co.kr/site/data/img/2022/05/13/2022051300019_0.jpg"
}
}
},
"option": {
"badge": 1,
"overwrite": true,
"collapseKey": "99",
"groupKey: "",
"android": {
"icon": "GoogleIcon",
"sound": "GoogleSound",
"priority": "normal"
},
"ios": {
"sound": "AppleSound"
}
}
}
}
```
Note
서버에서 로그 기록을 즉시 확인할 수 있도록 호출 데이터는 개행 문자 없이 한 줄로 발송 하기를 권장합니다.
* 요청
> POST /push/send HTTP/1.1
> User-Agent: curl/7.29.0
> Host: sandbox-notification.qpyou.cn
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NDE1NzMyOTcsImp0aSI6ImFkbWluaXN0cmF0b3IifQ.23nG9RnbuOwnMbRSebBi2i-Qt_fOfqU_vUKUZ2JJlWU
> Content-Length: 502
- 응답