Notification Payload — vad är det, JSON-struktur och tolkning

Vad är Notification Payload

Notification Payload (meddelandets payload) — är ett JSON-objekt som servern skickar till APNS (Apple Push Notification Service) för leverans till en iOS-enhet. Payloaden innehåller all data som systemet behöver för att visa meddelandet: titel, text, ljud, badge och metadata för bakgrundsbearbetning. Payload-strukturen är strikt reglerad av Apple och innehåller obligatoriska nycklar för korrekt bearbetning av systemet.

Payloadens roll vid push-leverans

När servern skickar ett push-meddelande via HTTP/2 API APNS, innehåller begäran auktoriseringshuvuden och en JSON-kropp — payloaden. APNS kontrollerar payloadens giltighet: om JSON är felaktig eller överskrider storleksgränsen returnerar Apples server ett 400 Bad Request-fel. Efter validering levererar APNS payloaden till enheten, där iOS-systemet tolkar den och bestämmer hur meddelandet ska bearbetas — visa en banner, starta en bakgrundsuppgift eller spela upp ett ljud.

Evolution av payload-formatet

APNS-payload-formatet har utvecklats från en enkel text-payload i iOS 2 till en flerkomponents JSON-struktur i moderna versioner. iOS 10 introducerade stöd för media-bilagor via mutable-content, iOS 12 lade till gruppering av meddelanden via thread-id, och iOS 15 introducerade supports-live-activities för Live Activities. Idag kan payloaden innehålla upp till 15 olika nycklar beroende på meddelandets önskade beteende.

Struktur för APNS-payload: obligatoriska och valfria nycklar

Rotobjektet för payloaden innehåller aps-ordboken och valfria anpassade fält på den översta nivån. aps-ordboken är det enda obligatoriska elementet, men inuti den kan det finnas olika kombinationer av nycklar beroende på meddelandetyp: alert, badge, sound, content-available, mutable-content, interruption-level och andra.

Alert-nyckeln: sträng- och ordboksformat

Alert-nyckeln kan vara en enkel sträng (som blir meddelandets brödtext) eller en ordbok med fälten title, subtitle, body. Ordboksformatet gör det möjligt att ange titel och undertitel separat från huvudtexten. För lokaliserade meddelanden används nycklarna title-loc-key, title-loc-args, loc-key, loc-args som refererar till applikationens Localizable.strings. Detta gör det möjligt att skicka en payload utan text på ett specifikt språk — applikationen lägger till översättningen.

Hantering av avbrott: interruption-level och relevance-score

Från och med iOS 15 lade Apple till Focus Mode-mekanismen som kräver att utvecklaren anger meddelandets avbrottsnivå. interruption-level accepterar värdena: passive (utan ljud, utan att väcka skärmen), active (standardbeteende), time-sensitive (genomtränger fokus, kräver special entitlement) och critical (medicinska/nödsituationer). relevance-score (0–1) hjälper Focus-systemet att rangordna meddelanden inom en kategori.

Gruppering av meddelanden via thread-id

thread-id-nyckeln sammanfogar meddelanden i grupper i Notification Center. Alla meddelanden med samma thread-id visas som en grupp som användaren kan expandera. Detta är särskilt användbart för meddelandeappar, där meddelanden från en kontakt grupperas tillsammans, eller för appar som skickar många meddelanden av samma typ.

Anpassade fält och dataöverföring

Anpassade fält — är alla nycklar utanför aps-ordboken som utvecklaren lägger till för att överföra ytterligare data till enheten. Servern inkluderar dem i payloadens rot-JSON-objekt, och applikationen tar emot dem via userInfo i UNNotificationContent. Anpassade fält bör inte duplicera nyckelnamn från aps för att undvika konflikter vid tolkning.

Begränsningar för anpassad data

Huvudbegränsningen — den totala payload-storleken får inte överstiga 4096 byte. Anpassade fält konkurrerar om denna gräns med de obligatoriska aps-nycklarna, så det är viktigt att minimera mängden överförd data. Använd korta nyckelnamn (t.ex. uid istället för user-id), undvik stora JSON-strukturer och skicka endast identifierare, inte fullständiga dataobjekt.

Säkerhet och validering av anpassade fält

Anpassade fält kommer från servern och bör inte litas på utan kontroll. Validera alltid typer och värden för anpassade fält vid tolkning: kontrollera nyckelns närvaro via optional binding, konvertera till förväntad typ med as? String/Int/Dictionary och hantera fallet med saknat värde. Använd aldrig force unwrap (!) för data från payloaden — servern kan skicka felaktig data och applikationen kommer att krascha.

