푸시 알림

카카오 플랫폼 서비스에서 제공하는 푸시 알림은 APNS(Apple Push Notification Service), GCM(Google Cloud Messaging)을 활용합니다. 카카오 푸시 서비스는 멀티 플랫폼을 지원하며, 해당 서비스를 사용하면 푸시 알림 기능을 위한 별도의 메시지 큐 서버 및 전송 서버를 구축할 필요가 없습니다.

현재 제공되는 푸시 알림 API는 다음과 같습니다.

푸시토큰의 등록/조회/해제는 안드로이드, iOS SDK를 통해서도 가능하나, 푸시 알림 전송은 REST API로만 지원합니다.

푸시 알림을 지원하기 위한 iOS, Android의 환경 설정과 SDK를 이용한 푸시토큰의 등록/해제는 아래를 참고 합니다.

  • iOS 푸시 알림: APNS 인증서 발급 및 iOS 애플리케이션에서 필요한 푸시 토큰 발급/등록/해제에 대한 설명입니다.
  • Android 푸시 알림: GCM 서비스 사용 등록 및 Android 애플리케이션에서 필요한 푸시 토큰 발급/등록/해제에 대한 설명입니다.

시작하기 전에

카카오 푸시 서비스를 이용하기 전에 아래의 내용을 먼저 살펴보기를 권장합니다.

  • 요구사항: REST API로 제공되는 푸시 알림을 사용하기 위한 조건에 대해 설명합니다.
  • 푸시 토큰 관리 개요: 애플리케이션, APNS/GCM, Third 서버, 카카오 플랫폼 서버를 통해 어떻게 푸시 토큰이 관리되는지에 대해 설명합니다.
  • 푸시 알림 보내기 개요: 애플리케이션, APNS/GCM, Third 서버, 카카오 플랫폼 서버를 통해 어떻게 푸시 알림이 전달되는지에 대해 설명합니다.

요구사항

카카오 플랫폼 서비스는 REST API로 푸시 알림을 제공합니다. 해당 기능을 올바로 사용하기 위해서는 서비스에서 다음과 같은 사항을 만족해야 합니다.

  • REST API를 호출할 수 있는 자체 앱 서버가 있어야 합니다.
    • 푸시 토큰 등록, 삭제 및 푸시 알림 전송 등을 이용하기 위해서는 카카오 플랫폼 서비스에서 제공하는 어드민 키(Admin Key)를 사용하여 REST API를 호출해야 합니다. 어드민 키는 절대로 유출되어서는 안 되는, 일종의 마스터 키(Master Key)이므로 반드시 Third 서버에서 API를 호출해야 합니다.
    • 어드민 키는 카카오 웹사이트의 내 애플리케이션에서 확인할 수 있습니다. 만약 iOS, Android 애플리케이션의 소스코드 내에서 어드민 키를 사용할 경우, 해당 애플리케이션은 보안에 취약할 수 있습니다.
  • 서비스가 내부적으로 관리하는 정수(Long) 형태의 사용자 고유 ID가 있어야 합니다.
    • 정수의 범위는 1부터 2^63 - 1까지 사용 가능 합니다.
    • 카카오 로그인을 사용한다면 카카오가 제공하는 user id를 사용해도 무방하나 반드시 카카오에서 제공하는 사용자의 고유 ID를 사용할 필요는 없습니다.

푸시 토큰 관리 개요

사용자의 푸시 토큰은 카카오 푸시 서비스에서 관리됩니다. 다음은 사용자의 푸시 토큰에 대한 등록 및 삭제 과정을 살펴봅니다.

사용자의 푸시 토큰 등록
  1. iOS/Android 애플리케이션(App Client)은 푸시 토큰을 APNS/GCM으로부터 발급 받습니다.

    iOS, Android의 푸시 토큰 발급하는 과정은 iOS 푸시 알림, Android 푸시 알림을 참조하세요.

  2. 애플리케이션은 발급 받은 푸시 토큰을 자체 앱 서버(3rd App Server)로 보냅니다.
  3. 앱 서버(3rd App Server)에서는 앱으로부터 받은 푸시 토큰을 어드민 키, 서비스내의 고유한 사용자 ID와 함께 푸시 토큰 등록 API를 호출합니다. restapi_push_token1

