Notification Payload — ano ito, JSON structure at pag-parse

Ano ang Notification Payload

Notification Payload (payload ng notification) — ay isang JSON object na ipinapadala ng server sa APNS (Apple Push Notification Service) para sa paghahatid sa isang iOS device. Ang payload ay naglalaman ng lahat ng data na kailangan ng system para ipakita ang notification: pamagat, text, tunog, badge at metadata para sa background processing. Ang structure ng payload ay mahigpit na kinokontrol ng Apple at may kasamang mandatory key para sa tamang pagproseso ng system.

Papel ng payload sa paghahatid ng push

Kapag nagpadala ang server ng push notification sa pamamagitan ng HTTP/2 API ng APNS, ang request ay naglalaman ng authorization headers at JSON body — ang payload. Sinusuri ng APNS ang validity ng payload: kung ang JSON ay hindi wasto o lumampas sa limitasyon ng laki, ang Apple server ay nagbabalik ng error na 400 Bad Request. Pagkatapos ng validation, inihahatid ng APNS ang payload sa device, kung saan ito ay ini-parse ng iOS system at tinutukoy kung paano poproseso ang notification — magpakita ng banner, magsimula ng background task, o magpatugtog ng tunog.

Ebolusyon ng format ng payload

Ang APNS payload format ay nag-evolve mula sa simpleng text payload sa iOS 2 patungo sa multi-component na JSON structure sa modernong bersyon. iOS 10 ay nagdala ng suporta para sa media attachments sa pamamagitan ng mutable-content, iOS 12 ay nagdagdag ng pagpapangkat ng notification sa pamamagitan ng thread-id, at iOS 15 ay nagpakilala ng supports-live-activities para sa Live Activities. Ngayon, ang payload ay maaaring maglaman ng hanggang 15 iba't ibang key depende sa nais na pag-uugali ng notification.

Structure ng APNS payload: mandatory at opsyonal na key

Ang root object ng payload ay naglalaman ng aps dictionary at opsyonal na custom field sa itaas na antas. Ang aps dictionary ay ang tanging mandatoryong elemento, ngunit sa loob nito ay maaaring may iba't ibang kombinasyon ng key depende sa uri ng notification: alert, badge, sound, content-available, mutable-content, interruption-level at iba pa.

Alert key: string at dictionary format

Ang alert key ay maaaring isang simpleng string (na nagiging body ng notification) o isang dictionary na may mga field na title, subtitle, body. Ang dictionary format ay nagpapahintulot sa pagtatakda ng pamagat at sub-title nang hiwalay sa pangunahing text. Para sa lokalisadong notification, ginagamit ang mga key na title-loc-key, title-loc-args, loc-key, loc-args na tumutukoy sa Localizable.strings ng app. Ito ay nagpapahintulot sa pagpapadala ng payload nang walang text sa isang partikular na wika — ang app ang naglalagay ng pagsasalin.

Pamamahala ng pagkaantala: interruption-level at relevance-score

Simula sa iOS 15, idinagdag ng Apple ang Focus Mode mechanism na nangangailangan ng developer na tukuyin ang antas ng pagkaantala ng notification. interruption-level ay tumatanggap ng mga halaga: passive (walang tunog, walang paggising ng screen), active (standard na pag-uugali), time-sensitive (tumagos sa focus, nangangailangan ng special entitlement) at critical (medikal/emergency na sitwasyon). Ang key na relevance-score (0–1) ay tumutulong sa Focus system na mag-ranking ng notification sa loob ng isang kategorya.

Pagpapangkat ng notification sa pamamagitan ng thread-id

Ang thread-id key ay pinagsasama ang mga notification sa mga grupo sa Notification Center. Lahat ng notification na may parehong thread-id ay ipinapakita bilang isang grupo na maaaring palawakin ng user. Ito ay lalong kapaki-pakinabang para sa messaging apps, kung saan ang mga mensahe mula sa isang contact ay pinagsama-sama, o para sa mga app na nagpapadala ng maraming notification ng parehong uri.

Custom na field at pagpapadala ng data

Custom na field — ay anumang key sa labas ng aps dictionary na idinadagdag ng developer para sa pagpapadala ng karagdagang data sa device. Isinasama ng server ang mga ito sa root JSON object ng payload, at natatanggap ng app ang mga ito sa pamamagitan ng userInfo sa UNNotificationContent. Ang custom na field ay hindi dapat dumoble sa mga pangalan ng key mula sa aps upang maiwasan ang conflict sa pag-parse.

Mga limitasyon sa custom na data

Ang pangunahing limitasyon — ang kabuuang laki ng payload ay hindi dapat lumampas sa 4096 bytes. Ang custom na field ay nakikipagkumpitensya para sa limitasyong ito sa mandatoryong aps key, kaya mahalagang bawasan ang laki ng ipinadalang data. Gumamit ng maiikling pangalan ng key (hal. uid sa halip na user-id), iwasan ang malalaking JSON structure at magpadala lamang ng identifier, hindi kumpletong data object.

Seguridad at validation ng custom na field

Ang custom na field ay nagmumula sa server at hindi dapat pagkatiwalaan nang walang pagsusuri. Palaging i-validate ang mga uri at halaga ng custom na field sa pag-parse: suriin ang pagkakaroon ng key sa pamamagitan ng optional binding, i-convert sa inaasahang uri gamit ang as? String/Int/Dictionary at pangasiwaan ang kaso ng nawawalang halaga. Huwag kailanman gumamit ng force unwrap (!) para sa data mula sa payload — ang server ay maaaring magpadala ng maling data at ang app ay magca-crash.

