Notification Payload — co to je, JSON struktura a parsování

Co je Notification Payload

Notification Payload (payload oznámení) — je JSON objekt, který server odesílá do APNS (Apple Push Notification Service) pro doručení na zařízení iOS. Payload obsahuje všechna data potřebná systémem pro zobrazení oznámení: titul, text, zvuk, badge a metadata pro zpracování na pozadí. Struktura payloadu je přísně regulována společností Apple a zahrnuje povinné klíče pro správné zpracování systémem.

Role payloadu při doručování push

Když server odesílá push oznámení přes HTTP/2 API APNS, požadavek obsahuje autorizační hlavičky a JSON tělo — payload. APNS kontroluje platnost payloadu: pokud je JSON nesprávný nebo překračuje limit velikosti, server Apple vrátí chybu 400 Bad Request. Po validaci APNS doručí payload na zařízení, kde jej systém iOS zpracuje a určí, jak oznámení zpracovat — zobrazit banner, spustit úlohu na pozadí nebo přehrát zvuk.

Evoluce formátu payloadu

Formát APNS payloadu se vyvinul z jednoduchého textového payloadu v iOS 2 do vícesložkové JSON struktury v moderních verzích. iOS 10 přinesl podporu mediálních příloh přes mutable-content, iOS 12 přidal seskupování oznámení přes thread-id a iOS 15 zavedl supports-live-activities pro Live Activities. Dnes může payload obsahovat až 15 různých klíčů v závislosti na požadovaném chování oznámení.

Struktura APNS payloadu: povinné a volitelné klíče

Kořenový objekt payloadu obsahuje slovník aps a volitelná vlastní pole na nejvyšší úrovni. Slovník aps je jediný povinný prvek, ale uvnitř něj mohou být různé kombinace klíčů v závislosti na typu oznámení: alert, badge, sound, content-available, mutable-content, interruption-level a další.

Klíč alert: řetězcový a slovníkový formát

Klíč alert může být jednoduchý řetězec (který se stane tělem oznámení) nebo slovník s poli title, subtitle, body. Slovníkový formát umožňuje nastavit titul a podtitul odděleně od hlavního textu. Pro lokalizovaná oznámení se používají klíče title-loc-key, title-loc-args, loc-key, loc-args, které odkazují na Localizable.strings aplikace. To umožňuje odeslat payload bez textu v konkrétním jazyce — aplikace doplní překlad.

Řízení přerušení: interruption-level a relevance-score

Počínaje iOS 15 Apple přidal mechanismus Focus Mode, který vyžaduje, aby vývojář určil úroveň přerušení oznámení. interruption-level přijímá hodnoty: passive (bez zvuku, bez probuzení obrazovky), active (standardní chování), time-sensitive (prorazí focus, vyžaduje special entitlement) a critical (lékařské/nouzové situace). Klíč relevance-score (0–1) pomáhá systému Focus řadit oznámení v rámci jedné kategorie.

Seskupování oznámení pomocí thread-id

Klíč thread-id spojuje oznámení do skupin v Notification Center. Všechna oznámení se stejným thread-id se zobrazují jako jedna skupina, kterou může uživatel rozbalit. To je užitečné zejména pro aplikace pro zasílání zpráv, kde jsou zprávy od jednoho kontaktu seskupeny dohromady, nebo pro aplikace odesílající mnoho oznámení stejného typu.

Vlastní pole a přenos dat

Vlastní pole — jsou jakékoli klíče mimo slovník aps, které vývojář přidává pro přenos dalších dat na zařízení. Server je zahrne do kořenového JSON objektu payloadu a aplikace je obdrží prostřednictvím userInfo v UNNotificationContent. Vlastní pole by neměla duplikovat názvy klíčů z aps, aby se předešlo konfliktům při parsování.

Omezení vlastních dat

Hlavní omezení — celková velikost payloadu nesmí přesáhnout 4096 bajtů. Vlastní pole soutěží o tento limit s povinnými klíči aps, proto je důležité minimalizovat velikost přenášených dat. Používejte krátké názvy klíčů (např. uid místo user-id), vyhýbejte se velkým JSON strukturám a přenášejte pouze identifikátory, ne celé datové objekty.

Bezpečnost a validace vlastních polí

Vlastní pole přicházejí ze serveru a neměla by být bez kontroly důvěryhodná. Vždy validujte typy a hodnoty vlastních polí při parsování: zkontrolujte přítomnost klíče pomocí optional binding, převeďte na očekávaný typ pomocí as? String/Int/Dictionary a ošetřete případ chybějící hodnoty. Nikdy nepoužívejte force unwrap (!) pro data z payloadu — server může odeslat nesprávná data a aplikace spadne.

