"Send notifications to the user’s device with a JSON payload."
JSON 페이로드로 사용자의 기기에 노티피케이션을 전송합니다.
Overview
원격 노티피케이션은 사용자에게 JSON 페이로드 형식으로 중요한 정보를 전달합니다. 페이로드는 수행하길 원하는 사용자 상호작용의 타입(알림, 소리, badge)을 구체화하고, 앱이 노티피케이션에 반응하는 데 필요한 모든 커스텀 데이터를 포함합니다.
기본적인 원격 노티피케이션 페이로드는 애플이 정의한 키와 커스텀 값을 포함합니다. 특정 노티피케이션에 커스텀 키와 값을 추가할 수도 있습니다. 애플 푸시 노티피케이션 서비스(APNs)는 페이로드의 전체 크기가 아래 제한을 초과하는 노티피케이션을 거부합니다.
- Voice over Internet Protocol(VoIP)의 경우 최대 페이로드 크기는 5 킬로바이트(5120바이트)입니다.
- 다른 모든 원격 노티피케이션의 경우 최대 페이로드 크기는 4 킬로바이트(4096바이트)입니다.
Create the JSON Payload
JSON 딕셔너리를 사용해서 원격 노티피케이션을 위한 페이로드를 구체화할 수 있습니다. 이 딕셔너리 내부에 하나 혹은 하나 이상의 추가적인 애플이 정의한 키를 포함하는 값을 갖는 aps 키를 포함시켜야 합니다. Table 1에 목록으로 나와있습니다. 시스템에게 알림, 소리 재생을 표시하거나 앱의 아이콘에 badge를 달 수 있도록 지시하는 키를 포함시킬 수도 있습니다. 또한, 시스템에게 백그라운드에서 조용히 처리하도록 지시할 수도 있습니다. 더 많은 정보는 Pushing Background Updates to Your App을 보시기 바랍니다.
애플이 정의한 키와 더불어, 작은 양의 데이터, 노티피케이션 서비스 앱 확장, 노티피케이션 컨텐트 앱 확장을 전달하기 위해 페이로드로 커스텀 키를 추가할 수 있습니다. 커스텀 키는 딕셔너리, 배열, 스트링, 숫자, 불리언과 같은 원시 타입인 값을 갖고 있어야 합니다. 커스텀 키는 앱에서 전달받은 UNNotificationContent 객체의 userInfo 딕셔너리에서 사용이 가능합니다.
보통 코드가 노티피케이션 처리를 할 수 있도록 커스텀 키를 사용하게 될 것입니다. 예를 들어 코드가 앱의 특정 데이터를 찾는 데 사용할 수 있는 아이덴티파이어 스트링을 포함시킬 것입니다. aps 딕셔너리의 피어로 앱의 특정 키를 추가하시기 바랍니다.
Listing 1은 사용자를 게임에 초대하는 메시지를 알림으로 표시하는 노티피케이션 페이로드를 보여주고 있습니다. 카테고리 키가 이전에 등록된 UNNotificationCategory 객체를 식별하면, 액션 버튼은 알림에 추가됩니다. 예를 들어 여기에 있는 카테고리는 게임을 즉시 시작할 수 있는 실행 액션을 포함하고 있습니다. 커스텀 gameID 키는 앱이 게임 초대를 가져오는 데 사용할 수 있는 아이덴티파이어를 포함하고 있습니다.
Listing 1 A remote notification payload for showing an alert
{
"aps" : {
"alert" : {
"title" : "Game Request",
"subtitle" : "Five Card Draw"
"body" : "Bob wants to play poker",
},
"category" : "GAME_INVITATION"
},
"gameID" : "12345678"
}Listing 2는 앱의 아이콘에 badge를 추가하고 소리를 재생하는 노티피케이션 페이로드를 보여주고 있습니다. 구체화된 소리 파일은 사용자의 기기에 있어야 하고, 앱의 번들이나 앱 컨테이너의 Library/Sounds 폴더 중 한 곳에 있어야 합니다. messageID 키는 노티피케이션에 의해 발생하는 메시지를 식별하기 위한 앱의 특정 정보를 포함하고 있습니다.
Listing 2 A remote notification payload for playing a sound
{
"aps" : {
"badge" : 9
"sound" : "bingbong.aiff"
},
"messageID" : "ABCDEFGHIJ"
}노티피케이션을 위한 소리 생성과 관련해 더 많은 정보를 알고 싶으시다면 UNNotificationSound를 보시기 바랍니다.
UNNotificationSound
https://developer.apple.com/documentation/usernotifications/unnotificationsound
https://velog.io/@panther222128/UNNotificationSound
Important
신용카드 숫자와 같은 민감한 사용자 데이터를 노티피케이션 페이로드에 두지 않아야 합니다. 민감한 정보를 포함해야만 한다면 페이로드에 추가하기 전에 암호화하시기 바랍니다. 사용자의 기기에서 데이터 암호화 해제를 위해 노티피케이션 서비스 앱 확장을 사용할 수 있습니다. 더 많은 정보는 Modifying Content in Newly Delivered Notifications를 보시기 바랍니다.
Modifying Content in Newly Delivered Notifications
https://developer.apple.com/documentation/usernotifications/modifying_content_in_newly_delivered_notifications
https://velog.io/@panther222128/Modifying-Content-in-Newly-Delivered-Notifications
Localize Your Alert Messages
원격 노티피케이션의 컨텐트를 로컬화하는 방법은 두 가지가 있습니다.
- 페이로드에 로컬화된 스트링을 직접 포함시키는 것입니다.
- 로컬화된 메시지 스트링을 앱 번들에 추가하고, 시스템이 어떤 스트링을 표시할 것인지 선택하도록 하는 것입니다.
페이로드에 직접 로컬화된 스트링을 넣는 것은 더 많은 유연성을 제공하지만, 제공자 서버에서 사용자의 선호 언어를 추적해야 할 필요가 생깁니다. 제공자 서버는 스트링을 제공하기 때문에 어떤 언어가 사용되는지를 알고 있어야 합니다. 사용자의 기기에서 NSLocale의 속성인 preferredLanguages를 확인함으로써 사용자의 선호 언어를 가져올 수 있습니다. 그러면 앱은 서버에 해당 정보를 전달할 수 있습니다.
노티피케이션 메시지의 텍스트가 사전에 결졍된 것이라면, 메시지 스트링을 앱 번들에 있는 Localizable.strings 파일에 저장할 수 있으며, 어떤 스트링을 표시하길 원하는지 구체화할 수 있게 해주는 title-loc-key, subtitle-loc-key, loc-key 페이로드 키를 사용할 수 있습니다. 로컬화된 스트링은 동적으로 최종 스트링에 컨텐트를 입력할 수 있도록, 플레이스홀더를 포함하고 있을 것입니다. Listing 3은 앱이 제공한 스트링으로부터 기인한 메시지를 갖는 페이로드의 예시를 보여주고 있습니다. loc-args 키는 스트링으로 교체하기 위한 대체 변수의 배열을 포함하고 있습니다.
Listing 3 A remote notification payload with localized content
{
"aps" : {
"alert" : {
"loc-key" : "GAME_PLAY_REQUEST_FORMAT",
"loc-args" : [ "Shelly", "Rick"]
}
}
}컨텐트 로컬라이즈를 위해 사용할 수 있는 키는 Table 2에서 확인하시기 바랍니다.
Payload Key Reference
Table 1은 aps 딕셔너리에 포함시킬 수 있는 키의 목록입니다. 사용자와 상호작용하려면 알림, badge, 소리 키를 포함시키기 바랍니다. aps 딕셔너리에 커스텀 키를 추가하지 않아야 합니다. APNs는 커스텀 키를 무시합니다. 대신 aps 딕셔너리의 피어로 커스텀 키를 추가하시기 바랍니다. Listing 1에서 보여주고 있습니다.
Table 1 Keys to include in the aps dictionary
| Key | Value type | Description |
|---|---|---|
| alert | 딕셔너리 (혹은 스트링) | 알림을 표시하기 위한 정보입니다. 딕셔너리를 권장합니다. 스트링을 구체화하면 알림은 바디 텍스트로 스트링을 표시합니다. 딕셔너리 키의 리스트는 Table 2를 보시기 바랍니다. |
| badge | 숫자 | 앱 아이콘에 badge로 표시할 숫자입니다. 현재 badge를 지우려면 0으로 구체화해야 합니다. |
| 소리 | 스트링 | 앱 메인 번들 혹은 앱 컨테이너 디렉토리의 Library/Sounds에 있는 소리 파일 이름입니다. 시스템 소리를 재생하려면 스트링을 "default"로 구체화해야 합니다. 중요한 알림의 경우 소리 딕셔너리를 대신 사용해야 합니다. 소리를 준비하는 방법에 대한 더 많은 정보는 UNNotificationSound를 보시기 바랍니다. |
| 소리 | 딕셔너리 | 중요한 알림에 대해 소리 정보를 포함하는 딕셔너리입니다. 일반적인 노티피케이션은 사운드 스트링을 대신 사용해야 합니다. |
| 스레드 id | 스트링 | 관련 노티피케이션을 그룹화하기 위한 앱의 특정 아이덴티파이어입니다. 이 값은 UNNotificationContent 객체에 있는 threadIdentifier 속성에 상응합니다. |
| 카테고리 | 스트링 | 노티피케이션의 타입입니다. 이 스트링은 launch 시점에 등록한 UNNotificationCategory 객체의 한 가지 아이덴티파이어와 상응해야 합니다. Declaring Your Actionable Notification Types를 보시기 바랍니다. |
| 사용 가능한 컨텐트 | 숫자 | 백그라운드 노티피케이션 플래그입니다. 조용한 백그라운드 업데이트를 수행하려면 값 1을 구체화하고 알림, badge, 소리 키를 페이로드에 포함시키지 않아야 합니다. See Pushing Background Updates to Your App를 보시기 바랍니다. |
| 수정 가능한 컨텐트 | 숫자 | 노티피케이션 서비스 앱 확장 플래그입니다. 값이 1이면 시스템은 전달 전에 노티피케이션 서비스 앱 확장으로 노티피케이션을 전달합니다. 노티피케이션의 컨텐트를 수정하려면 확장을 사용하시기 바랍니다. Modifying Content in Newly Delivered Notifications를 보시기 바랍니다. |
| 타깃 컨텐트 id | 스트링 | 앞으로 가져온 윈도우의 아이덴티파이어입니다. 이 키의 값은 푸시 페이로부터 생성된 UNNotificationContent 객체를 채울 것입니다. UNNotificationContent 객체의 targetContentIdentifier 속성을 사용해서 값에 접근해야 합니다. |
| 인터럽션 수준 | 스트링 | 노티피케이션의 중요도 및 전달 타이밍을 나타내는 스트링입니다. 스트링 값은 UNNotificationInterruptionLevel 열거형 케이스에 상응하는 “passive”, “active”, “time-senstive”, “critical”입니다. |
| 관련성 스코어 | 숫자 | 앱으로부터 노티피케이션을 정렬하기 위해 시스템이 사용하는 숫자로 0에서 1 사이의 값을 갖습니다. 가장 높은 점수는 노티피케이션 요약에서 나타납니다. relevanceScore를 보시기 바랍니다. |
UNNotificationSound
https://developer.apple.com/documentation/usernotifications/unnotificationsound
https://velog.io/@panther222128/UNNotificationSound
Declaring Your Actionable Notification Types
https://developer.apple.com/documentation/usernotifications/declaring_your_actionable_notification_types
https://velog.io/@panther222128/Declaring-Your-Actionable-Notification-Types
Pushing Background Updates to Your App
https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app
https://velog.io/@panther222128/Pushing-Background-Updates-to-Your-App
relevanceScore
https://developer.apple.com/documentation/usernotifications/unnotificationcontent/3821031-relevancescore
https://velog.io/@panther222128/relevanceScore
Table 2는 알림 딕셔너리에 포함시킬 수 있는 키를 리스트로 보여주고 있습니다. 알림 배너에 포함시킬 타이틀 및 메시지를 구체화하기 위해 이러한 스트링을 사용하시기 바랍니다.
Table 2 Keys to include in the alert dictionary
| Key | Value type | Description |
|---|---|---|
| 타이틀 | 스트링 | 노티피케이션의 제목입니다. 애플 워치는 이 스트링을 short look 노티피케이션 인터페이스에서 표시합니다. 사용자에 의해 빠르게 이해될 수 있는 스트링을 구체화해야 합니다. |
| 서브타이틀 | 스트링 | 노티피케이션 목적을 설명하는 추가적인 정보입니다. |
| 바디 | 스트링 | 알림 메시지의 내용입니다. |
| launch 이미지 | 스트링 | 표시하고자 하는 launch 이미지 파일의 이름입니다. 사용자가 앱 launch를 선택하면 앱의 launch 이미지 대신 구체화된 이미지 의 컨텐츠 혹은 스토리보드 파일의 컨텐츠가 표시됩니다. |
| title-loc-key | 스트링 | 로컬화된 제목 스트링을 위한 키입니다. 앱의 Localizable.strings 파일로부터 제목을 가져오기 위해 제목 키 대신 이 키를 구체화하시기 바랍니다. 값은 strings 파일에 있는 키의 이름을 포함해야 합니다. |
| title-loc-args | strings의 배열 | 변수를 제목 스트링으로 교체하는 값을 포함하는 strings의 배열입니다. title-loc-key로 구체화된 스트링에서의 %@ 문자는 이 배열로부터 값이 교체됩니다. 배열의 첫 번째 아이템은 %@ 문자자의 첫 번째 인스턴스를 스트링으로 교체하고, 두 번째 아이템은 두 번째 인스턴스를 교체합니다. 이후도 마찬가지입니다. |
| subtitle-loc-key | 스트링 | 로컬화된 서브타일틀 스트링을 위한 키입니다. 서브타이틀 키 대신 이 키를 사용해서 앱의 Localizable.strings 파일로부터 서브타이틀을 가져오시기 바랍니다. 값은 strings 파일에 있는 키의 이름을 포함해야 합니다. |
| subtitle-loc-args | strings의 배열 | 변수를 제목 스트링으로 교체하는 값을 포함하는 strings의 배열입니다. subtitle-loc-key로 구체화된 스트링에서의 %@ 문자는 이 배열로부터 값이 교체됩니다. 배열의 첫 번째 아이템은 %@ 문자의 첫 번째 인스턴스를 스트링으로 교체하고, 두 번째 아이템은 두 번째 인스턴스를 교체합니다. 이후도 마찬가지입니다. |
| loc-key | 스트링 | 로컬화된 메시지 스트링을 위한 키입니다. 바디 키 대신 이 키를 사용해서 앱의 Localizable.strings 파일로부터 메시지 텍스트를 가져오시기 바랍니다. 값은 strings 파일의 키 이름을 포함해야 합니다. |
| loc-args | strings의 배열 | 변수를 메시지 텍스트로 교체하는 값을 포함하는 strings의 배열입니다. loc-key로 구체화된 스트링에서의 %@ 문자는 이 배열로부터 값이 교체됩니다. 배열의 첫 번째 아이템은 %@ 문자의 첫 번째 인스턴스를 스트링으로 교체하고, 두 번째 아이템은 두 번째 인스턴스를 교체합니다. 이후도 마찬가지입니다. |
Table 3은 소리 딕셔너리에 포함시킬 수 있는 키를 리스트로 보여주고 있습니다. 이러한 키를 사용해서 중요한 알림을 위한 소리를 설정하시기 바랍니다.
Table 3 Keys to include in the sound dictionary
| Key | Value type | Description |
|---|---|---|
| critical | 숫자 | critical 알림 플래그입니다. critical 알림을 활성화하려면 1로 설정합니다. |
| 이름 | 스트링 | 앱의 메인 번들 혹은 앱 컨테이너 디렉토리의 Library/Sounds 폴더에 있는 소리 파일의 이름입니다. 시스템 소리를 재생하려면 스트링 "default"를 구체화해야 합니다. 소리 준비 방법에 대한 더 많은 정보는 UNNotificationSound를 보시기 바랍니다. |
| 볼륨 | 숫자 | critical 알림 소리에 대한 볼륨입니다. 이 값을 0(소리없음)에서 1(최대 볼륨) 사이로 설정하시기 바랍니다. |
UNNotificationSound
https://developer.apple.com/documentation/usernotifications/unnotificationsound
https://velog.io/@panther222128/UNNotificationSound
Figure 2는 배너 노티피케이션에서 제목, 서브타이틀, 바디 컨텐트를 기본값으로 둔 것을 보여줍니다. 알림의 모양을 커스터마이징 하려면 Customizing the Appearance of Notifications에서 설명하고 있는 것처럼 노티피케이션 컨텐트 앱 확장을 사용해야 합니다.
Customizing the Appearance of Notifications
https://developer.apple.com/documentation/usernotificationsui/customizing_the_appearance_of_notifications
https://velog.io/@panther222128/Customizing-the-Appearance-of-Notifications
Figure 2 The default appearance of the notification content
See Also
Server Tasks
Sending Notification Requests to APNs
애플 푸시 노티피케이션 서비스(APNs)에 원격 노티피케이션 페이로드 및 기기 토큰 정보를 전송합니다.
https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns
https://velog.io/@panther222128/Sending-Notification-Requests-to-APNs
Handling Notification Responses from APNs
APNs 서버가 반환한 상태 코드에 응답합니다.
https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/handling_notification_responses_from_apns
https://velog.io/@panther222128/Handling-Notification-Responses-from-APNs
Pushing Background Updates to Your App
앱을 깨우고 백그라운드에서 업데이트하는 노티피케이션을 전달합니다.
https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app
https://velog.io/@panther222128/Pushing-Background-Updates-to-Your-App
