Notification Payload — mi ez, JSON szerkezet és feldolgozás

Mi az a Notification Payload

Notification Payload (az értesítés payloadja) — egy JSON-objektum, amelyet a szerver az APNS (Apple Push Notification Service) felé küld egy iOS-eszközre történő kézbesítés céljából. A payload tartalmazza a rendszer által az értesítés megjelenítéséhez szükséges összes adatot: címet, szöveget, hangot, badge-t és metaadatokat a háttérfeldolgozáshoz. A payload szerkezetét az Apple szigorúan szabályozza, és kötelező kulcsokat tartalmaz a rendszer általi helyes feldolgozáshoz.

A payload szerepe a push kézbesítésében

Amikor a szerver push-értesítést küld az APNS HTTP/2 API-ján keresztül, a kérés hitelesítési fejléceket és egy JSON-törzset — a payloadot — tartalmaz. Az APNS ellenőrzi a payload érvényességét: ha a JSON helytelen vagy meghaladja a méretkorlátot, az Apple szerver 400 Bad Request hibát ad vissza. Az érvényesítés után az APNS kézbesíti a payloadot az eszközre, ahol az iOS rendszer elemzi és meghatározza, hogyan dolgozza fel az értesítést — jelenítsen meg egy banner-t, indítson el egy háttérfeladatot vagy játsszon le egy hangot.

A payload formátumának fejlődése

Az APNS payload formátuma az iOS 2 egyszerű szöveges payloadjától a modern verziók többkomponensű JSON-struktúrájáig fejlődött. Az iOS 10 a mutable-content segítségével támogatást hozott a média-mellékletekhez, az iOS 12 a thread-id segítségével csoportosítást adott az értesítésekhez, az iOS 15 pedig bevezette a supports-live-activities-t a Live Activities számára. Ma a payload az értesítés kívánt viselkedésétől függően akár 15 különböző kulcsot is tartalmazhat.

Az APNS payload szerkezete: kötelező és opcionális kulcsok

A payload gyökér objektuma tartalmazza az aps szótárt és opcionális egyedi mezőket a felső szinten. Az aps szótár az egyetlen kötelező elem, de benne az értesítés típusától függően különböző kulcskombinációk lehetnek: alert, badge, sound, content-available, mutable-content, interruption-level és mások.

Az alert kulcs: string és szótár formátum

Az alert kulcs lehet egy egyszerű karakterlánc (amely az értesítés törzsévé válik) vagy egy szótár a title, subtitle, body mezőkkel. A szótár formátum lehetővé teszi a cím és alcím külön beállítását a fő szövegtől. A lokalizált értesítésekhez a title-loc-key, title-loc-args, loc-key, loc-args kulcsok használatosak, amelyek az alkalmazás Localizable.strings fájljára hivatkoznak. Ez lehetővé teszi payload küldését egy adott nyelvű szöveg nélkül — az alkalmazás helyettesíti be a fordítást.

Megszakítások kezelése: interruption-level és relevance-score

Az iOS 15-től kezdve az Apple hozzáadta a Focus Mode mechanizmust, amely megköveteli a fejlesztőtől az értesítés megszakítási szintjének megadását. Az interruption-level a következő értékeket fogadja el: passive (hang nélkül, képernyő felébresztése nélkül), active (alapértelmezett viselkedés), time-sensitive (áttöri a fókuszt, speciális jogosultságot igényel) és critical (orvosi/vészhelyzetek). A relevance-score (0–1) kulcs segíti a Focus rendszert az értesítések rangsorolásában egy kategórián belül.

Értesítések csoportosítása thread-id segítségével

A thread-id kulcs csoportokba egyesíti az értesítéseket a Notification Centerben. Minden értesítés azonos thread-id-vel egyetlen csoportként jelenik meg, amelyet a felhasználó kibonthat. Ez különösen hasznos az üzenetküldő alkalmazásokban, ahol egy kapcsolattartó üzenetei össze lesznek csoportosítva, vagy az olyan alkalmazásokban, amelyek sok azonos típusú értesítést küldenek.

Egyedi mezők és adatátvitel

Egyedi mezők — az aps szótáron kívüli kulcsok, amelyeket a fejlesztő ad hozzá további adatok eszközre történő továbbításához. A szerver belefoglalja őket a payload gyökér JSON-objektumába, az alkalmazás pedig a userInfo-n keresztül kapja meg őket a UNNotificationContent-ben. Az egyedi mezők nem duplikálhatják az aps kulcsneveit a feldolgozás során fellépő konfliktusok elkerülése érdekében.

Az egyedi adatok korlátozásai

A fő korlátozás — a payload teljes mérete nem haladhatja meg a 4096 bájtot. Az egyedi mezők versengenek ezért a korlátért a kötelező aps kulcsokkal, ezért fontos minimalizálni az átvitt adatok méretét. Használjon rövid kulcsneveket (pl. uid a user-id helyett), kerülje a nagy JSON-struktúrákat, és csak azonosítókat küldjön, ne teljes adatobjektumokat.

Az egyedi mezők biztonsága és érvényesítése