사용자의 푸시 토큰 삭제
  1. 사용자가 해당 애플리케이션의 푸시를 더이상 이용하지 않는 이벤트를 발생시킵니다.

    예를 들어, 사용자가 해당앱을 로그아웃 했거나, 해당 앱의 푸시 알림을 끈 경우

  2. 해당 애플리케이션은 자체 앱 서버(3rd App Server)로 푸시 토큰 삭제 이벤트를 알리고, 앱 서버는 어드민 키, 서비스내의 고유한 사용자 ID와 함께 푸시 토큰 삭제 REST API를 호출합니다.
  3. 카카오 API 서버는 해당 사용자 ID의 모든 푸시 토큰을 찾은 후 삭제합니다. restapi_push_token2

푸시 알림 보내기 개요
  1. 사용자가 애플리케이션을 이용해 푸시를 보내는 이벤트를 발생시킵니다.

    예를 들어, 한 사용자(User1)가 친구(User2)의 쓴 글에 댓글을 남길 경우

  2. 해당 애플리케이션은 자체 앱 서버(3rd App Server)로 푸시를 보낼 이벤트를 보냅니다. 이때 앱이 보낼 메시지를 구성하여 보낼 수도 있고 앱 서버에서 이벤트를 받아 메시지를 구성할 수도 있습니다.
  3. 앱 서버는 구성한 메시지와 어드민 키, 푸시를 받아야 할 사용자의 ID와 함께 카카오 푸시 REST API를 호출합니다.
  4. 카카오 API 서버는 해당 사용자 ID의 모든 푸시 토큰을 찾은 후, 적절하게 APNS/GCM 서버로 해당 내용을 전송합니다. 여러 디바이스가 등록되어 있을 경우, 모든 디바이스로 푸시 알림이 전송됩니다. restapi_push_noti

푸시 알림에 대한 대략적인 내용을 살펴보았습니다. 다음은 실제 REST API를 호출하기 위한 상세내용을 설명합니다.

푸시 토큰 등록

푸시 알림을 이용하기 위해서는 우선 수신하는 사용자의 푸시 토큰(디바이스 토큰)이 카카오 푸시 서비스에 등록되어 있어야 합니다.

푸시 API는 다른 REST API와 달리 사용자의 AccessToken이 아니라, 앱 사용자 전체를 관리 할 수 있는 어드민 키(Admin Key)가 필요합니다. 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 자체 앱 서버에서 API를 호출하시기 바랍니다.

[Request]

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

어드민 키와 함께 아래 파라미터의 값들을 POST로 요청합니다.

설명 필수
uuid 사용자의 고유 ID. 1~(2^63 -1) 범위의 정수만 사용 가능     O    
device_id 기기의 고유한 ID. 멀티 디바이스를 지원하기 위함으로 기기별로 푸시 보내는 것과 디바이스별 푸시 토큰 삭제가 가능해진다.
APNS의 경우는 기기마다 푸시토큰이 다르기 때문에 APNS로 부터 받은 토큰을 그대로 사용해도 무방하나 GCM은 한 기기에 여러 푸시 토큰이 가능하기 때문에 기기 고유 ID를 생성하는 적절한 알고리즘이 필요하다.
최대 64자.
O
push_type apns 혹은 gcm O
push_token       APNS(64자), GCM으로부터 발급받은 Push Token O


다음은 Request 예제입니다

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

위의 응답 내용 중 30은 해당 푸시 토큰이 30일 내에 재등록이 없을 경우 만료됨을 뜻합니다. 값이 -1일 경우 만료 무제한을 의미합니다.

푸시 토큰 조회

푸시 알림을 이용하기 위해서는 우선 수신하는 사용자의 푸시 토큰(디바이스 토큰)이 카카오 푸시 서비스에 등록되어 있어야 합니다. 이미 등록했는지 등록된 푸시 토큰이 무엇인지 조회할 수 있습니다.

