Push notification

Kakao platform service provide push notification through APNS(Apple Push Notification Service), GCM(Google Cloud Messaging). Kakao Push service support multi platform and if you use such service you do not need separate message queue server and forwarding server for push notification separately.

Supported push notification API follows.

Although push token registration /lookup/ deletion works in iOS and android, forwarding push notification is supported only in REST API REST API.

In order to support push notification for iOS and Android, follow settings and SDK of push token registration/deletion below.

  • iOS push notification: This is about issuing APNS certification and issuing /registering /deleting iOS push token required for application.
  • Android push notification: This is about GCM service usage registration and issuing /registering/ deleting Android application required push token.

Getting started

Before getting in to kakao push service, please refer content below.

  • Requirement: Discuss requirement for using push notification REST API.
  • Push token management: Discuss on how push token is managed through Application, APNS/GCM, Third server, kakao platform server .
  • Sending push notification: Discuss on how push token is sent through Application, APNS/GCM, Third server, kakao platform server.

Requirement

Kakao platform service provide push notification through REST API. In order to use such functionality, service should meet below criteria.

  • There must be a app server that could call REST API.
    • In order to register, delete and forward push token, Admin key that is provided from kakao platform service must be used for calling REST API. Admin key should never be opened to the public. It is a master key which means it should be used to call API from the third server.
    • Admin key can be checked at my application in kakao's website. If admin key is used inside iOS, Android application, such application will be vulnerable to malicious attacks in future.
  • Service should obtain unique ID of type Long.
    • This natural number can be of range from 1 to 2^63 - 1.
    • If you are using kakao login, kakao provided user id can be used but using kakao provided unique id is not required to be used.

Push token management

Kakao push service manages user's push token. Following looks deep in to user push token registration and deletion.

Registering user push token
  1. iOS/Android application(App Client) retrieve push token from APNS/GCM.

    For issuing iOS, Android's push token, refer to iOS push notification, Android push notification.

  2. Application send issued push token to 3rd App Server.
  3. 3rd App Server uses push token retrieved from app with admin key and user's unique ID to call push token registration API. restapi_push_token1

Delete user push token
  1. Triggers event for user to no longer use push service in application.

    This happens in circumstances where user have logged out or have turned push notification off

  2. Application will notify 3rd App server about push token deletion event and the server will request deletion through calling RST API with admin key and unique user ID.
  3. Kakao API server will find user with such unique ID and delete it's push token. restapi_push_token2

Send push notification
  1. This is about triggering event for forwarding push through user application.

    If User1 leaves comment on User2's post for example

  2. Application will send event to 3rd App Server. Message can be either structured or can be structured through app server once event has been received .
  3. Once message is structured by App server, it will call REST API with message, admin key, and user ID of who is about to receive the push notification.
  4. After kakao API server find user ID and it's push token, it will send content to APNS/GCM .If such device exists and is registered, all of the device with such information will received push notification. restapi_push_noti

We have covered briefly about push notification. Following is a details on how to call REST API request.

Register push token

In order to use push notification, device that will receive push notification should register it's push token (device token) in kakao push server.

Unlike other REST API, push token does not use AccessToken but need Admin key to control entire users. In order to avoid admin key from being stolen, please call API through app server, not from your app it self.

[Request]

POST /v1/push/register HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}

Request using POST method with admin key and parameter below.

key description required
uuid user unique ID. Allowed range of integer number from 1~(2^63 -1)     O    
device_id device unique ID. This is to support multi device. This enables us to send push by device and delete by device.
For APNS, each device have different push token. This means push token retrieved from APNS can be used directly but since GCM lets you have multiple push token per device, you need sounding algorithm to create device unique ID.
max character of 64.
O
push_type apns or gcm O
push_token       APNS(max 40 words),Push token retrieved from GCM O


Following is Request example

curl -v -X POST https://kapi.kakao.com/v1/push/register \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
  -d "uuid=1234&device_id=0f365b39-c33d-39be-bdfc-74aaf5534470&push_type=gcm" \
  -d "push_token=APA91bEZ3fjwrKV2mxAFvZMC960zKBWBVffLErwZgFzsFnzzsxgi5lSQlq3zvzObZBe4OnbwkTZfMqV7_a6fF0AJNgUjt5Scpo2BTaHyLVlK54QmwIQBahUwJprKjj0YvF_rh8l7CTvl6TRxqlqO_NIwaoAcI0MssA"

[Response]

HTTP/1.1 200 OK
Content-Length: 2
Content-type: application/json;charset=UTF-8

30

