APNS: mi ez, az Apple Push Notification Service felépítése és működése

Mi az APNS?

Az Apple Push Notification Service (APNS) — az Apple saját szolgáltatása push értesítések útvonalához az alkalmazásszervertől a felhasználók eszközeire. Az FCM-mel ellentétben az APNS nem támogatja az Androidot vagy más platformokat — teljesen az Apple ökoszisztémához kötött.

A szolgáltatás egy állandó TLS-kapcsolaton keresztül működik, amelyet minden Apple eszköz létesít az APNS szerverekkel bekapcsoláskor. Ez a kapcsolat a háttérben marad, és az értesítések minimális késleltetéssel történő kézbesítésére szolgál.

Az APNS vállalja a teljes kézbesítési infrastruktúrát: titkosítás, hitelesítés, prioritáskezelés és újraküldés az eszköz elérhetetlensége esetén. A fejlesztőnek csak egy megfelelően formázott payloadot és érvényes push tokent kell biztosítania.

Az APNS evolúciója

Kezdetben az APNS egy bináris protokollon keresztül működött a 2195–2196 portokon. 2015-től az Apple áttért a modern HTTP/2 protokollra, amely támogatja a multiplexelést, fejléctömörítést és szerver push értesítéseket. A HTTP/2 2020 júniusától kötelező.

Hogyan működik az Apple Push Notification Service?

A push értesítés APNS-en keresztüli kézbesítésének folyamata öt szakaszból áll: eszköz regisztrálása, push token megszerzése, kérés küldése a szerver által, APNS útvonalazás és kézbesítés az eszközre.

• Regisztráció — indításkor az alkalmazás meghívja a registerForRemoteNotifications-t, a rendszer csatlakozik az APNS-hez
• Token — az APNS visszaadja a push tokent az eszköznek — egy egyedi karakterlánc, amely azonosítja az alkalmazást az eszközön
• Küldés — az alkalmazásszerver POST kérést küld a https://api.push.apple.com címre a tokennal és payloaddal
• Útvonalazás — az APNS megtalálja az eszközt a token alapján és kézbesíti az üzenetet a TLS-kapcsolaton keresztül
• Feldolgozás — az iOS/macOS megjeleníti az értesítést vagy továbbítja az alkalmazásnak az állapottól függően

Ha az eszköz nem érhető el (kikapcsolt vagy hálózat nélkül), az APNS tárolja az utolsó üzenetet minden alkalmazáshoz és kézbesíti a kapcsolat helyreállásakor. A maximális tárolási idő 4 hét, ezután az üzenet törlődik.

Hitelesítés az APNS-ben: Token és Tanúsítvány

Az Apple két hitelesítési módszert támogat az alkalmazásszerver számára push értesítések küldésekor. Minden módszernek megvannak a maga jellemzői az érvényességi idő, kezelés és használhatóság tekintetében.

Token-based hitelesítés — az Apple által ajánlott módszer 2019 óta. Létrehoz egy p8 kulcsot az Apple Developer Console-ban, feltölti a szerverre és aláírja vele az APNS kéréseket. A kulcs nem jár le és működik a fiók összes alkalmazásához.

Melyik hitelesítési módszert válassza

Új projektekhez a Token-based hitelesítés egyértelműen előnyösebb: egyetlen p8 kulcs a teljes fiókhoz, korlátlan, környezetfüggetlen. A Certificate-based (.p12) még használatban van régebbi projektekben, de éves cserét és külön tanúsítványokat igényel Sandbox és Production számára. Vegye figyelembe a tanúsítvány lejárati idejét a CI/CD tervezésekor.

APNS push értesítési típusok

Az APNS három típusú push értesítést támogat, amelyek az eszközön való viselkedésben és a kérés attribútumainak követelményeiben különböznek. A típus választása az UX forgatókönyvtől és az üzenet sürgősségétől függ.

• Alert — standard értesítés címmel, szöveggel és opcionális műveleti gombokkal
• Background — csendes adatkézbesítés (silent push) a felhasználónak történő megjelenítés nélkül, az application:didReceiveRemoteNotification dolgozza fel
• VOIP — speciális típus VoIP alkalmazásokhoz (PushKit), azonnal kézbesítve, még ha az alkalmazás zárva van