푸시 API는 다른 REST API와 달리 사용자의 AccessToken이 아니라, 앱 사용자 전체를 관리 할 수 있는 어드민 키(Admin Key)가 필요합니다. 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 자체 앱 서버에서 API를 호출하시기 바랍니다.

[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}

어드민 키와 함께 아래 파라미터의 값들을 GET 또는 POST로 요청합니다.

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


다음은 Request 예제입니다

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]

요청이 성공하면 응답 바디에 JSON 객체로 푸시 토큰 정보가 Array로 포함합니다.

설명 타입
user_id 사용자의 고유 ID. 1~(2^63 -1) 범위의 정수만 사용 가능 String
device_id 기기의 고유한 ID.
최대 64자.
String
push_type apns 혹은 gcm String
push_token APNS(64자), GCM으로부터 발급받은 Push Token String
created_at 푸시 토큰을 처음 등록한 시각 Datetime
updated_at 푸시 토큰을 업데이트한 시각 Datetime

예를 들어,
앞에서 푸시 토큰을 등록한 사용자를 조회하면

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"
    }
]

푸시 토큰 삭제

푸시 토큰을 삭제하는 API 입니다. 다음과 같은 상황에서 해당 API가 필요할 수 있습니다.

  • 사용자가 특정 기기에서 푸시 알림을 끄고 싶을 때
  • 사용자가 특정 기기에서 로그아웃을 할 때

푸시 API는 다른 REST API와 달리 사용자의 AccessToken이 아니라, 앱 사용자 전체를 관리 할 수 있는 어드민 키(Admin Key)가 필요합니다. 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 자체 앱 서버에서 API를 호출하시기 바랍니다.

[Request]

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

어드민 키와 함께 아래 파라미터의 값들을 POST로 요청합니다.

설명 필수
uuid 사용자의 고유 ID. 1~(2^63 -1) 범위의 정수만 사용 가능     O    
device_id 기기의 고유한 ID. 한 사용자에 등록된 기기가 여러개인 경우 해당 기기의 푸시 토큰만 삭제 가능하다. 최대 64자. O
push_type apns 혹은 gcm O



다음은 Request 예제입니다.

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

성공일 경우, HTTP StatusCode 200에 응답 내용은 없습니다.

푸시 알림 보내기

푸시 알림을 보내는 API입니다. 수신할 사용자 ID로 등록된 모든 기기로 푸시 알림이 보내집니다.

푸시 API는 다른 REST API와 달리 사용자의 AccessToken이 아니라, 앱 사용자 전체를 관리 할 수 있는 어드민 키(Admin Key)가 필요합니다. 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 자체 앱 서버에서 API를 호출하시기 바랍니다.

[Request]

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

어드민 키와 함께 아래 파라미터의 값들을 POST로 요청합니다.

설명 필수
uuids 수신할 사용자의 고유 ID 리스트. Json Array 형태. 사용자 고유 ID는 1~(2^63 -1) 범위의 정수만 사용 가능. 100개 이하만 허용.     O    
push_message 아래 PushMsgJson 참조. 최소 {}는 보내야함. O
bypass 토큰 관리를 자체적으로 할 경우, bypass용으로 푸시 알림을 사용할지의 여부(Boolean). 디폴트 false. bypass를 사용시 push_token을 PushMsgJson에 포함하여야 함. X


PushMsgJson

PushMsgJson은 다음과 같은 포맷으로 구성되어 있습니다.
APNS만 사용하도록 설정되어 있으면 for_apns만, GCM만 사용하도록 설정되어 있으면 for_gcm만 넣으시면 됩니다. 만약 둘 다 설정이 되어 있으면 반드시 둘 다 넣으셔야 합니다.

{
  "for_apns":{
    "badge": 3,
    "sound": "sound_file",
    "push_alert": true,
    "content-available":1,
    "category":"INVITE_CATEGORY",
    "message": "홍길동님 외 2명이 댓글을 달았습니다.",
    "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": "나의 댓글을 받아랏!...(생략)"
    }
  }
}
for_apns

for_apns의 세부 속성은 다음과 같습니다.