In above response, number 30 means that if there is no re-registeration of push token in 30 days, it will expire. 값이 -1일 경우 만료 무제한을 의미합니다.

Lookup push token

In order to use push notification, push token(device token) must be registerd in kakao push service. If it has already been registered, you can lookup on what your push token is.

Unlike REST API's AccessToken, push API need Admin key to control entire app user. Please make sure that your admin key is not stolen and that you do not call API directly within your app. Please make sure to make the API request through app server. [Request]

GET /v1/push/tokens HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}
POST /v1/push/tokens HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}

With admin key, below parameter will be included in request using GET or POST method.

설명 필수 비고
uuid user unique ID. Allowed range of integer number from 1~(2^63 -1) X 단, uuid 또는 uuids 둘 중 하나는 있어야 함.
uuids 사용자의 고유 ID 리스트. Json Array 형태. 사용자 고유 ID는 1~(2^63 -1) 범위의 정수만 사용 가능. 100개 이하만 허용. X 단, uuid 또는 uuids 둘 중 하나는 있어야 함.


Following is a Request example

curl -v -X GET https://kapi.kakao.com/v1/push/tokens?uuid=1234 \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"
curl -v -X POST https://kapi.kakao.com/v1/push/tokens \
  -d 'uuids=["1234", "5678"]'  \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

If request succeed, response body will include push token information with array in JSON object.

key description type
user_id user unique ID. Allowed range of integer number from 1~(2^63 -1) String
device_id device unique ID.
with max character of 64.
String
push_type apns or gcm String
push_token APNS(64 characters), Push token issued from GCM String
created_at Time that push token was first registered Datetime
updated_at Time that push token was first updated Datetime

For example,
If you lookup user who have previously registered push token

HTTP/1.1 200 OK
Content-type: application/json;charset=UTF-8
[
    {
    "user_id":"1234",
    "device_id":"0f365b39-c33d-39be-bdfc-74aaf5534470",
    "push_type":"gcm",
    "push_token":"APA91bEZ3fjwrKV2mxAFvZMC960zKBWBVffLErwZgFzsFnzzsxgi5lSQlq3zvzObZBe4OnbwkTZfMqV7_a6fF0AJNgUjt5Scpo2BTaHyLVlK54QmwIQBahUwJprKjj0YvF_rh8l7CTvl6TRxqlqO_NIwaoAcI0MssA",
    "created_at":"2014-07-29T06:24:12Z",
    "updated_at":"2014-07-29T06:24:12Z"
    }
]

Push token deletion

This is an API for deleting push token. In following circumstance, this API will be needed.

  • When user wish to turn off push notification in certain device
  • When user log out from certain device

Unlike REST API's AccessToken, push API need Admin key to control entire app user. Please make sure that your admin key is not stolen and that you do not call API directly within your app. Please make sure to make the API request through app server.

[Request]

POST /v1/push/deregister HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}

With admin key and below parameter included, request using POST method.

key description required
uuid user unique ID. Allowed range of integer number from 1~(2^63 -1)     O    
device_id Device unique ID. If there are multiple devices registered by single user, you can only delete targeted device's push token. max 64 characters. O
push_type apns or gcm O



Following is a Request example.

curl -v -X POST https://kapi.kakao.com/v1/push/deregister \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
  -d "uuid=1234&device_id=0f365b39-c33d-39be-bdfc-74aaf5534470&push_type=gcm"

[Response]

HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8

If it's success, there is no response content in HTTP StatusCode 200.

Sending push notification

This is an API for sending push notification . Send push notification to all of devices with targeted user id.

Unlike REST API's AccessToken, push API need Admin key to control entire app user. Please make sure that your admin key is not stolen and that you do not call API directly within your app. Please make sure to make the API request through app server.

[Request]

POST /v1/push/send HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}

Include below parameters with adminkey and make POST request.

key description required
uuids list of users unique ID. Allowed range of integer number from 1~(2^63 -1). In Json Array format. The array of size 100 or below is allowed.     O    
push_message refer PushMsgJson below. At minimum, {} or greater is required. O
bypass 토큰 관리를 자체적으로 할 경우, bypass용으로 푸시 알림을 사용할지의 여부(Boolean). 디폴트 false. bypass를 사용시 push_token을 PushMsgJson에 포함하여야 함. X


PushMsgJson

PushMsgJson is packaed in following format.
If only APNS is set to be used, you only have to input for_apns. If only GCM is set to be used input only for_gcm. If both are used, you must input both.

