Notification Payload — шта је то, JSON структура и парсирање

Шта је Notification Payload

Notification Payload (пейлоуд обавештења) — је JSON објекат који сервер шаље APNS-у (Apple Push Notification Service) ради доставе на iOS уређај. Пейлоуд садржи све податке потребне систему за приказ обавештења: наслов, текст, звук, badge и метаподатке за обраду у позадини. Структура пейлоуда је строго регулисана од стране Apple-а и укључује обавезне кључеве за правилну обраду од стране система.

Улога пейлоуда у достави push-а

Када сервер шаље push обавештење путем HTTP/2 API APNS-а, захтев садржи заглавља ауторизације и JSON тело — пейлоуд. APNS проверава валидност пейлоуда: ако је JSON неисправан или премашује ограничење величине, Apple сервер враћа грешку 400 Bad Request. Након валидације, APNS доставља пейлоуд на уређај, где га iOS систем парсира и одређује како да обради обавештење — прикаже банер, покрене позадински задатак или репродукује звук.

Еволуција формата пейлоуда

Формат APNS пейлоуда је еволуирао од једноставног текстуалног пейлоуда у iOS 2 до вишекомпонентне JSON структуре у модерним верзијама. iOS 10 је донела подршку за медијске прилоге путем mutable-content, iOS 12 је додала груписање обавештења путем thread-id, а iOS 15 је увео supports-live-activities за Live Activities. Данас пейлоуд може садржати до 15 различитих кључева у зависности од потребног понашања обавештења.

Структура APNS пейлоуда: обавезни и опционални кључеви

Корени објекат пейлоуда садржи речник aps и опционална прилагођена поља на горњем нивоу. Речник aps је једини обавезни елемент, али унутар њега могу постојати различите комбинације кључева у зависности од типа обавештења: alert, badge, sound, content-available, mutable-content, interruption-level и други.

alert кључ: стринг и речник формат

alert кључ може бити једноставан стринг (који постаје тело обавештења) или речник са пољима title, subtitle, body. Речник формат омогућава постављање наслова и поднаслова одвојено од главног текста. За локализована обавештења користе се кључеви title-loc-key, title-loc-args, loc-key, loc-args, који упућују на Localizable.strings апликације. Ово омогућава слање пейлоуда без текста на одређеном језику — апликација замењује превод.

Управљање прекидима: interruption-level и relevance-score

Почевши од iOS 15, Apple је додао механизам Focus Mode, који захтева од програмера да наведе ниво прекида обавештења. interruption-level прихвата вредности: passive (без звука, без буђења екрана), active (стандардно понашање), time-sensitive (пробија фокус, захтева special entitlement) и critical (медицинске/хитне ситуације). Кључ relevance-score (0–1) помаже Focus систему да рангира обавештења у оквиру једне категорије.

Груписање обавештења путем thread-id

Кључ thread-id обједињује обавештења у групе у Notification Center-у. Сва обавештења са истим thread-id приказују се као једна група коју корисник може да прошири. Ово је посебно корисно за апликације за размену порука, где се поруке од једног контакта групишу заједно, или за апликације које шаљу много обавештења истог типа.

Прилагођена поља и пренос података

Прилагођена поља — су сви кључеви ван речника aps које програмер додаје за пренос додатних података на уређај. Сервер их укључује у корени JSON објекат пейлоуда, а апликација их прима путем userInfo у UNNotificationContent. Прилагођена поља не би требало да дуплирају имена кључева из aps-а да би се избегли конфликти при парсирању.

Ограничења за прилагођене податке

Главно ограничење — укупна величина пейлоуда не сме да прелази 4096 бајтова. Прилагођена поља се такмиче за ово ограничење са обавезним aps кључевима, зато је важно минимизирати величину пренетих података. Користите кратке називе кључева (нпр. „uid“ уместо „user-id“), избегавајте велике JSON структуре и преносите само идентификаторе, не пуне објекте података.

Сигурност и валидација прилагођених поља

Прилагођена поља долазе са сервера и не треба им веровати без провере. Увек валидирајте типове и вредности прилагођених поља при парсирању: проверавајте присуство кључа путем optional binding, конвертујте у очекивани тип помоћу as? String/Int/Dictionary и обрадите случај недостатка вредности. Никада не користите force unwrap (!) за податке из пейлоуда — сервер може послати неисправне податке и апликација ће crash-овати.

{
    "aps": {
        "alert": {
            "title": "Нова порука",
            "body": "Здраво! Како си?"
        },
        "badge": 5,
        "sound": "default",
        "category": "message",
        "thread-id": "chat_4521",
        "mutable-content": 1
    },
    "sender-id": "user_789",
    "chat-id": "chat_4521",
    "message-type": "text",
    "image-url": "https://cdn.example.com/img.jpg"
}

Препоруке за именовање прилагођених поља