{
    "aps": {
        "alert": {
            "title": "Bagong mensahe",
            "body": "Kamusta! Kumusta ka?"
        },
        "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"
}

Rekomendasyon sa pagpapangalan ng custom na field

Gumamit ng pare-parehong istilo ng pagpapangalan para sa custom na field sa lahat ng payload ng proyekto. kebab-case (message-type) o camelCase (messageType) — parehong approach ay katanggap-tanggap, ngunit mahalagang sundin ang isa sa loob ng proyekto. Iwasan ang mahabang pangalan: uid sa halip na user-identifier, img sa halip na profile-image-url. Bawat character sa pangalan ng key ay isang byte mula sa limitasyong 4096.

Halimbawa ng payload para sa iba't ibang uri ng notification

Iba't ibang senaryo ng push notification ay nangangailangan ng iba't ibang kombinasyon ng key sa payload. Tingnan natin ang ilang tipikal na halimbawa: simpleng text notification, notification na may lokalisasyon, Silent Push at Rich Notification na may media attachment.

Simpleng text notification

Basic payload na may text at tunog — minimal na configuration para ipakita ang notification sa user. Alert bilang string ay nagbibigay ng maikling mensahe, sound default ay nagpapatugtog ng standard system sound. Ang badge ay opsyonal at nagtatakda ng counter sa icon. Ang category at thread-id ay idinadagdag para sa pagpapangkat at interaktibidad.

{
    "aps": {
        "alert": "Paalala: meeting sa 15 minuto",
        "badge": 3,
        "sound": "default"
    }
}

Notification na may lokalisasyon

Para sa pagpapadala sa mga device na may iba't ibang wika, gumamit ng lokalisasyon key sa halip na nakapirming text. title-loc-key ay tumutukoy sa isang key sa Localizable.strings ng app, at ang title-loc-args ay nagpapalit ng mga argumento. Ito ay nagpapahintulot sa pagpapadala ng isang payload sa lahat ng device, at ang app mismo ang nagpapakita ng text sa tamang wika.

{
    "aps": {
        "alert": {
            "title-loc-key": "NEW_MESSAGE_TITLE",
            "title-loc-args": ["Anna"],
            "loc-key": "NEW_MESSAGE_BODY",
            "loc-args": ["Kamusta!"]
        },
        "sound": "message.caf"
    }
}

Silent Push na may background synchronization

Para sa background synchronization nang hindi nagpapakita ng notification, ginagamit ang content-available: 1 at kawalan ng alert. Ang custom na field ay nagpapahiwatig ng uri ng operasyon at data para sa pagproseso. Ina-activate ng system ang app sa background, tinatawag ang didReceiveRemoteNotification na may fetchCompletionHandler, at ginagawa ng app ang synchronization.

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

Rich Notification na may larawan

Para sa pagpapakita ng media attachment, kailangan ang mutable-content: 1 para i-activate ang Service Extension at URL ng larawan sa custom na field. mutable-content: 1 ay nag-signal sa system na simulan ang UNNotificationServiceExtension, na magda-download ng larawan mula sa URL at idadagdag ito bilang UNNotificationAttachment. Ang category ay tumutukoy sa rehistradong kategorya para sa pagpapakita ng action buttons.

{
    "aps": {
        "alert": {
            "title": "Bagong produkto",
            "body": "Tingnan ang bagong koleksyon"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Pagproseso at pag-parse ng payload sa app

UNNotificationContent.userInfo ay naglalaman ng kumpletong diksyunaryo ng natanggap na payload pagkatapos ng pagproseso ng system. Ang app ay may access sa payload sa UNUserNotificationCenter delegate kapag nakatanggap ng notification (sa foreground), kapag nag-tap sa notification, at gayundin sa Service Extension at Content Extension. Ang tamang pag-parse ay mandatory para sa pag-extract ng custom na data at pagtukoy ng mga susunod na aksyon.

Pag-parse sa AppDelegate kapag nag-tap sa notification

Kapag nag-tap ang user sa notification, tinatawag ng system ang didReceive response method sa UNUserNotificationCenterDelegate. Sa response.notification.request.content.userInfo ay matatagpuan ang kumpletong payload. Kinukuha ng developer ang custom na field, tinutukoy ang uri ng aksyon (hal. buksan ang chat, pumunta sa produkto) at tinatawag ang kaukulang navigation sa app.

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()
}

Validation ng payload sa Service Extension

Ang Service Extension ay tumatanggap ng payload bago ipakita ang notification at maaari itong baguhin. Validation ng payload — unang hakbang sa didReceive: suriin ang pagkakaroon ng mandatoryong custom na field, kawastuhan ng URL para sa attachment at uri ng data. Kung hindi wasto ang payload, agad na tawagan ang completion handler na may orihinal na content, huwag mag-aksaya ng oras sa walang kwentang pagproseso.

Pag-log at pag-monitor ng payload

Para sa debugging ng push notification sa produksyon, gumamit ng structured logging ng payload. OSLog ay nagpapahintulot sa pag-log ng payload na may kategoryang notifications at debug level. Sa server side, subaybayan ang APNS response: ang matagumpay na response ay naglalaman ng apns-id para sa pagtutugma sa ipinadalang payload, at ang error na 400 ay nagpapahiwatig ng hindi wastong JSON o labis na laki.