APNS: ano ito, arkitektura ng Apple Push Notification Service at kung paano ito gumagana

Ano ang APNS?

Ang Apple Push Notification Service (APNS) — ay sariling serbisyo ng Apple para sa pagruta ng mga push notification mula sa server ng aplikasyon patungo sa mga aparato ng mga gumagamit. Hindi tulad ng FCM, hindi sinusuportahan ng APNS ang Android o iba pang mga platform — ito ay ganap na nakatali sa ecosystem ng Apple.

Ang serbisyo ay gumagana sa pamamagitan ng isang permanenteng TLS na koneksyon na itinatag ng bawat Apple device sa mga server ng APNS kapag naka-on. Ang koneksyong ito ay pinapanatili sa background at ginagamit para sa paghahatid ng mga notification na may minimal na pagkaantala.

Ang APNS ay pumapangalaga sa buong imprastraktura ng paghahatid: encryption, autentikasyon, prioritisasyon, at muling pagpapadala kung hindi available ang device. Ang developer ay kailangan lamang magbigay ng wastong na-format na payload at isang valid na push token.

Ebolusyon ng APNS

Sa simula, ang APNS ay gumagana sa pamamagitan ng isang binary protocol sa mga port 2195–2196. Mula noong 2015, lumipat ang Apple sa modernong HTTP/2 protocol na sumusuporta sa multiplexing, header compression, at server push notification. Ang HTTP/2 ay naging mandatory mula Hunyo 2020.

Paano gumagana ang Apple Push Notification Service?

Ang proseso ng paghahatid ng push notification sa pamamagitan ng APNS ay binubuo ng limang yugto: pagrehistro ng device, pagkuha ng push token, pagpapadala ng kahilingan ng server, pagruta ng APNS, at paghahatid sa device.

• Pagrehistro — sa pag-start, tinatawag ng app ang registerForRemoteNotifications, kumokonekta ang system sa APNS
• Token — ibinabalik ng APNS ang push token sa device — isang natatanging string na nagpapakilala sa app sa device
• Pagpapadala — ang server ng aplikasyon ay nagpapadala ng POST request sa https://api.push.apple.com kasama ang token at payload
• Pagruta — hinahanap ng APNS ang device sa pamamagitan ng token at inihahatid ang mensahe sa pamamagitan ng TLS connection
• Pagproseso — ipinapakita ng iOS/macOS ang notification o ipinapasa ito sa app depende sa estado

Kung ang device ay hindi available (naka-off o walang network), iniimbak ng APNS ang huling mensahe para sa bawat app at ihahatid ito kapag naibalik ang koneksyon. Ang maximum na oras ng pag-iimbak ay 4 na linggo, pagkatapos nito ay tatanggalin ang mensahe.

Autentikasyon sa APNS: Token at Certificate

Sinusuportahan ng Apple ang dalawang paraan ng autentikasyon ng server ng aplikasyon kapag nagpapadala ng push notification. Ang bawat paraan ay may sariling mga katangian tungkol sa panahon ng bisa, pamamahala, at kadalian ng paggamit.

Token-based autentikasyon — ang inirerekomendang paraan ng Apple mula noong 2019. Gumagawa ka ng isang p8 key sa Apple Developer Console, ina-upload ito sa server, at pinipirmahan ang bawat APNS request dito. Hindi nag-e-expire ang key at gumagana para sa lahat ng app ng iyong account.

Aling paraan ng autentikasyon ang pipiliin

Para sa mga bagong proyekto, ang Token-based autentikasyon ay tiyak na mas gusto: isang p8 key para sa buong account, walang hanggan, walang dependency sa kapaligiran. Ang Certificate-based (.p12) ay ginagamit pa rin sa mga legacy na proyekto, ngunit nangangailangan ng taunang pagpapalit at hiwalay na certificate para sa Sandbox at Production. Isaalang-alang ang expiry date ng certificate kapag nagpaplano ng CI/CD.

Mga Uri ng Push Notification ng APNS

Sinusuportahan ng APNS ang tatlong uri ng push notification na nagkakaiba sa pag-uugali sa device at mga kinakailangan sa attribute ng kahilingan. Ang pagpili ng uri ay depende sa UX scenario at pagka-apura ng mensahe.

• Alert — karaniwang notification na may pamagat, teksto, at opsyonal na mga button ng aksyon
• Background — tahimik na paghahatid ng data (silent push) nang hindi ipinapakita sa gumagamit, pinoproseso sa application:didReceiveRemoteNotification
• VOIP — espesyal na uri para sa VoIP apps (PushKit), inihahatid agad kahit nakasara ang app

Para sa Background notification, kailangan mong isama ang key na content-available: 1 at itakda ang priyoridad sa 5 (matipid sa enerhiya na paghahatid). Maaaring limitahan ng system ang bilang ng background notification kung hindi ito pinoproseso ng app sa tamang oras.