속성 타입 필수 설명 예시
badge Integer     X     iOS기기의 앱에 표시될 배지 카운트 123
sound String X Push 수신 시 알람 소리 "default"
push_alert Boolean X 음소거, 알림센터에 뜨지 않는 상태로 Push 전송.
푸시 음소거 및 알림센터에 띄우지는 않되, badge 수는 바꾸고 싶을 때 사용.
false
content-available Integer X 새로운 콘텐츠를 사용할 수 있음을 나타냄 1
category String X 알림센터에 보여줄 액션 설정 INVITE_CATEGORY
message String or Dictionary X APNS 기준 alert에 해당. 알림센터에 표시할 내용 "내가 쓴 글에 댓글이 달렸습니다."
custom_field Dictionary X 메시지 외 앱에 부가적인 정보를 전달하고자 할 때 사용 {"article_id" : 111}
push_token String X bypass를 사용할 경우 자체 관리하는 토큰 "AAABBBCCCDDD"

APNS의 경우, APNS 서버에서 수신한 데이터 기준으로 푸시 알림 한 건의 전체 길이(alert + custom_field + etc)가 256byte를 넘을 수 없습니다. 그래서 메시지 경량화를 위해 특정 푸시 알림 메시지 포맷을 미리 앱에 저장하고 포맷의 키와 파라미터만 넘기는 방법도 제공합니다. (Creating the Remote Notification Payload)

Localized Formatted String 기능은 다음과 같이 사용 가능합니다.

{
  "message":{
    "loc-key" : "COMMENT_ALERT_FORMAT",
    "loc-args" : ["홍길동", "2"]
  }
}

만약 예시의 COMMENT_ALERT_FORMAT이 다음과 같은 형식이라면

%@님 외 %@명이 댓글을 달았습니다.

실제의 푸시 알림은 다음과 같은 형태로 푸시 알림 메시지를 수신하게 됩니다.

홍길동님 외 2명이 댓글을 달았습니다.
for_gcm

for_gcm의 세부 속성은 다음과 같습니다.

속성 타입 필수 설명 예시
collapse String X 푸시 메시지 구분자. 같은 값을 가지는 푸시 알림이 여러 개일 때 마지막 하나만 사용자 기기로 전송.(GCM 공식 문서 참조) "wi10ck48"
delay_while_idle Boolean X false일 경우, 사용자 기기의 idle 상태 상관없이 즉시 푸시 알림 전송. 반대로 true로 하면 GCM 서버 상태에 따라 어느 정도 시간이 지난 후 푸시 알림이 전송됨 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 메시지 외 앱에 부가적인 정보를 전달하고자 할 때 사용
APNS와 다르게 푸시 알림 한 건의 전체 길이가 4KB까지 가능
{"article_id" : 111 }
return_url String X 푸시 알림의 전송 실패에 대한 피드백 처리가 필요할 때 사용 https://example.com/gcm_push_fail
push_token String X bypass를 사용할 경우 자체 관리하는 토큰 "AAABBBCCCDDD"


return_url로 보낼 때 POST를 사용하며, 다음의 값들이 포함됩니다.

  • userId: 해당 Push 실패된 Push Token의 userId
  • pushToken: Push 실패된 Push Token
  • date: 전송 실패한 시간(정수로 된 unix time, millisec)

gcm 전송 실패 피드백에 대한 Request 예제입니다.

POST /gcm_push_fail HTTP/1.1
Host: example.com
Content-type: application/x-www-form-urlencoded

userId=123&pushToken=abcdefg&date=1396582208000


Request 예제는 다음과 같습니다.

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":"홍길동님 외 2명이 댓글을 달았습니다.",
    "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": "나의 댓글을 받아랏!...(생략)"
    }
  }
}'

[Response]

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

Request가 성공일 경우, HTTP StatusCode 200에 응답 내용은 없습니다. 단, 200(OK)가 수신 받을 기기까지 제대로 전송되었음을 뜻하지는 않습니다. 200(OK)일지라도 APNS, GCM의 서버 상태가 좋지 않을 경우 푸시 알림이 제대로 전송되지 않을 수도 있습니다.


Last Modified : 2017-08-03