[번역] UNUserNotifications / Generating a Remote Notification (애플 공식 문서)

Overview

푸시 알림은 JSON 페이로드 형태로 사용자에게 중요한 정보를 전달합니다. 페이로드에서 수행하려는 사용자 상호작용의 종류(알림, 사운드, 배지)가 지정되며, 앱이 알림에 응답하는 데 필요한 모든 커스텀 데이터가 포함됩니다.

« figure src=“media-2953613.png” align=“center” »

푸시 알림 페이로드에는 Apple이 정의한 키와 그에 해당하는 커스텀 값이 포함됩니다. 또한 알림에 맞게 직접 정의한 커스텀 키와 값을 추가할 수도 있습니다. Apple 푸시 알림 서버(APNs)는 페이로드의 전체 크기가 다음 제한을 초과하면 알림을 거부합니다.

• VolP(인터넷 전화) 알림의 경우, 최대 페이로드의 크기는 5KB (5120바이트)입니다.

• 그외 모든 푸시 알림의 경우, 최대 페이로드의 크기는 4KB (4096바이트)입니다.

Create the JSON payload

푸시 알림의 페이로드는 JSON 딕셔너리로 생성합니다. 이 딕셔너리 안에는 aps 키를 포함해야 하며, aps 키의 값은 아래 표에 나열된 하나 이상의 Apple이 정의한 추가 키들을 담은 딕셔너리입니다. 이 키들을 통해 시스템에 알림을 표시하거나, 사운드를 재생하거나, 앱 아이콘에 배지를 적용하도록 지시할 수 있습니다. 또한 시스템이 알림을 백그라운드에서 조용히 처리하도록 지시할 수 있습니다. 더 자세한 내용은 Pushing background updates to your App을 참고하세요.

Apple이 정의한 키 외에도, 페이로드에 커스텀 키를 추가해 소량의 데이터를 앱이나 Notification Service App Extension, Notification Content App Extension으로 전달할 수 있습니다. 커스텀 키의 값은 딕셔너리, 배열, 문자열, 숫자, 불리언과 같은 기본 타입이어야 합니다. 이렇게 추가한 커스텀 키는 UNNotificationContent 객체의 userInfo 딕셔너리에서 확인할 수 있습니다.

일반적으로 커스텀 키는 코드에서 알림을 처리하는 데 도움을 줍니다. 예를 들어, 앱 전용 데이터를 조회할 때 사용할 수 있는 식별자를 포함할 수 있습니다. 커스텀 키는 aps 딕셔너리와 같은 계층에 추가해야 합니다.

아래는 사용자를 게임에 초대하는 알림 메시지를 표시하도록 하는 알림 페이로드 예시를 보여줍니다. category 키가 미리 등록된 UNUserNotificationCategory 객체를 가리키는 경우, 시스템은 알림에 액션 버튼을 추가합니다. 예를 들어, 여기서는 category에 즉시 게임을 시작할 수 있는 play 액션이 포함되어 있습니다. 커스텀 gameID 키에는 게임 초대를 가져올 때 사용할 수 있는 식별자가 담겨 있습니다.

{
    "aps" : {
        "alert" : {
            "title" : "Game Request",
            "subtitle" : "Five Card Draw",
            "body" : "Bob wants to play poker"
        },
        "category" : "GAME_INVITATION"
    },
    "gameID" : "12345678"
}

아래는 앱 아이콘에 배지를 표시하고 사운드를 재생하는 알림 페이로드 예시를 보여줍니다. 지정한 사운드 파일은 사용자의 기기에 있어야 하며, 앱 번들 또는 Library/Sounds 폴더에 위치해야 합니다. messageID 키에는 알림을 발생시킨 메시지를 식별하기 위한 앱 전용 정보가 담겨 있습니다.

{
    "aps" : {
        "badge" : 9,
        "sound" : "bingbong.tiff"
    },
    "messageID" : "ABCDEFGHIJ"
}

알림에 사용할 사운드를 생성하는 방법에 대한 더 자세한 내용은 UNNotificationSound를 참고하세요.

Important: 알림 페이로드에는 고객 정보나 신용카드 번호와 같은 민감한 데이터를 포함하지 마세요. 불가피하게 고객 정보나 민감한 데이터를 포함해야 한다면, 페이로드에 추가하기 전에 암호화를 해야 합니다. 그리고 사용자 기기에서 Notification Service App Extension을 사용해 해당 데이터를 복호화할 수 있습니다. 더 자세한 내용은 Modifying content in newly delivered notifications를 참고하세요.

Localize your alert messages

푸시 알림의 콘텐츠를 현지화하는 방법에는 두 가지가 있습니다:

• 페이로드에 현지화된 문자열을 직접 포함하는 방법

• 앱 번들에 현지화된 문자열을 추가하고, 시스템이 표시할 문자열을 선택하도록 하는 방법

현지화된 문자열을 직접 페이로드에 넣는 방식은 더 많은 유연성을 제공하지만, 제공자 서버(provider server)에서 사용자의 선호 언어를 추적해야 합니다. 문자열을 서버에서 제공하기 때문에 서버는 어떤 언어를 사용할지 알아야 합니다. 사용자의 기기에서 NSLocale의 preferredLanguages 속성을 확인하여 사용자의 선호 언어를 가져올 수 있습니다. 그런 다음 앱이 해당 정보를 서버로 전달할 수 있습니다.

알림 메시지의 텍스트가 미리 정해져 있다면, 앱 번들의 Localizable.strings 파일에 메시지 문자열을 저장하고 title-loc-key, subtitle-loc-key, loc-key 키를 사용하여 표시할 문자열을 지정할 수 있습니다. 현지화된 문자열에는 플레이스 홀더를 포함할 수 있으며, 이를 통해 최종 문자열에 동적으로 콘텐츠를 삽입할 수 있습니다. 아래는 앱에서 제공한 문자열을 기반으로 생성된 메시지를 포함하는 페이로드 예시를 보여줍니다. loc-args 키에는 플레이스 홀더를 대체할 변수들을 담은 배열이 포함됩니다.

{
    "aps" : {
        "alert" : {
            "loc-key" : "GAME_PLAY_REQUEST_FORMAT",
            "loc-args" : [ "Shelly", "Rick" ] 
        }
    }
}

현지화된 콘텐츠에 사용하는 키에 대한 더 자세한 내용은 아래 섹션을 참고하세요.

Payload key reference

아래 표에는 aps 딕셔너리에 포함할 수 있는 키들이 나와 있습니다. 사용자와 상호작용하려면 alert, badge, sound 키를 포함해야 합니다. aps 딕셔너리에 커스텀 키를 추가하지 마세요. APNs는 커스텀 키를 무시합니다. 대신, aps 딕셔너리와 같은 계층에 커스텀 키를 추가해야 합니다.

아래 표는 alert 딕셔너리에 포함할 수 있는 키들이 나와 있습니다. 이 문자열들을 사용해 알림 배너에 포함할 제목과 메시지를 지정할 수 있습니다.

아래 표는 sound 딕셔너리에 포함할 수 있는 키들이 나와 있습니다. 이 키들을 사용해 긴급한 알림에 재생할 사운드를 설정할 수 있습니다.

아래 그림은 배너 알림에서 제목, 부제목, 본문 콘텐츠가 기본적으로 배치되는 위치를 보여줍니다. 알림의 모양을 사용자화하려면, Customizing the Appearance of Notifications에 설명된 대로 Notification Content App Extension를 사용하면 됩니다.