Konfigurasyon ng Priyoridad ng Paghahatid

Sinusuportahan ng APNS ang dalawang halaga ng priyoridad: 10 (agarang paghahatid) at 5 (matipid sa enerhiya). Para sa alert notification gamitin ang 10 — dapat matanggap agad ng gumagamit ang mga ito. Para sa background gamitin ang 5 — maaaring maantala ng system ang paghahatid upang makatipid ng baterya. Ang maling priyoridad para sa background ay maaaring humantong sa pagtanggi ng notification ng APNS.

Format ng Payload ng APNS

Tumatanggap ang APNS ng payload sa JSON format na may maximum na sukat na 4 KB para sa ordinaryong notification at 5 KB para sa VOIP. Ang payload ay naglalaman ng sapilitang diksyunaryong aps na may mga setting ng pagpapakita at opsyonal na custom na mga field.

{
    "aps": {
        "alert": {
            "title": "Bagong mensahe",
            "body": "Mayroon kang 3 hindi nababasang chat"
        },
        "badge": 3,
        "sound": "default",
        "category": "message_category",
        "thread-id": "chat_room_42"
    },
    "customData": {
        "chatId": "42"
    }
}

Ang key na thread-id ay nag-grupo ng mga notification sa iOS Notification Center. Ang key na category ay nag-uugnay ng notification sa UNNotificationCategory para sa pagpapakita ng mga action button. Kung wala ang mga key na ito, lahat ng notification ay ipinapakita nang paisa-isa.

Mga Custom na Field sa APNS Payload

Bukod sa sapilitang diksyunaryong aps, ang APNS payload ay maaaring maglaman ng anumang custom na field sa pinakamataas na antas. Ang mga field na ito ay accessible sa app sa pamamagitan ng userInfo dictionary kapag pinoproseso ang notification. Ang custom na data ay kapaki-pakinabang para sa pagpapadala ng mga entity ID, screen, o link. Ang maximum na sukat ng payload ay 4 KB, kaya iwasan ang pagpapadala ng malaking halaga ng data sa pamamagitan ng push; i-load ang mga ito sa pamamagitan ng API pagkatapos buksan ang notification.

Halimbawa ng Pagpapadala sa pamamagitan ng HTTP/2 API

Upang magpadala ng push notification sa server, kailangan mong magsagawa ng POST request sa APNS endpoint na may tamang authentication headers. Sa ibaba ay isang halimbawa sa Node.js gamit ang Token-based authentication.

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: "Kamusta!", body: "Test 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("Matagumpay na naipadala ang push")
    }
})

Pagkatapos ng pagpapadala, ibinabalik ng APNS ang HTTP status na 200 para sa matagumpay na paghahatid o error code na may paglalarawan sa body ng tugon. Mahalagang hawakan ang error na token-unregistered (410) — ang naturang token ay dapat tanggalin sa server dahil ang app ay tinanggal na sa device.

Mga Error ng APNS at ang Kanilang Paghawak

Ibinabalik ng APNS ang mga HTTP status para sa bawat kahilingan sa pagpapadala. Matagumpay na pagpapadala — status 200. Ang mga error ay nangangailangan ng iba't ibang mga estratehiya sa paghawak. BadDeviceToken (400) o Unregistered (410) — ang token ng device ay luma na, dapat tanggalin mula sa server. PayloadTooLarge (413) — nalampasan ang limit na 4 KB, paikliin ang payload.

Error TooManyRequests (429) — nalampasan ang limit ng mga kahilingan. Nagtatakda ang APNS ng quota sa bilang ng mga pagpapadala bawat segundo. Kapag nakatanggap ng 429, kailangan mong magpatupad ng exponential backoff at subukan muli ang pagpapadala. Inirerekomenda na huwag lumampas sa 100 kahilingan bawat segundo bawat HTTP/2 connection.

Mga error mula sa panig ng APNS — 500 at 503 (Internal Server Error / Service Unavailable). Ito ay mga pansamantalang pagkasira ng imprastraktura ng Apple. Sa ganitong mga kaso, ulitin ang pagpapadala na may pagkaantala ng 1–5 segundo, hindi hihigit sa 3 pagtatangka. Ang patuloy na 5xx error sa ganap na gumaganang server ay bihira at karaniwang nauugnay sa mga problema sa TLS connection.

Para sa Production na kapaligiran, kinakailangan mong ipatupad ang pag-log ng lahat ng APNS error na may indikasyon ng token, error code, at oras. Makakatulong ito upang mabilis na matukoy ang mga problema sa mga certificate, quota, o partikular na device token. Regular na suriin ang expiry date ng mga certificate kung gumagamit ka ng Certificate-based authentication.