A Background értesítésekhez meg kell adni a content-available: 1 kulcsot és be kell állítani a prioritást 5-re (energiahatékony kézbesítés). A rendszer korlátozhatja a háttérértesítések számát, ha az alkalmazás nem dolgozza fel őket időben.

A kézbesítési prioritás beállítása

Az APNS két prioritási értéket támogat: 10 (azonnali kézbesítés) és 5 (energiahatékony). Az alert értesítésekhez használjon 10-et — a felhasználónak azonnal meg kell kapnia azokat. Background esetén használjon 5-öt — a rendszer késleltetheti a kézbesítést az akkumulátor kímélése érdekében. A helytelen prioritás background esetén az értesítés elutasításához vezethet az APNS részéről.

Az APNS payload formátuma

Az APNS a payloadot JSON formátumban fogadja, maximum 4 KB méretben a szokásos értesítésekhez és 5 KB méretben a VOIP számára. A payload tartalmazza a kötelező aps szótárat megjelenítési beállításokkal és opcionális egyéni mezőket.

{
    "aps": {
        "alert": {
            "title": "Új üzenet",
            "body": "3 olvasatlan csevegésed van"
        },
        "badge": 3,
        "sound": "default",
        "category": "message_category",
        "thread-id": "chat_room_42"
    },
    "customData": {
        "chatId": "42"
    }
}

A thread-id kulcs csoportosítja az értesítéseket az iOS Értesítési Központban. A category kulcs az értesítést az UNNotificationCategory-hez kapcsolja a műveleti gombok megjelenítéséhez. E kulcsok nélkül az összes értesítés külön jelenik meg.

Egyéni mezők az APNS payloadban

A kötelező aps szótáron kívül az APNS payload tartalmazhat tetszőleges egyéni mezőket a legfelső szinten. Ezek a mezők az alkalmazás számára a userInfo szótáron keresztül érhetők el az értesítés feldolgozásakor. Az egyéni adatok hasznosak entitások azonosítóinak, képernyőknek vagy linkeknek az átadásához. A payload maximális mérete 4 KB, ezért kerülje a nagy adatmennyiségek push-on keresztüli küldését; töltse be őket API-n keresztül az értesítés megnyitása után.

Példa küldésre HTTP/2 API-n keresztül

Push értesítés küldéséhez a szervernek POST kérést kell küldenie az APNS endpointra a megfelelő hitelesítési fejlécekkel. Alább egy példa Node.js-ben Token-based hitelesítéssel.

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: "Szia!", body: "Teszt 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 sikeresen elküldve")
    }
})

Küldés után az APNS HTTP 200 státuszt ad vissza sikeres kézbesítéskor vagy hibakódot leírással a válasz törzsében. Fontos kezelni a token-unregistered (410) hibát — az ilyen tokent el kell távolítani a szerverről, mert az alkalmazást eltávolították az eszközről.

APNS hibák és kezelésük

Az APNS HTTP státuszokat ad vissza minden küldési kéréshez. Sikeres küldés — 200 státusz. A hibák különböző kezelési stratégiákat igényelnek. BadDeviceToken (400) vagy Unregistered (410) — az eszköz token lejárt, el kell távolítani a szerverről. PayloadTooLarge (413) — a 4 KB-os korlát túllépése, rövidítse le a payloadot.

A TooManyRequests (429) hiba — a kérések számának korlátja túllépve. Az APNS kvótát állít be a másodpercenkénti küldések számára. 429 fogadásakor exponenciális késleltetést (exponential backoff) kell alkalmazni és újra kell próbálni a küldést. Ajánlott nem túllépni a 100 kérést másodpercenként HTTP/2 kapcsolatonként.

APNS oldali hibák — 500 és 503 (Internal Server Error / Service Unavailable). Ezek az Apple infrastruktúra átmeneti meghibásodásai. Ilyen esetekben ismételje a küldést 1–5 másodperces késleltetéssel, legfeljebb 3 próbálkozzon. Az állandó 5xx hibák egy teljesen működő szerveren ritkák és általában TLS kapcsolati problémákhoz kapcsolódnak.

A Production környezethez kötelező az összes APNS hiba naplózását megvalósítani a token, hibakód és idő megadásával. Ez segít gyorsan azonosítani a tanúsítványokkal, kvótákkal vagy bizonyos eszköztokenekkel kapcsolatos problémákat. Rendszeresen ellenőrizze a tanúsítványok lejárati idejét, ha Certificate-based hitelesítést használ.