APNS: co to je, architektura Apple Push Notification Service a jak funguje

Co je APNS?

Apple Push Notification Service (APNS) je vlastní služba Apple pro směrování push oznámení z aplikačního serveru na zařízení uživatelů. Na rozdíl od FCM nepodporuje APNS Android ani jiné platformy — je plně vázáno na ekosystém Apple.

Služba funguje prostřednictvím trvalého TLS připojení, které každé zařízení Apple naváže se servery APNS při zapnutí. Toto připojení je udržováno na pozadí a používá se k doručování oznámení s minimálním zpožděním.

APNS přebírá veškerou infrastrukturu doručování: šifrování, autentizaci, prioritizaci a opětovné odeslání v případě nedostupnosti zařízení. Vývojář potřebuje pouze poskytnout správně vytvořené payload a platný push token.

Vývoj APNS

Původně APNS fungoval prostřednictvím binárního protokolu na portech 2195–2196. Od roku 2015 Apple převedl službu na moderní protokol HTTP/2, který podporuje multiplexování, kompresi hlaviček a serverová push oznámení. HTTP/2 se stal povinným od června 2020.

Jak funguje Apple Push Notification Service?

Proces doručení push oznámení přes APNS se skládá z pěti fází: registrace zařízení, získání push tokenu, odeslání požadavku serverem, směrování APNS a doručení na zařízení.

• Registrace — při spuštění aplikace zavolá registerForRemoteNotifications, systém kontaktuje APNS
• Token — APNS vrátí zařízení push token — unikátní řetězec identifikující aplikaci na zařízení
• Odeslání — aplikační server odešle POST požadavek na https://api.push.apple.com s tokenem a payload
• Směrování — APNS najde zařízení podle tokenu a doručí zprávu přes TLS připojení
• Zpracování — iOS/macOS zobrazí oznámení nebo jej předá aplikaci v závislosti na stavu

Pokud je zařízení nedostupné (vypnuté nebo bez sítě), APNS uloží poslední zprávu pro každou aplikaci a doručí ji po obnovení připojení. Maximální doba uložení je 4 týdny, poté je zpráva smazána.

Autentizace v APNS: Token a Certificate

Apple podporuje dva způsoby autentizace aplikačního serveru při odesílání push oznámení. Každý způsob má své vlastnosti týkající se doby platnosti, správy a snadnosti použití.

Token-based autentizace — doporučený způsob Applem od roku 2019. Vytvoříte jeden p8-klíč v Apple Developer Console, nahrajete jej na server a podepisujete jím každý APNS požadavek. Klíč nevyprší a funguje pro všechny aplikace vašeho účtu.

Jaký způsob autentizace zvolit

Pro nové projekty je Token-based autentizace jednoznačně výhodnější: jeden p8-klíč pro celý účet, neomezená platnost, bez vazby na prostředí. Certificate-based (.p12) se stále používá ve starších projektech, ale vyžaduje každoroční výměnu a samostatné certifikáty pro Sandbox a Production. Zohledněte vypršení certifikátu při plánování CI/CD.

Typy push oznámení APNS

APNS podporuje tři typy push oznámení, které se liší chováním na zařízení a požadavky na atributy požadavku. Výběr typu závisí na UX scénáři a naléhavosti zprávy.

• Alert — standardní oznámení s nadpisem, textem a volitelnými tlačítky akcí
• Background — tiché doručení dat (silent push) bez zobrazení uživateli, zpracovává se v application:didReceiveRemoteNotification
• VOIP — speciální typ pro VoIP aplikace (PushKit), doručuje se okamžitě i při zavřené aplikaci

Pro Background oznámení je nutné nastavit klíč content-available: 1 a prioritu 5 (energeticky úsporné doručení). Systém může omezit počet oznámení na pozadí, pokud je aplikace nezpracovává včas.

Nastavení priority doručení

APNS podporuje dvě hodnoty priority: 10 (okamžité doručení) a 5 (energeticky úsporné). Pro alert oznámení použijte 10 — uživatel by je měl obdržet ihned. Pro background oznámení použijte 5 — systém může doručení zpozdit kvůli úspoře baterie. Nesprávná priorita pro background může vést k zamítnutí oznámení APNS.

Formát užitečného zatížení APNS

