Notification Payload — wat is het, JSON-structuur en parsen

Wat is Notification Payload

Notification Payload (payload van de melding) — is een JSON-object dat de server naar APNS (Apple Push Notification Service) stuurt voor levering aan een iOS-apparaat. De payload bevat alle gegevens die het systeem nodig heeft om de melding weer te geven: titel, tekst, geluid, badge en metadata voor achtergrondverwerking. De payloadstructuur is strikt gereguleerd door Apple en bevat verplichte sleutels voor correcte verwerking door het systeem.

Rol van de payload bij push-levering

Wanneer de server een pushmelding verzendt via de HTTP/2 API van APNS, bevat het verzoek autorisatie-headers en een JSON-body — de payload. APNS controleert de geldigheid van de payload: als de JSON onjuist is of de groottebeperking overschrijdt, retourneert de Apple-server een 400 Bad Request-fout. Na validatie levert APNS de payload aan het apparaat, waar het iOS-systeem het parseert en bepaalt hoe de melding moet worden verwerkt — een banner weergeven, een achtergrondtaak starten of een geluid afspelen.

Evolutie van het payloadformaat

Het APNS-payloadformaat is geëvolueerd van een eenvoudige tekstuele payload in iOS 2 naar een uit meerdere componenten bestaande JSON-structuur in moderne versies. iOS 10 bracht ondersteuning voor media-bijlagen via mutable-content, iOS 12 voegde groepering van meldingen via thread-id toe, en iOS 15 introduceerde supports-live-activities voor Live Activities. Tegenwoordig kan de payload tot 15 verschillende sleutels bevatten, afhankelijk van het gewenste gedrag van de melding.

Structuur van APNS-payload: verplichte en optionele sleutels

Het hoofdobject van de payload bevat het aps-woordenboek en optionele aangepaste velden op het hoogste niveau. Het aps-woordenboek is het enige verplichte element, maar daarbinnen kunnen verschillende combinaties van sleutels voorkomen, afhankelijk van het meldingstype: alert, badge, sound, content-available, mutable-content, interruption-level en andere.

Alert-sleutel: tekenreeks- en woordenboekformaat

De alert-sleutel kan een eenvoudige tekenreeks zijn (die de hoofdtekst van de melding wordt) of een woordenboek met velden title, subtitle, body. Het woordenboekformaat maakt het mogelijk de titel en subtitel apart van de hoofdtekst in te stellen. Voor gelokaliseerde meldingen worden de sleutels title-loc-key, title-loc-args, loc-key, loc-args gebruikt, die verwijzen naar Localizable.strings van de app. Dit maakt het mogelijk een payload te verzenden zonder tekst in een specifieke taal — de app voegt de vertaling in.

Beheer van onderbrekingen: interruption-level en relevance-score

Vanaf iOS 15 heeft Apple het Focus Mode-mechanisme toegevoegd, dat vereist dat de ontwikkelaar het onderbrekingsniveau van de melding specificeert. interruption-level accepteert de waarden: passive (zonder geluid, zonder het scherm te activeren), active (standaardgedrag), time-sensitive (doorbreekt de focus, vereist special entitlement) en critical (medische/noodsituaties). De sleutel relevance-score (0–1) helpt het Focus-systeem meldingen binnen een categorie te rangschikken.

Groepering van meldingen via thread-id

De thread-id-sleutel voegt meldingen samen in groepen in het Notification Center. Alle meldingen met dezelfde thread-id worden weergegeven als een groep die de gebruiker kan uitvouwen. Dit is vooral handig voor berichtenapps, waar berichten van een contactpersoon worden gegroepeerd, of voor apps die veel meldingen van hetzelfde type verzenden.

Aangepaste velden en gegevensoverdracht

Aangepaste velden — zijn alle sleutels buiten het aps-woordenboek die de ontwikkelaar toevoegt om extra gegevens naar het apparaat te sturen. De server neemt ze op in het root-JSON-object van de payload, en de app ontvangt ze via userInfo in UNNotificationContent. Aangepaste velden mogen de sleutelnamen van aps niet dupliceren om conflicten bij het parsen te voorkomen.

Beperkingen voor aangepaste gegevens

De belangrijkste beperking — de totale payloadgrootte mag niet meer dan 4096 bytes bedragen. Aangepaste velden concurreren voor deze limiet met de verplichte aps-sleutels, dus het is belangrijk de hoeveelheid verzonden gegevens te minimaliseren. Gebruik korte sleutelnamen (bijv. uid in plaats van user-id), vermijd grote JSON-structuren en stuur alleen identificaties, geen volledige gegevensobjecten.

Beveiliging en validatie van aangepaste velden