{
    "aps": {
        "alert": {
            "title": "Nová zpráva",
            "body": "Ahoj! Jak se máš?"
        },
        "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"
}

Doporučení pro pojmenování vlastních polí

Používejte jednotný styl pojmenování vlastních polí ve všech payloadech projektu. kebab-case (message-type) nebo camelCase (messageType) — oba přístupy jsou přijatelné, ale je důležité držet se jednoho v rámci projektu. Vyhýbejte se dlouhým názvům: uid místo user-identifier, img místo profile-image-url. Každý znak v názvu klíče je jeden bajt z limitu 4096.

Příklady payloadů pro různé typy oznámení

Různé scénáře push oznámení vyžadují různé kombinace klíčů v payloadu. Podívejme se na několik typických příkladů: jednoduché textové oznámení, oznámení s lokalizací, Silent Push a Rich Notification s mediální přílohou.

Jednoduché textové oznámení

Základní payload s textem a zvukem — minimální konfigurace pro zobrazení oznámení uživateli. Alert jako řetězec poskytuje krátkou zprávu, sound default přehrává standardní systémový zvuk. Badge je volitelný a nastavuje čítač na ikoně. category a thread-id se přidávají pro seskupení a interaktivitu.

{
    "aps": {
        "alert": "Připomínka: schůzka za 15 minut",
        "badge": 3,
        "sound": "default"
    }
}

Oznámení s lokalizací

Pro odesílání na zařízení s různými jazyky používejte lokalizační klíče místo pevně daného textu. title-loc-key odkazuje na klíč v Localizable.strings aplikace a title-loc-args nahrazuje argumenty. To umožňuje odeslat jeden payload na všechna zařízení a aplikace sama zobrazí text v příslušném jazyce.

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

Silent Push se synchronizací na pozadí

Pro synchronizaci na pozadí bez zobrazení oznámení se používá content-available: 1 a absence alert. Vlastní pole určují typ operace a data ke zpracování. Systém aktivuje aplikaci na pozadí, zavolá didReceiveRemoteNotification s fetchCompletionHandler a aplikace provede synchronizaci.

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

Rich Notification s obrázkem

Pro zobrazení mediální přílohy je nutný mutable-content: 1 pro aktivaci Service Extension a URL obrázku ve vlastním poli. mutable-content: 1 signalizuje systému spuštění UNNotificationServiceExtension, který stáhne obrázek z URL a přidá jej jako UNNotificationAttachment. category ukazuje na registrovanou kategorii pro zobrazení tlačítek akcí.

{
    "aps": {
        "alert": {
            "title": "Nový produkt",
            "body": "Podívejte se na novou kolekci"
        },
        "category": "product",
        "mutable-content": 1
    },
    "media-url": "https://cdn.example.com/product.jpg"
}

Zpracování a parsování payloadu v aplikaci

UNNotificationContent.userInfo obsahuje plný slovník přijatého payloadu po zpracování systémem. Aplikace má přístup k payloadu v delegátu UNUserNotificationCenter při přijetí oznámení (v popředí), při klepnutí na oznámení, a také v Service Extension a Content Extension. Správné parsování je povinné pro extrakci vlastních dat a určení dalších akcí.

Parsování v AppDelegate při klepnutí na oznámení

Když uživatel klepne na oznámení, systém zavolá metodu didReceive response v UNUserNotificationCenterDelegate. V response.notification.request.content.userInfo se nachází plný payload. Vývojář extrahuje vlastní pole, určí typ akce (např. otevření chatu, přechod na produkt) a zavolá odpovídající navigaci v aplikaci.

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

Validace payloadu v Service Extension

Service Extension obdrží payload před zobrazením oznámení a může jej upravit. Validace payloadu — první krok v didReceive: zkontrolujte přítomnost povinných vlastních polí, správnost URL pro přílohy a typ dat. Pokud je payload neplatný, okamžitě zavolejte completion handler s původním obsahem, neztrácejte čas zbytečným zpracováním.

Logování a monitorování payloadů

Pro ladění push oznámení v produkci používejte strukturované logování payloadů. OSLog umožňuje logovat payload s kategorií notifications a úrovní debug. Na straně serveru sledujte odpovědi APNS: úspěšná odpověď obsahuje apns-id pro přiřazení k odeslanému payloadu a chyba 400 indikuje neplatný JSON nebo překročení velikosti.