[APNs] 7. The Remote Notification Payload

The Remote Notification Payload

 각각의 APNs remote 알림은 하나의 페이로드를 포함합니다. 페이로드는, 어떻게 시스템이 사용자가에 알려야만 하는 지에 대한 정보와 함께, 여러분이 제공하기를 바라는 커스텀 정보를 포함하고 있습니다.

여러분이 사용하는 provider API 에 의존하는 알림을 위한 최대 페이로드 크기는, 다음과 같습니다:

• HTTP/2-based APNs provider API
  • Regular push notification : 4KB(4096 bytes)
  • Voice over Internet Protocol(VoIP) notification : 5KB(5120 bytes)
• Legacy APNs binary interface
  • Regular push notification : 2KB(2048 bytes)

APNs 는  여러분이 사용하는 인터페이스 그리고 여러분이 보내는 알림의 종류에 대해 최대 크기를 초과하는 알림들에 대해서는 거부합니다.

Payload Keys

각각의 알림에 대해서, JSON dictionay object 로 구성되어 있습니다(RFC 4627 에 정의된). 이 dictionary는 aps 키에 의해서 식별되어 집니다. aps dictionary 는 하나 또는 그 이상의 특징들을 담을 수 있는데 다음의 사용자 알림 형태에 명시되어 있습니다. :

• 사용자에게 하나의 alert 메시지를 보여준다.
• 숫자를 앱 아이콘 배지로 한다.
• 소리를 재생한다.

조용한 remote 알림을 제공하기 위해서, remote-notification 값을 여러분의 Info.plist 파일에 UIBackgroundModes 배열에 추가한다. 이 배열에 대해 좀 더 배우려면, UIBackgroundModes 에 대해서 보세요.

만약 알림이 도착했는데도 특정 앱이 실행중이지 않더라도, alert 메시지, 소리, 배지값이 실행되거나 보여진다. 많약에 앱이 실행중이라면, 시스템은 알림을 NSDictionary 객체로 앱을 delegate 하기 위해 보냅니다.

Provider 는 개인화 페이로드 값을 애플이 예약한 aps dictionary 바깥에 명시화할 수 있습니다. 개인화 값들은 JSON 구조를 사용해야만 하고 원시 타입이어야만 합니다: dictionary(object), array, string, number, 그리고 Boolean. 여러분은 개인화 페이로드 데이터에 일반사용자 정보(또는 민감한 정보)를 포함해서는 안 됩니다. 대신에, 컨텍스트를 설정하거나(사용자 인터페이스에 대한) 내부 메트릭스의 목적으로는 사용 가능합니다. 예를들어, 개인화 페이로드 값은 인스턴스 메시지 클라이언트 앱에서 사용되어지는 대화식별자일 수 있으며 또한 provider 가 알림을 보낼 때 식별할 수 있는 타임스탬프로 사용될 수 있습니다. alert 메시지와 관련된 동작은 파괴적이어서는 안 됩니다. - 예를 들면, 단말기의 데이터를 지워서는 안 됩니다.

요점: 알림을 전달하는 것은 최선의 노력이지, 보장하지 않습니다. 이것은 여러분의 앱으로 데이터를 전달하려는 의도가 아니라, 오직 사용자에게 새로운 데이터가 왔다는 걸 알려줄 뿐입니다.

표 5-1 aps 페이로드의 키들의 목록과 예상 값들.

표 5-1 aps dictionary 의 키와 값

