APNS: шта је то, архитектура Apple Push Notification Service и како ради

Шта је APNS?

Apple Push Notification Service (APNS) — Apple-ов сопствени сервис за усмеравање push обавештења од сервера апликације до уређаја корисника. За разлику од FCM, APNS не подржава Android или друге платформе — потпуно је везан за Apple екосистем.

Сервис функционише путем сталне TLS везе коју сваки Apple уређај успоставља са APNS серверима при укључењу. Ова веза се одржава у позадини и користи се за доставу обавештења са минималним кашњењем.

APNS преузима целокупну инфраструктуру доставе: енкрипцију, аутентификацију, приоритизацију и поновно слање у случају недоступности уређаја. Програмер треба само да обезбеди правилно форматиран payload и важећи push token.

Еволуција APNS

Првобитно је APNS радио путем бинарног протокола на портовима 2195–2196. Од 2015. године Apple је прешао на савремени HTTP/2 протокол који подржава мултиплексирање, компресију заглавља и серверске push нотификације. HTTP/2 је постао обавезан од јуна 2020. године.

Како функционише Apple Push Notification Service?

Процес доставе push обавештења путем APNS састоји се од пет фаза: регистрација уређаја, добијање push token-а, слање захтева од стране сервера, усмеравање APNS и достава на уређај.

• Регистрација — при покретању апликација позива registerForRemoteNotifications, систем се повезује са APNS
• Токен — APNS враћа уређају push token — јединствени низ који идентификује апликацију на уређају
• Слање — сервер апликације шаље POST захтев на https://api.push.apple.com са токеном и payload-ом
• Усмеравање — APNS проналази уређај по токену и доставља поруку путем TLS везе
• Обрада — iOS/macOS приказује обавештење или га прослеђује апликацији у зависности од стања

Ако је уређај недоступан (искључен или без мреже), APNS чува последњу поруку за сваку апликацију и доставља је при успостављању везе. Максимално време чувања — 4 недеље, након чега се порука брише.

Аутентификација у APNS: Token и Сертификат

Apple подржава два начина аутентификације сервера апликације при слању push обавештења. Сваки начин има своје карактеристике у погледу рока трајања, управљања и једноставности коришћења.

Token-based аутентификација — препоручени Apple-ов начин од 2019. године. Креирате један p8 кључ у Apple Developer Console, учитавате га на сервер и потписујете сваки APNS захтев њиме. Кључ не истиче и ради за све апликације вашег налога.

Који начин аутентификације одабрати

За нове пројекте Token-based аутентификација је дефинитивно пожељнија: један p8 кључ за цео налог, бесконачан, без везаности за окружење. Certificate-based (.p12) се још увек користи у legacy пројектима, али захтева годишњу замену и посебне сертификате за Sandbox и Production. Узмите у обзир време истека сертификата при планирању CI/CD.

Типови push обавештења APNS

APNS подржава три типа push обавештења која се разликују по понашању на уређају и захтевима за атрибуте захтева. Избор типа зависи од UX сценарија и хитности поруке.

• Alert — стандардно обавештење са насловом, текстом и опционим дугмићима за акцију
• Background — тиха достава података (silent push) без приказивања кориснику, обрађује се у application:didReceiveRemoteNotification
• VOIP — посебан тип за VoIP апликације (PushKit), доставља се одмах чак и када је апликација затворена

За Background обавештења потребно је навести кључ content-available: 1 и поставити приоритет 5 (енергетски ефикасна достава). Систем може ограничити број позадинских обавештења ако их апликација не обрађује на време.

Подешавање приоритета доставе

APNS подржава две вредности приоритета: 10 (тренутна достава) и 5 (енергетски ефикасна). За alert обавештења користите 10 — корисник треба да их прими одмах. За background користите 5 — систем може одложити доставу ради уштеде батерије. Неисправан приоритет за background може довести до одбијања обавештења од стране APNS.

Формат корисног терета APNS

APNS прима payload у JSON формату максималне величине 4 KB за обична обавештења и 5 KB за VOIP. Payload садржи обавезни речник aps са подешавањима приказа и опциона прилагођена поља.

{
    "aps": {
        "alert": {
            "title": "Нова порука",
            "body": "Имате 3 непрочитана ћаскања"
        },
        "badge": 3,
        "sound": "default",
        "category": "message_category",
        "thread-id": "chat_room_42"
    },
    "customData": {
        "chatId": "42"
    }
}

Кључ thread-id обједињује обавештења у групе у iOS Центру за обавештења. Кључ category повезује обавештење са UNNotificationCategory за приказ дугмића за акцију. Без ових кључева, сва обавештења се приказују појединачно.

Прилагођена поља у APNS пакету

Поред обавезног речника aps, APNS пакет може садржати било која прилагођена поља на највишем нивоу. Ова поља су доступна апликацији путем userInfo речника при обради обавештења. Прилагођени подаци су погодни за пренос идентификатора ентитета, екрана или линкова. Максимална величина пакета је 4 KB, зато избегавајте пренос великих количина података путем push-а; учитавајте их путем API-ја након отварања обавештења.

Пример слања путем HTTP/2 API

За слање push обавештења на серверу потребно је извршити POST захтев ка APNS endpoint-у са исправним заглављима аутентификације. Испод је пример у Node.js са Token-based аутентификацијом.

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: "Здраво!", body: "Тест 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 успешно послат")
    }
})

Након слања, APNS враћа HTTP статус 200 при успешној достави или код грешке са описом у телу одговора. Важно је обрадити грешку token-unregistered (410) — такав token треба уклонити са сервера, јер је апликација уклоњена са уређаја.

APNS грешке и њихова обрада

APNS враћа HTTP статусе за сваки захтев за слање. Успешно слање — статус 200. Грешке захтевају различите стратегије обраде. BadDeviceToken (400) или Unregistered (410) — token уређаја је застарео, треба га уклонити са сервера. PayloadTooLarge (413) — прекорачен лимит од 4 KB, скратите payload.

Грешка TooManyRequests (429) — прекорачен лимит захтева. APNS поставља квоту на број слања у секунди. При пријему 429 потребно је применити експоненцијално кашњење (exponential backoff) и поновити слање. Препоручује се да не прелазите 100 захтева у секунди по једној HTTP/2 вези.

Грешке на страни APNS — 500 и 503 (Internal Server Error / Service Unavailable). Ово су привремени кварови Apple инфраструктуре. У таквим случајевима понављајте слање са кашњењем 1–5 секунди, не више од 3 покушаја. Константне 5xx грешке на потпуно исправном серверу су ретка појава, обично повезане са проблемима TLS везе.

За Production окружење обавезно имплементирајте логирање свих APNS грешака са навођењем token-а, кода грешке и времена. Ово ће помоћи да се брзо идентификују проблеми са сертификатима, квотама или специфичним token-има уређаја. Редовно проверавајте рок трајања сертификата ако користите Certificate-based аутентификацију.