Aangepaste velden komen van de server en moeten niet zonder controle worden vertrouwd. Valideer altijd de typen en waarden van aangepaste velden bij het parsen: controleer de aanwezigheid van de sleutel via optional binding, converteer naar het verwachte type met as? String/Int/Dictionary en behandel het geval van ontbrekende waarde. Gebruik nooit force unwrap (!) voor gegevens uit de payload — de server kan onjuiste gegevens verzenden en de app zal crashen.

{
    "aps": {
        "alert": {
            "title": "Nieuw bericht",
            "body": "Hallo! Hoe gaat het?"
        },
        "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"
}

Aanbevelingen voor naamgeving van aangepaste velden

Gebruik een uniforme naamgevingsstijl voor aangepaste velden in alle payloads van het project. kebab-case (message-type) of camelCase (messageType) — beide benaderingen zijn acceptabel, maar het is belangrijk er een te volgen binnen het project. Vermijd lange namen: uid in plaats van user-identifier, img in plaats van profile-image-url. Elk teken in de sleutelnaam is een byte uit de limiet van 4096.

Voorbeelden van payloads voor verschillende meldingstypen

Verschillende scenario's van pushmeldingen vereisen verschillende combinaties van sleutels in de payload. Laten we een aantal typische voorbeelden bekijken: een eenvoudige tekstmelding, een melding met lokalisatie, Silent Push en Rich Notification met media-bijlage.

Eenvoudige tekstmelding

Basis-payload met tekst en geluid — minimale configuratie om een melding aan de gebruiker weer te geven. Alert als tekenreeks geeft een kort bericht, sound default speelt het standaard systeemgeluid af. Badge is optioneel en stelt een teller in op het pictogram. category en thread-id worden toegevoegd voor groepering en interactiviteit.

{
    "aps": {
        "alert": "Herinnering: afspraak over 15 minuten",
        "badge": 3,
        "sound": "default"
    }
}

Melding met lokalisatie

Voor verzending naar apparaten met verschillende talen gebruikt u lokalisatiesleutels in plaats van vaste tekst. title-loc-key verwijst naar een sleutel in Localizable.strings van de app, en title-loc-args vervangt de argumenten. Dit maakt het mogelijk een payload naar alle apparaten te sturen, waarbij de app de tekst in de juiste taal weergeeft.

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

Silent Push met achtergrondsynchronisatie

Voor achtergrondsynchronisatie zonder melding weer te geven, wordt content-available: 1 gebruikt zonder alert. Aangepaste velden geven het type bewerking en de te verwerken gegevens aan. Het systeem activeert de app op de achtergrond, roept didReceiveRemoteNotification aan met fetchCompletionHandler, en de app voert de synchronisatie uit.

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

Rich Notification met afbeelding

Voor het weergeven van een media-bijlage is mutable-content: 1 nodig om de Service Extension te activeren en de URL van de afbeelding in een aangepast veld. mutable-content: 1 geeft het systeem de opdracht UNNotificationServiceExtension te starten, die de afbeelding van de URL downloadt en toevoegt als UNNotificationAttachment. category verwijst naar een geregistreerde categorie voor het weergeven van actieknoppen.

{
    "aps": {
        "alert": {
            "title": "Nieuw product",
            "body": "Bekijk de nieuwe collectie"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Verwerken en parsen van payload in de app

UNNotificationContent.userInfo bevat het volledige woordenboek van de ontvangen payload na verwerking door het systeem. De app heeft toegang tot de payload in de UNUserNotificationCenter-delegate bij ontvangst van de melding (op de voorgrond), bij het tikken op de melding, en ook in Service Extension en Content Extension. Correct parsen is verplicht om aangepaste gegevens te extraheren en verdere acties te bepalen.

Parsen in AppDelegate bij tikken op melding

Wanneer de gebruiker op een melding tikt, roept het systeem de methode didReceive response aan in UNUserNotificationCenterDelegate. In response.notification.request.content.userInfo bevindt zich de volledige payload. De ontwikkelaar extraheert aangepaste velden, bepaalt het type actie (bijv. chat openen, naar product gaan) en roept de juiste navigatie in de app aan.

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

Validatie van payload in Service Extension

Service Extension ontvangt de payload voordat de melding wordt weergegeven en kan deze wijzigen. Validatie van de payload — de eerste stap in didReceive: controleer de aanwezigheid van verplichte aangepaste velden, de juistheid van de URL voor bijlagen en het gegevenstype. Als de payload ongeldig is, roep dan onmiddellijk de completion handler aan met de originele inhoud, zonder tijd te verspillen aan nutteloze verwerking.

Loggen en monitoren van payloads

Gebruik gestructureerd loggen van payloads voor het debuggen van pushmeldingen in productie. OSLog maakt het mogelijk de payload te loggen met de categorie notifications en debug-niveau. Houd aan de serverzijde de APNS-antwoorden bij: een succesvol antwoord bevat apns-id voor koppeling met de verzonden payload, en een 400-fout duidt op ongeldige JSON of overschrijding van de grootte.