Key	Value Type	Comment
alert	string or dictionary	만약에 속성이 포함되어 있으면, 시스템은 표준alert 이나 배너로 표시하는데, 이는 사용자 설정에 기반합니다. alert의 값으로 string 이나 dictionary 로 명시할 수 있습니다. 만약에 string 으로 명시하면, 두 개의 버튼을 가진 메시지 텍스트 alert이 될 것입니다. : Colse and View. 만약 사용자가 View 를 tab하면, 앱이 실행될 것 입니다 만약에 dictionary 로 명시하면, dictionary 의 key 에 대한 설명이 있는 Table 5-2를 참고하세요. JSON의 \U 표기는 지원되지 않습니다. 텍스트 대신에 실제 UTF-8 캐릭터를 입력하세요.
badge	number	앱 아이콘의 배지로 표현되는 숫자. 만약에 속성이 누락됬으면, 배지는 변하지 않습니다. 배지를 삭제하기 위해서는, 속성의 값을 0으로 셋팅하세요.
sound	string	앱 번들 안의 또는 앱의 데이터 컨테이너 안의 Library/Sounds 폴더 안의 사운드파일 이름입니다. alert 되면서 파일 안의 소리가 재생됩니다. 만약에 소리파일이 없으면 default 로 값이 명시화 되며, 기본 alert 소리가 재생됩니다. 오디오는 오디오 데이터 형식들 중 하나이어야만 하고 그 형식들은 시스템 소리에 호환되야합니다.; 더 자세한 내용은 Preparing Custom Alert Sounds 를 보세요.
content-available	number	1이라는 값으로 제공되는 이키는 새로운 내용을 이용할 수 있다는 걸 나타냅니다. 이 키와 값을 포함하는 것의 의미는 여러분의 앱이 백그라운드나 재실행 상태에서 실행되었을 때, application:didReceiveRemoteNotification:fetchCompleteHandler : 가 호출된다는 것을 말합니다.
category	string	string 값으로 제공되는 이 키는 개인화 행동들을 정의하기 위해 여러분이 UIMutableUserNotificationCategory 객체의 identifier 속성을 표현합니다. 개인화 활동들을 사용하는 것을 더 배우려면, Registering Your Actionable Notification Types 를 보세요.

표 5-2 alert dictionary 에 대한 키들의 목록과 예상 값들.

표 5-2 alert 속성의 자식 속성들.

Key	Value	Comment
title	string	알림의 목적을 설명하는 짧은 문자열입니다. 애플시계는 알림 인터페이스의 일부로 문자열을 보여줍니다. 문자열은 간략하게 보여져야하고 빠르게 이해할 수 있도록 만들어져야만 합니다. 이 키는 iOS 8.2부터 추가되었습니다.
body	string	alert 메시지의 텍스트 입니다.
title-loc-key	string or null	이 키는 지역화를 위한 Localizable.strings 파일의 title string 입니다. 이 키는 title-loc-args 배열에 명시된 변수들을 다루기 위해 %@ 그리고 %n$@ 규정자 의 형식이 될 수 있습니다.  더 많은 정보를 보려면 Localized Formmated Strings 를 보세요. 이 키는 iOS 8.2 부터 추가되었습니다.
title-loc-args	array of strings or null	title-lox-key 의 형식 규정자를 대신하기 위한 다양한 문자열 값들 입니다. 더 많은 정보는 Localized Formmated Strings 를 보세요. 이 키는 iOS 8.2 부터 추가되었습니다.
action-loc-key	string or null	만약에 문자열이 명시되어 있다면, 시스템은 Close 와 View 버튼을 포함한 alert을 보여줄 것 입니다. 문자열은 View 대신에 오른쪽 버튼의 제목 사용하기 위해 현재 지역에서 지역화된 문자열을 얻기 위한 키로 사용됩니다.
loc-key	string	현재 위치에 대한 Localizable.strings 파일의 alert 메시지 문자열에 대한 키 입니다(사용자의 언어에 따라서 설정됩니다). 키 문자열은 loc-args 배열에 명시된 변수로 %@ 그리고 %n$@ 규정자 의 형식일 수 있습니다. 더 많은 정보를 보려면 Localized Formmated Strings 를 보세요.
loc-args	array of strings	low-key 안에 형식있는 규정자? 로서 변할 수 있는 문자열 값을 나타냅니다. 더 많은 정보를 보려면 Localized Formmated Strings 를 보세요.
launch-image	string	앱 번들 안의 이미지 파일의 파일명으로, 파일이름 확장 또는 없이~.  이미지는 실행 이미지로 사용되어지는데, 사용자가 action button을 탭하거나 action slider 를 이동시킬 때 입니다.