{
    "aps": {
        "alert": {
            "title": "Nytt meddelande",
            "body": "Hej! Hur mår du?"
        },
        "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"
}

Rekommendationer för namngivning av anpassade fält

Använd en enhetlig namngivningsstil för anpassade fält i alla projektets payloads. kebab-case (message-type) eller camelCase (messageType) — båda metoderna är acceptabla, men det är viktigt att hålla sig till en inom projektet. Undvik långa namn: uid istället för user-identifier, img istället för profile-image-url. Varje tecken i nyckelnamnet är en byte från gränsen på 4096.

Exempel på payloads för olika meddelandetyper

Olika scenarier för push-meddelanden kräver olika kombinationer av nycklar i payloaden. Låt oss titta på några typiska exempel: ett enkelt textmeddelande, ett meddelande med lokalisering, Silent Push och Rich Notification med media-bilaga.

Enkelt textmeddelande

Grundläggande payload med text och ljud — minimal konfiguration för att visa ett meddelande för användaren. Alert som sträng ger ett kort meddelande, sound default spelar upp standard systemljud. Badge är valfritt och sätter en räknare på ikonen. category och thread-id läggs till för gruppering och interaktivitet.

{
    "aps": {
        "alert": "Påminnelse: möte om 15 minuter",
        "badge": 3,
        "sound": "default"
    }
}

Meddelande med lokalisering

För sändning till enheter med olika språk, använd lokaliseringsnycklar istället för fast text. title-loc-key refererar till en nyckel i applikationens Localizable.strings, och title-loc-args ersätter argumenten. Detta gör det möjligt att skicka en payload till alla enheter, och applikationen visar texten på rätt språk.

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

Silent Push med bakgrundssynkronisering

För bakgrundssynkronisering utan att visa meddelandet används content-available: 1 och frånvaro av alert. Anpassade fält anger operationstyp och data för bearbetning. Systemet aktiverar applikationen i bakgrunden, anropar didReceiveRemoteNotification med fetchCompletionHandler, och applikationen utför synkroniseringen.

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

Rich Notification med bild

För att visa en media-bilaga krävs mutable-content: 1 för att aktivera Service Extension och bildens URL i ett anpassat fält. mutable-content: 1 signalerar systemet att starta UNNotificationServiceExtension, som laddar ner bilden från URL:en och lägger till den som UNNotificationAttachment. category pekar på en registrerad kategori för att visa åtgärdsknappar.

{
    "aps": {
        "alert": {
            "title": "Ny produkt",
            "body": "Se den nya kollektionen"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Bearbetning och tolkning av payload i applikationen

UNNotificationContent.userInfo innehåller den fullständiga ordboken för den mottagna payloaden efter bearbetning av systemet. Applikationen får åtkomst till payloaden i UNUserNotificationCenter-delegaten vid mottagning av meddelandet (i förgrunden), vid tryck på meddelandet, samt i Service Extension och Content Extension. Korrekt tolkning är obligatorisk för att extrahera anpassad data och bestämma fortsatta åtgärder.

Tolkning i AppDelegate vid tryck på meddelande

När användaren trycker på ett meddelande anropar systemet metoden didReceive response i UNUserNotificationCenterDelegate. I response.notification.request.content.userInfo finns den fullständiga payloaden. Utvecklaren extraherar anpassade fält, bestämmer åtgärdstyp (t.ex. öppna chatten, gå till produkt) och anropar motsvarande navigering i applikationen.

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

Validering av payload i Service Extension

Service Extension tar emot payloaden innan meddelandet visas och kan ändra den. Validering av payload — första steget i didReceive: kontrollera förekomsten av obligatoriska anpassade fält, korrektheten av URL:en för bilagor och datatypen. Om payloaden är ogiltig, anropa omedelbart completion handler med originalinnehållet, slösa inte tid på meningslös bearbetning.

Loggning och övervakning av payloads

För felsökning av push-meddelanden i produktion, använd strukturerad loggning av payloads. OSLog gör det möjligt att logga payloaden med kategorin notifications och debug-nivå. På serversidan, spåra APNS-svar: ett lyckat svar innehåller apns-id för matchning med den skickade payloaden, och ett 400-fel indikerar ogiltig JSON eller storleksöverskridning.