{
  "for_apns":{
    "badge": 3,
    "sound": "sound_file",
    "push_alert": true,
    "content-available":1,
    "category":"INVITE_CATEGORY",
    "message": "Hongil dong and 2 others have left comments .",
    "custom_field": {
      "article_id": "111",
      "comment_id": "222"
    }
  },
  "for_gcm":{
    "collapse": "articleId123",
    "delay_while_idle":false,
    "time_to_live":17200,
    "dry_run":false,
    "priority":"high",
    "custom_field": {
      "article_id": 111,
      "comment_id": 222,
      "comment_preview": "Receive my comment!.."
    }
  }
}
for_apns

for_apns's detail properties follow.

Category type required description example
badge Integer     X     Badge count to be displayed in app of iOS devices 123
sound String X When Push is received, notify through sound "default"
push_alert Boolean X In muted condition where push is forwarded without showing in notification center.
When you want to change badge count for when push is muted, and it's not shown in notification.
false
content-available Integer X 새로운 콘텐츠를 사용할 수 있음을 나타냄 1
category String X 알림센터에 보여줄 액션 설정 INVITE_CATEGORY
message String or Dictionary X APNS based alert. Contents to be shown in notification center "Comment has been left in your post."
custom_field Dictionary X When trying to send additional information beside message to the app {"article_id" : 111}
push_token String X bypass를 사용할 경우 자체 관리하는 토큰 "AAABBBCCCDDD"

For APNS, based on APNS server's received message, push notification can not exceed 256byte in total size(alert + custom_field + etc).As such, in order to make light weight message, saving specific format for notification message prior to receiving it is supported. This means that you only have to receive format key and parameter. (Creating the Remote Notification Payload)

Localized Formatted String functionality can be used following way.

{
  "message":{
    "loc-key" : "COMMENT_ALERT_FORMAT",
    "loc-args" : ["Hong gil-dong", "2"]
  }
}

If example's COMMENT_ALERT_FORMAT is in such format

%@ and %@ others commented.

Message will actually be received and formated as below.

Hong gil-dong and 2 others commented.

######for_gcm
`for_gcm`'s detail properties follow .

| Category | Type | required | details | example |
| :--- | :--- | :--: | :--- | :--- |
| collapse | String | X | Push message identifier. If there are multiple values of push notification, last will be sent to the device.(Refer GCM public document) | "wi10ck48" |
| delay_while_idle | Boolean | X | If it's false, push notification will be sent regardless of user device's idle status. At contrary, if it's set to true, push notification will be sent after awhile, depending on GCM server status | false |
| time_to_live | Integer | X | GCM에 저장될 미전송메시지 보관주기.(단위:초) | 17200 |
| dry_run | Boolean | X | 테스트를 위해 사용. 실제 단말에 전송되지 않는다. | true or false |
| priority | String | X | 단말이 도즈모드 상태에서도 푸시를 받을 수 있도록 한다.(기본값 normal) | high or normal
| custom_field | Json | X | Used when message or other app's are being used to forward additional information <br/>Unlike APNS, push notification of size 4KB can be sent | {"article_id" : 111 } |
| return_url | String | X | It's used for getting feedback on push notification forward failures | https://example.com/gcm_push_fail |
| push_token | String | X | bypass를 사용할 경우 자체 관리하는 토큰 | "AAABBBCCCDDD" |
<br/>
When sending return_url, POST method will be used, and below values will be included.
* userId: Targeted Push, failed Push Token's userId
* pushToken: Push failed Push Token
* date: Failed time(unix time, millisec of integer)

 This is a Request example of feedback during gcm forwarding failure .
```http
POST /gcm_push_fail HTTP/1.1
Host: example.com
Content-type: application/x-www-form-urlencoded

userId=123&pushToken=abcdefg&date=1396582208000


Request example follows

curl -v -X POST https://kapi.kakao.com/v1/push/send \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
  -d 'uuids=["1234", "5678"]'  \
  --data-urlencode 'push_message={
  "for_apns":{
    "badge": 3,
    "sound": "sound_file",
    "push_alert": true,
    "message": "Hongil dong and 2 others have left comments.",
    "custom_field": {
      "article_id": "111",
      "comment_id": "222"
    }
  },
  "for_gcm":{
    "collapse": "articleId123",
    "delay_while_idle":false,
    "custom_field": {
      "article_id": 111,
      "comment_id": 222,
      "comment_preview": "Receive my comment!...(생략)"
    }
  }
}'

[Response]

HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8

If Request is successful, HTTP StatusCode 200 will have no content in response. 200(OK) however does not guarantee that device that will be receiving the request has successfully received information. Even with 200(OK) if APNS, GCM server is enduring bad condition or failures, push notification might have failed to be received at user end.


Last Modified : 2017-08-03