Користите јединствени стил именовања прилагођених поља у свим пейлоудима пројекта. kebab-case (message-type) или camelCase (messageType) — оба приступа су прихватљива, али је важно држати се једног у оквиру пројекта. Избегавајте дуга имена: „uid“ уместо „user-identifier“, „img“ уместо „profile-image-url“. Сваки знак у имену кључа је бајт из лимита 4096.

Примери пейлоуда за различите типове обавештења

Различити сценарији push обавештења захтевају различите комбинације кључева у пейлоуду. Размотримо неколико типичних примера: једноставно текстуално обавештење, обавештење са локализацијом, Silent Push и Rich Notification са медијским прилогом.

Једноставно текстуално обавештење

Основни пейлоуд са текстом и звуком — минимална конфигурација за приказ обавештења кориснику. Alert као стринг даје кратку поруку, sound default репродукује стандардни системски звук. Badge је опционалан и поставља бројач на иконици. category и thread-id се додају за груписање и интерактивност.

{
    "aps": {
        "alert": "Подсетник: састанак за 15 минута",
        "badge": 3,
        "sound": "default"
    }
}

Обавештење са локализацијом

За слање на уређаје са различитим језицима користите кључеве локализације уместо чврсто задатог текста. title-loc-key упућује на кључ у Localizable.strings апликације, а title-loc-args замењује аргументе. Ово омогућава слање једног пейлоуда на све уређаје, а апликација сама приказује текст на одговарајућем језику.

{
    "aps": {
        "alert": {
            "title-loc-key": "NEW_MESSAGE_TITLE",
            "title-loc-args": ["Ана"],
            "loc-key": "NEW_MESSAGE_BODY",
            "loc-args": ["Здраво!"]
        },
        "sound": "message.caf"
    }
}

Silent Push са позадинском синхронизацијом

За позадинску синхронизацију без приказа обавештења користи се content-available: 1 и одсуство alert-а. Прилагођена поља указују на тип операције и податке за обраду. Систем активира апликацију у позадини, позива didReceiveRemoteNotification са fetchCompletionHandler, и апликација извршава синхронизацију.

{
    "aps": {
        "content-available": 1
    },
    "sync-type": "invalidate-cache",
    "timestamp": "2026-07-03T12:00:00Z"
}

Rich Notification са сликом

За приказ медијског прилога потребан је mutable-content: 1 за активацију Service Extension-а и URL слике у прилагођеном пољу. mutable-content: 1 сигнализира систему да покрене UNNotificationServiceExtension, који ће преузети слику са URL-а и додати је као UNNotificationAttachment. category указује на регистровану категорију за приказ дугмади за радње.

{
    "aps": {
        "alert": {
            "title": "Нови производ",
            "body": "Погледајте нову колекцију"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Обрада и парсирање пейлоуда у апликацији

UNNotificationContent.userInfo садржи пун речник примљеног пейлоуда након обраде од стране система. Апликација приступа пейлоуду у делегату UNUserNotificationCenter-а при пријему обавештења (у предњем плану), при клику на обавештење, као и у Service Extension-у и Content Extension-у. Исправно парсирање је обавезно за издвајање прилагођених података и одређивање даљих радњи.

Парсирање у AppDelegate-у при клику на обавештење

Када корисник кликне на обавештење, систем позива метод didReceive response у UNUserNotificationCenterDelegate-у. У response.notification.request.content.userInfo се налази пун пейлоуд. Програмер издваја прилагођена поља, одређује тип радње (нпр. отварање ћаскања, прелазак на производ) и позива одговарајућу навигацију у апликацији.

func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse,
    withCompletionHandler completionHandler: @escaping () -> Void
) {
    let userInfo = response.notification
        .request.content.userInfo

    guard let chatId = userInfo["chat-id"] as? String
    else {
        completionHandler()
        return
    }

    let messageType = userInfo["message-type"]
        as? String ?? "text"

    NavigationRouter.shared.navigate(
        to: .chat(chatId: chatId,
                  messageType: messageType))
    completionHandler()
}

Валидација пейлоуда у Service Extension-у

Service Extension прима пейлоуд пре приказа обавештења и може га модификовати. Валидација пейлоуда — први корак у didReceive: проверите присуство обавезних прилагођених поља, исправност URL-а за прилоге и тип података. Ако је пейлоуд неважећи, одмах позовите completion handler са оригиналним садржајем, не губећи време на бескорисну обраду.

Логовање и мониторинг пейлоуда

За отклањање грешака push обавештења на продукцији користите структурирано логовање пейлоуда. OSLog омогућава логовање пейлоуда са категоријом „notifications“ и debug нивоом. На серверској страни пратите APNS одговоре: успешан одговор садржи apns-id за подударање са послатим пейлоудом, а грешка 400 указује на неисправан JSON или прекорачење величине.