APNS přijímá payload ve formátu JSON s maximální velikostí 4 KB pro běžná oznámení a 5 KB pro VOIP. Payload obsahuje povinný slovník aps s nastavením zobrazení a volitelná vlastní pole.

{
    "aps": {
        "alert": {
            "title": "Nová zpráva",
            "body": "Máte 3 nepřečtené chaty"
        },
        "badge": 3,
        "sound": "default",
        "category": "message_category",
        "thread-id": "chat_room_42"
    },
    "customData": {
        "chatId": "42"
    }
}

Klíč thread-id sdružuje oznámení do skupin v Centru oznámení iOS. Klíč category propojuje oznámení s UNNotificationCategory pro zobrazení tlačítek akcí. Bez těchto klíčů se všechna oznámení zobrazují jednotlivě.

Vlastní pole v APNS payloadu

Kromě povinného slovníku aps může APNS payload obsahovat libovolná vlastní pole na nejvyšší úrovni. Tato pole jsou aplikaci k dispozici prostřednictvím slovníku userInfo při zpracování oznámení. Vlastní data jsou užitečná pro přenos identifikátorů entit, obrazovek nebo odkazů. Maximální velikost payloadu je 4 KB, proto se vyhněte přenosu velkých objemů dat přes push; načtěte je přes API po otevření oznámení.

Příklad odeslání přes HTTP/2 API

Pro odeslání push oznámení na serveru je nutné provést POST požadavek na APNS endpoint se správnými hlavičkami autentizace. Níže je uveden příklad v Node.js s použitím Token-based autentizace.

const http2 = require("http2")
const fs = require("fs")
const jwt = require("jsonwebtoken")

const token = jwt.sign(
    { iss: "TEAM_ID", iat: Math.floor(Date.now() / 1000) },
    fs.readFileSync("AuthKey.p8"),
    { algorithm: "ES256", keyid: "KEY_ID" }
)

const payload = JSON.stringify({
    aps: { alert: { title: "Ahoj!", body: "Testovací push" } }
})

const client = http2.connect(
    "https://api.push.apple.com"
)

const req = client.request({
    ":method": "POST",
    ":path": "/3/device/DEVICE_PUSH_TOKEN",
    "authorization": "bearer " + token,
    "apns-push-type": "alert",
    "apns-topic": "com.example.app",
    "apns-priority": "10"
})
req.end(payload)

req.on("response", (headers) => {
    if (headers[":status"] === 200) {
        console.log("Push odeslán úspěšně")
    }
})

Po odeslání APNS vrátí HTTP stav 200 při úspěšném doručení nebo kód chyby s popisem v těle odpovědi. Je důležité zpracovávat chybu token-unregistered (410) — takový token by měl být odstraněn ze serveru, protože aplikace byla odebrána ze zařízení.

Chyby APNS a jejich zpracování

APNS vrací HTTP stavy pro každý požadavek na odeslání. Úspěšné odeslání — stav 200. Chyby vyžadují různé strategie zpracování. BadDeviceToken (400) nebo Unregistered (410) — token zařízení je zastaralý, je třeba jej odstranit ze serveru. PayloadTooLarge (413) — překročen limit 4 KB, zmenšete payload.

Chyba TooManyRequests (429) — překročen limit požadavků. APNS stanovuje kvótu na počet odeslání za sekundu. Při obdržení 429 je nutné zavést exponenciální zpoždění (exponential backoff) a odeslání opakovat. Doporučuje se nepřekračovat 100 požadavků za sekundu na jedno HTTP/2 připojení.

Chyby na straně APNS — 500 a 503 (Internal Server Error / Service Unavailable). Jedná se o dočasné výpadky infrastruktury Apple. V takových případech opakujte odeslání se zpožděním 1–5 sekund, maximálně 3 pokusy. Trvalé chyby 5xx při plně funkčním serveru jsou vzácným jevem, obvykle souvisejí s problémy TLS připojení.

Pro produkční prostředí nezapomeňte implementovat logování všech chyb APNS s uvedením tokenu, kódu chyby a času. To pomůže rychle identifikovat problémy s certifikáty, kvótami nebo konkrétními tokeny zařízení. Pravidelně kontrolujte platnost certifikátů, pokud používáte Certificate-based autentizaci.