싱글 푸시

연동 준비사항¶

싱글 푸시 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` 게임 알림으로 발송 수신 동의 여부에 관계없이 발송 수신 동의 항목은 공지 알림과 야간 알림으로 이루어져 있음 대상자가 공지 알림 수신에 동의하지 않으면 공지로 설정된 모든 알림 메시지가 발송되지 않음 야간 알림 수신 동의는 공지 알림 수신에 동의한 경우에만 적용되므로 동의하지 않으면 공지로 설정된 모든 알림 메시지가 야간에 발송되지 않음. 야간은 오후 9시부터 다음날 오전 8시 사이를 의미	Boolean	O
	identifiers		식별자 정보 (최대 100개)identifier 구조와 예제는 아래에서 확인	identifier[]	O
	game	gameid	게임ID	String	O
		appids	AppID 목록 식별자에 매핑되는 AppID가 유효하지 않을 경우 미발송 처리 권장사항 기기 기반 식별자(did)일 경우: 매핑되는 AppID를 추가 계정 기반 식별자(playerld, vid, uid)일 경우: 매핑되는 모든 AppID 목록을 추가 다양한 식별자가 존재할 경우: Identifier 구조에서 우선순위 확인	String[]	X
	enableLocale		언어 로케일 적용 여부 `true` 푸시 발송 대상자가 설정한 언어와 동일한 언어로 메시지를 전송. 토큰 정보와 함께 저장된 언어 코드를 기준으로 함 토큰 저장 시 언어를 결정하는 기준 1순위: 게임 언어 2순위: 기기 언어 (전달된 게임 언어가 없을 경우) `false` 언어 로케일은 무시하고 payload의 single값을 통해서만 발송	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를 대상으로 조회하기 때문에 푸시 발송에 지연이 발생할 수 있습니다.

identifier 구조¶

구분	필드명		설명	타입	필수여부
identifier	identifier	playerId	4가지 중 하나 이상은 반드시 포함되어야 함 적용 우선순위는 playerId, vid, uid, did 순	Long	O
		vid
		uid
		did

identifier 예제¶

[
  {
    "playerId":51234,
    "vid":11232,
    "did":1234
  }
]

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에 설정된 알림 옵션이 기본 적용됩니다. 옵션에 관한 자세한 내용은 아래 문서를 참고하세요. iOS Android	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 가이드를 참고하세요. NORMAL = 데이터 메시지의 기본 우선순위입니다. 보통 우선순위 메시지는 기기가 절전 모드가 아닐 때 즉시 전송됩니다. 기기가 잠자기 모드일 때는 기기가 잠자기 모드를 종료할 때까지 배터리를 절약하기 위해 전송이 지연될 수 있습니다. 새로운 이메일 알림, UI 동기화 유지, 백그라운드 앱 데이터 동기화와 같이 시간이 크게 중요하지 않은 메시지의 경우 보통 전송 우선순위를 선택하세요. HIGH = FCM이 높은 우선순위 메시지를 즉시 전송하려고 시도하며 필요한 경우 FCM에서 기기의 절전 모드를 해제하고 매우 제한된 네트워크 액세스를 포함하여 제한된 일부 처리 작업을 실행할 수 있습니다. 높은 우선순위 메시지는 대개 사용자가 앱 또는 알림과 상호작용하는 과정을 포함합니다.	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":""}},"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": "테스트_한국어 메세지"
                }
            },
            "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"
            }
        }
    }
}

```

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

응답

< HTTP/1.1 200 OK
< content-length: 0
< Content-Type: application/json
< UUID: 3bc6b414-e2df-40d6-8006-9d2308a6edf9