개요
- 이 문서는 단일 푸시(Single Push)를 보내기 위한 API에 대한 설명이 포함되어 있다.
- 큐잉 푸시는 게임 서버에서 Hive의 vid 나 did를 이용하여 게임 유저에게 즉각 푸시를 보낼 수 있도록 제공된
기능이다.
API 기본 구조
- HTTP POST 방식을 이용하여 통신한다.
- 송수신 파라미터 및 리턴 값은 모두 JSON 형식으로 구성된다.
동작 원리
- API로 POST된 데이터는 Message Queue Server로 전송되고, Worker Process (Sender)가 이 데이터를
받아 처리한다.
URL
| 상용 (Production) | https://push.qpyou.cn/qsp/gateway.php |
|---|---|
| 샌드박스 (Sandbox) | https://sandbox-push.qpyou.cn/qsp/gateway.php |
| 스테이징 (Staging) | https://test-push.qpyou.cn/qsp/gateway.php |
입력 파라미터 (Input Parameters)
프로토콜 (Protocol)
| Field | Type | Description | APNS | GCM | etc |
|---|---|---|---|---|---|
| api | String | 플랫폼 구분용 필드 – APNS: apns – GCM: gcm – ADM: adm – |
● | ● | |
| appid | String | 푸시 발송할 게임의 AppID | ● | ● | |
| did | Int Array | 푸시 발송할 단말의 did(Device ID) | ● | ● | |
| vid | Int Array | 푸시 발송할 단말의 vid(Virtual Account ID) ※vid: Hive에서 발급하는 사용자 계정의 고유 ID |
● | ● | |
| title | String | 푸시 제목 (GCM에서만 사용 가능하며, HTML tag 지원) |
● | 필수입력사항 (GCM) |
|
| msg | String | 푸시 메세지 (GCM, ADM에서는 HTML tag 지원) |
● | ● | 필수입력사항 |
| msg_ios | String | 푸시 메세지 (VID 발송시 사용되는 iOS용 메세지) |
● | ||
| bigmsg | String | 푸시 장문 메세지 (GCM에서만 사용 가능하며, HTML tag 지원) |
● | ||
| ticker | String | 푸시 티커 (GCM에서만 사용 가능) | ● | ||
| badge | Int | 푸시 수신 시, 단말의 앱 아이콘에 표시되는 숫자 | ● | ● | |
| sound | String | 푸시 수신음 | ● | ● | |
| sound_ios | String | 푸시 수신음 (vid 발송 시 사용되는 iOS 푸시 수신음) |
● | ||
| icon | String | 푸시 아이콘 | ● | ||
| vib | Int | 진동 사용 여부 (GCM에서만 사용 가능 / 진동없음: 0, 진동: 1 / 기본값 1) |
● | ||
| active | String | 푸시 터치 시의 동작 설정 (GCM에서만 사용 가능 / 앱으로 이동: app, 웹 사이트로 이동: web:URL / 기본값 app) |
● | ||
| action | String | 앱으로 전달할 커스튬 데이타 | ● | ● | 신규 추가 파라미터 |
데이터 구성 예시 (Example)
- DID 발송
|
1 2 3 4 5 6 7 |
{ "api":"gcm", "appid":"com.com2us.mi.pushtest", "did":[123456789, 40018293], "msg":"단문메세지를 입력하세요", "bigmsg":"장문메세지를 입력하세요, GCM,ADM 전용!" } |
- VID 발송
|
1 2 3 4 5 6 7 |
{ "vid":[123, 429], "title":"PLAY", "msg":"Android PLAY!!!", "msg_ios":"iOS PLAY!!!", "bigmsg":"GCM, ADM Only!!!" } |
출력 파라미터 (Output Parameters)
| Field | Description | |||
|---|---|---|---|---|
| errno | 에러 코드 0: Success (성공) 1: Transmission error (잘못된 요청, 필수요소 누락) 2: Function error (내부 실행 오류, 관리자에게 문의) 9: Server error (서버 오류, 관리자에게 문의) |
|||
| error | 에러 메세지 | |||
| id | 푸시 아이디, 싱글푸시 결과를 추적하는데 사용 | |||
| date | 싱글 푸시 요청을 보낸 연월(yyyymm) | |||
푸시 데이터 사용 가이드
Android
수신 데이터 파싱을 지원한다.
Hive SDK v1.10.0 미만 버전을 사용하고 있는 게임 중 커스튬 데이타를 사용하기 위한 게임에 대해서 가이드를 적용하면 된다.
해당 기능은 Hive SDK v1.10.0 부터 적용된 Hive 유저 인게이지먼트에 포함되어 있다.
notification, bar, popup을 통해서 앱 실행시, LauncherActivity의 intent에 push data를 담아 실행
파싱 코드 예제
AndroidManifest.xml에 정의된 LauncherActivity 혹은 상속(extends)한 Activity의 onCreate()에서 아래와 같은 방법으로 데이터 파싱이 가능하다.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
< activity ... < intent-filter > < action android:name = "android.intent.action.MAIN" / > < category android:name="android.intent.category.LAUNCHER" / > < / intent-filter > < / activity > /** Called when the activity is first created. */ @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); Bundle pushData = this.getIntent().getExtras(); String key = "action"; Object exampleData = null; if(pushData != null) { actionData = pushData.get(key); } } |
pushData.get(key)의 경우 return type이 Object 이므로, 약속된 type을 알고 있다면 다음과 같이 명시적으로 활용할 수 있다.
|
1 2 3 4 5 6 |
... String exampleData = null; if(pushData != null) { actionData = pushData.getString(key); } ... |
iOS
iOS는 앱의 실행 여부에 따라, Push 정보를 수신하는 위치가 달라진다.
앱이 실행중이지 않을 경우
Push 메시지를 통해 앱을 실행하게 되며, 앱을 실행하면 호출되는 Delegate의 launchOptions에서 PushData를 확인할 수 있다.
Delegate
|
1 |
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions; |
데이터 확인 샘플 코드
|
1 2 3 4 5 6 7 8 9 10 |
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { ... NSString *<strong>pushKey</strong> = UIApplicationLaunchOptionsRemoteNotificationKey; if ([[launchOptions allKeys] containsObject:<strong>pushKey</strong>] ){ NSDictionary *<strong>pushData</strong> = [launchOptions objectForKey:<strong>pushKey</strong>] ; NSLog(@"%@", <strong>pushData</strong>); } ... } |
앱이 실행중일 경우
앱이 실행중일 때 아래 Delegate의 userInfo에서 Push 데이터를 확인할 수 있다.
단, 앱이 Background에 있을 때에는 Push를 통한 앱 진입 시에만 확인 가능함
Delegate
|
1 |
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo; |
데이터 확인 샘플 코드
|
1 2 3 4 |
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { NSLog(@"didReceiveRemoteNotification : %@", userInfo); } |
파싱 코드 예제
Push 데이터는 NSDictionary* 형태로 추출되며, 기본적으로 아래와 같은 형식을 가지고 있다.
‘aps‘는 푸시 알림(Alert)에 사용되는 기본 데이터이며, 사용자의 데이터는 별도의 필드로 추가해야 한다.
아래는 ‘action‘이라는 사용자 데이터를 추가한 형태임.
|
1 2 3 4 5 6 7 8 9 |
{ aps = { alert = "Hello from APNs Tester."; badge = 1; }; action = { actiondata = "data"; }; } |
아래와 같은 형태로 ‘action‘ 데이터를 추출하여 사용이 가능함.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
앱 최초 실행 시 Delegate - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *) launchOptions { NSString *pushKey = UIApplicationLaunchOptionsRemoteNotificationKey; if ([[launchOptions allKeys] containsObject:pushKey] ) { NSDictionary *pushData = [launchOptions objectForKey:pushKey] ; NSLog(@"%@", pushData) ; NSDictionary *actionData = pushData[@"action"]; } } 앱 실행 중 Delegate - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo { // Action 데이터가 Dictionary 형태일 경우. NSDictionary *actionData = userInfo[@"action"]; } |