Az egyedi mezők a szerverről érkeznek, és nem szabad ellenőrzés nélkül megbízni bennük. Mindig érvényesítse az egyedi mezők típusait és értékeit a feldolgozás során: ellenőrizze a kulcs meglétét optional binding segítségével, konvertálja a várt típusra as? String/Int/Dictionary segítségével, és kezelje az érték hiányának esetét. Soha ne használjon force unwrap (!) -ot a payload adataira — a szerver hibás adatokat küldhet, és az alkalmazás összeomlik.

{
    "aps": {
        "alert": {
            "title": "Új üzenet",
            "body": "Szia! Hogy vagy?"
        },
        "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"
}

Ajánlások az egyedi mezők elnevezéséhez

Használjon egységes elnevezési stílust az egyedi mezőkhöz a projekt összes payloadjában. kebab-case (message-type) vagy camelCase (messageType) — mindkét megközelítés elfogadható, de fontos, hogy a projekten belül egyet kövessen. Kerülje a hosszú neveket: uid a user-identifier helyett, img a profile-image-url helyett. A kulcsnév minden karaktere egy bájt a 4096-os korlátból.

Payload példák különböző értesítéstípusokhoz

Különböző forgatókönyvek push-értesítésekhez különböző kulcskombinációkra van szükség a payloadban. Vizsgáljunk meg néhány tipikus példát: egyszerű szöveges értesítés, lokalizált értesítés, Silent Push és Rich Notification média-melléklettel.

Egyszerű szöveges értesítés

Alap payload szöveggel és hanggal — minimális konfiguráció az értesítés megjelenítéséhez a felhasználónak. Alert karakterláncként rövid üzenetet ad, a sound default a szabványos rendszerhangot játssza le. A badge opcionális, és számlálót állít be az ikonon. A category és thread-id a csoportosításhoz és interaktivitáshoz kerül hozzáadásra.

{
    "aps": {
        "alert": "Emlékeztető: találkozó 15 perc múlva",
        "badge": 3,
        "sound": "default"
    }
}

Lokalizált értesítés

Különböző nyelvű eszközökre történő küldéshez használjon lokalizációs kulcsokat a rögzített szöveg helyett. title-loc-key az alkalmazás Localizable.strings fájljában lévő kulcsra hivatkozik, a title-loc-args pedig helyettesíti az argumentumokat. Ez lehetővé teszi egyetlen payload küldését minden eszközre, és az alkalmazás maga jeleníti meg a szöveget a megfelelő nyelven.

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

Silent Push háttér-szinkronizációval

Háttér-szinkronizációhoz az értesítés megjelenítése nélkül a content-available: 1 és az alert hiánya használatos. Az egyedi mezők jelzik a művelet típusát és a feldolgozandó adatokat. A rendszer aktiválja az alkalmazást a háttérben, meghívja a didReceiveRemoteNotification-t a fetchCompletionHandler-rel, és az alkalmazás elvégzi a szinkronizációt.

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

Rich Notification képpel

Média-melléklet megjelenítéséhez szükség van a mutable-content: 1-re a Service Extension aktiválásához és a kép URL-jére egy egyedi mezőben. mutable-content: 1 jelzi a rendszernek, hogy indítsa el a UNNotificationServiceExtension-t, amely letölti a képet az URL-ről és UNNotificationAttachmentként adja hozzá. A category egy regisztrált kategóriára mutat a műveleti gombok megjelenítéséhez.

{
    "aps": {
        "alert": {
            "title": "Új termék",
            "body": "Nézd meg az új kollekciót"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Payload feldolgozása és elemzése az alkalmazásban

UNNotificationContent.userInfo tartalmazza a fogadott payload teljes szótárát a rendszer általi feldolgozás után. Az alkalmazás a UNUserNotificationCenter delegáltjában fér hozzá a payloadhoz az értesítés fogadásakor (az előtérben), az értesítésre kattintáskor, valamint a Service Extension-ben és Content Extension-ben. A helyes feldolgozás kötelező az egyedi adatok kinyeréséhez és a további műveletek meghatározásához.

Feldolgozás az AppDelegate-ben értesítésre kattintáskor

Amikor a felhasználó egy értesítésre kattint, a rendszer meghívja a didReceive response metódust a UNUserNotificationCenterDelegate-ben. A response.notification.request.content.userInfo-ban található a teljes payload. A fejlesztő kinyeri az egyedi mezőket, meghatározza a művelet típusát (pl. chat megnyitása, termék megtekintése), és meghívja a megfelelő navigációt az alkalmazásban.

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

Payload érvényesítése a Service Extension-ben

A Service Extension az értesítés megjelenítése előtt kapja meg a payloadot, és módosíthatja azt. A payload érvényesítése — az első lépés a didReceive-ben: ellenőrizze a kötelező egyedi mezők meglétét, a mellékletek URL-jének helyességét és az adattípust. Ha a payload érvénytelen, azonnal hívja meg a completion handlert az eredeti tartalommal, ne vesztegessen időt haszontalan feldolgozásra.

Payloadok naplózása és monitorozása

A push-értesítések éles környezetben történő hibakereséséhez használja a payloadok strukturált naplózását. Az OSLog lehetővé teszi a payload naplózását a notifications kategóriával és debug szinttel. A szerveroldalon kövesse nyomon az APNS-válaszokat: a sikeres válasz tartalmazza az apns-id-t a küldött payloadhoz való hozzárendeléshez, a 400-as hiba pedig érvénytelen JSON-t vagy méret túllépését jelzi.