Configuring a Silent Notification

 aps dictionary 는 content-available 속성을 담을 수 있습니다. 1로 설정된 content-available 속성은 원격 알림 행동을 묵음 알림으로 만듭니다. 묵음 알림이 도착했을 때, iOS는 백그라운드의 앱을 깨우고 서버로부터 새로운 데이터를 가져오거나 백그라운드 정보 처리를 수행합니다. 사용자는 묵음 알림으로부터의 결과로 나온 새로운 또는 변경된 정보에 대해서 이야기하지 않는데, 그러나 다음 번 앱을 열었을 때 찾을 수 있을 것 입니다.

 묵음 알림에 대해서, 확실하게 다루어야 할 게 있는데 aps dictionary 에 alert, sound, badge 가 없어야 합니다. 만약 이 지침을 따르지 않는다면, 부정확하게 설정된 알림이 throttle 되고 백그라운드의 앱에 전달되지 않을 것이고 묵음 대신에 사용자에게 보이게 될 것 입니다.

Localized Formatted Strings

Examples of JSON Payloads

다음으로는 알림들의 페이로드 일부분의 예제들이 Table 5-1 에 목록화된 속성들의 실제적인 사용이 보여지고 있습니다. “acme” 키 이름의 속성들은 개인화 페이로드 데이터의 예제들 입니다.

Note: 예제들은 가독성을 위해 공백과 줄바꿈으로 형식화되어 있습니다. 실사용에서, 페이로드의 크기를 줄이기 위해서, 네트워크 성능 향상을 위해서 공백과 줄바꿈을 빼기도 합니다.

Example 1. 간단한 pas dictionary를 가진 페이로드가 있는데, 기본적인 alert 버튼(Close and View)을 가진 alert 메시지이 추천하는 형태 입니다. 이것은 alert 값으로 dictionary보다 문자열을 사용합니다.

{     "aps" : { "alert" : "Message received from Bob" },     "acme2" : [ "bang",  "whiz" ] }

Example 2. 예제의 페이로드는 단말기가 왼쪽에 Close 버튼 오른쪽엔 “action” 버튼에 대한 지역화된 제목을 alert 메시지로 보여주는 것을 요청하는데 aps dictionary를 사용합니다. 이 경우에, “PLAY”는 지역화에 상응되는 것을 가져오기 위해 현재 선택된 언어를 위한 Localizable.strings 파일의 키로 사용됩니다. aps dictionary는 또한 숫자5의 앱아이콘 배지로 요청합니다. 애플 시계에서는, 제목키는 사용자에게 새로운 요청을 alert 합니다.

{     "aps" : {         "alert" : {             "title" : "Game Request",             "body" : "Bob wants to play poker",             "action-loc-key" : "PLAY"         },         "badge" : 5     },     "acme1" : "bar",     "acme2" : [ "bang",  "whiz" ] }

Example 3. 예제의 페이로드는 단말기가 Close and View 버튼의 alert 메시지를 보여줘야만 합니다. 숫자9의 앱아이콘 배지와 알림이 전달됬을 때 번들 alert 소리를 요청합니다.

{     "aps" : {         "alert" : "You got your emails.",         "badge" : 9,         "sound" : "bingbong.aiff"     },     "acme1" : "bar",     "acme2" : 42 }

Example 4. 예제의 페이로드는 alert dictionary 의 자식 속성으로 loc-key 와 loc-args 는 형식화된 지역화 문자열을 앱 번들로부터 가져오고 적절한 위치의 변수 문자열 값(loc-args)으로 교체합니다. 이것은 또한 개인화 소리와 개인화 속성도 명시화 합니다.

{     "aps" : {         "alert" : {             "loc-key" : "GAME_PLAY_REQUEST_FORMAT",             "loc-args" : [ "Jenna", "Frank"]         },         "sound" : "chime.aiff"     },     "acme" : "foo" }

Example 5. 예제의 페이로드는 알림 행동들의 그룹을 명확하게 하기 위한 category 키를 사용합니다.

{   "aps" : {       "category" : "NEW_MESSAGE_CATEGORY"       "alert" : {         "body" : "Acme message received from Johnny Appleseed",         "action-loc-key" : "VIEW"       },       "badge" : 3,       "sound" : “chime.aiff"   },   "acme-account" : "jane.appleseed@apple.com",   "acme-message" : "message123456" }