APNS: ce este, structura Apple Push Notification Service și cum funcționează

Ce este APNS?

Apple Push Notification Service (APNS) — este serviciul propriu Apple pentru rutarea notificărilor push de la serverul aplicației la dispozitivele utilizatorilor. Spre deosebire de FCM, APNS nu acceptă Android sau alte platforme — este complet legat de ecosistemul Apple.

Serviciul funcționează printr-o conexiune TLS permanentă pe care fiecare dispozitiv Apple o stabilește cu serverele APNS la pornire. Această conexiune este menținută în fundal și utilizată pentru livrarea notificărilor cu întârziere minimă.

APNS preia întreaga infrastructură de livrare: criptare, autentificare, prioritizare și re-trimitere în cazul indisponibilității dispozitivului. Dezvoltatorul trebuie doar să furnizeze un payload corect formatat și un push token valid.

Evoluția APNS

Inițial APNS funcționa printr-un protocol binar pe porturile 2195–2196. Din 2015, Apple a trecut la protocolul modern HTTP/2, care suportă multiplexare, compresie antete și notificări push de la server. HTTP/2 a devenit obligatoriu din iunie 2020.

Cum funcționează Apple Push Notification Service?

Procesul de livrare a unei notificări push prin APNS constă din cinci etape: înregistrarea dispozitivului, obținerea push token-ului, trimiterea cererii de către server, rutarea APNS și livrarea pe dispozitiv.

• Înregistrare — la pornire, aplicația apelează registerForRemoteNotifications, sistemul se conectează la APNS
• Token — APNS returnează dispozitivului un push token — un șir unic care identifică aplicația pe dispozitiv
• Trimitere — serverul aplicației trimite o cerere POST la https://api.push.apple.com cu tokenul și payloadul
• Rutare — APNS găsește dispozitivul după token și livrează mesajul prin conexiunea TLS
• Procesare — iOS/macOS afișează notificarea sau o transmite aplicației în funcție de stare

Dacă dispozitivul este indisponibil (oprit sau fără rețea), APNS stochează ultimul mesaj pentru fiecare aplicație și îl livrează la restabilirea conexiunii. Perioada maximă de stocare — 4 săptămâni, după care mesajul este șters.

Autentificarea în APNS: Token și Certificat

Apple acceptă două metode de autentificare a serverului aplicației la trimiterea notificărilor push. Fiecare metodă are caracteristici proprii privind perioada de valabilitate, gestionarea și ușurința de utilizare.

Token-based autentificare — metoda recomandată de Apple din 2019. Creați o cheie p8 în Apple Developer Console, o încărcați pe server și semnați fiecare cerere APNS cu ea. Cheia nu expiră și funcționează pentru toate aplicațiile contului dumneavoastră.

Ce metodă de autentificare să alegeți

Pentru proiecte noi, Token-based autentificare este cu siguranță preferabilă: o singură cheie p8 pentru întreg contul, permanentă, fără legătură cu mediul. Certificate-based (.p12) este încă folosită în proiecte legacy, dar necesită înlocuire anuală și certificate separate pentru Sandbox și Production. Luați în considerare termenul de expirare a certificatului la planificarea CI/CD.

Tipuri de notificări push APNS

APNS acceptă trei tipuri de notificări push, care diferă prin comportamentul pe dispozitiv și cerințele de atribute ale cererii. Alegerea tipului depinde de scenariul UX și de urgența mesajului.

• Alert — notificare standard cu titlu, text și butoane de acțiune opționale
• Background — livrare silențioasă de date (silent push) fără afișare utilizatorului, procesată în application:didReceiveRemoteNotification
• VOIP — tip special pentru aplicații VoIP (PushKit), livrat imediat chiar și cu aplicația închisă

Pentru notificările Background trebuie să indicați cheia content-available: 1 și să setați prioritatea 5 (livrare eficientă energetic). Sistemul poate limita numărul de notificări de fundal dacă aplicația nu le procesează la timp.

Configurarea priorității de livrare

APNS acceptă două valori de prioritate: 10 (livrare imediată) și 5 (eficientă energetic). Pentru notificările alert utilizați 10 — utilizatorul trebuie să le primească imediat. Pentru background utilizați 5 — sistemul poate întârzia livrarea pentru economisirea bateriei. Prioritatea incorectă pentru background poate duce la respingerea notificării de către APNS.

Formatul payload-ului APNS

APNS acceptă payload în format JSON cu dimensiunea maximă de 4 KB pentru notificări obișnuite și 5 KB pentru VOIP. Payloadul conține dicționarul obligatoriu aps cu setări de afișare și câmpuri personalizate opționale.

{
    "aps": {
        "alert": {
            "title": "Mesaj nou",
            "body": "Ai 3 chat-uri necitite"
        },
        "badge": 3,
        "sound": "default",
        "category": "message_category",
        "thread-id": "chat_room_42"
    },
    "customData": {
        "chatId": "42"
    }
}

Cheia thread-id grupează notificările în Centrul de notificări iOS. Cheia category leagă notificarea de UNNotificationCategory pentru afișarea butoanelor de acțiune. Fără aceste chei, toate notificările sunt afișate individual.

Câmpuri personalizate în payload-ul APNS

Pe lângă dicționarul obligatoriu aps, payload-ul APNS poate conține orice câmpuri personalizate la nivelul superior. Aceste câmpuri sunt accesibile aplicației prin dicționarul userInfo la procesarea notificării. Datele personalizate sunt utile pentru transmiterea identificatorilor de entități, ecrane sau linkuri. Dimensiunea maximă a payload-ului este de 4 KB, așa că evitați transmiterea volumelor mari de date prin push; încărcați-le prin API după deschiderea notificării.

Exemplu de trimitere prin HTTP/2 API

Pentru a trimite o notificare push pe server, trebuie să efectuați o cerere POST la endpointul APNS cu antetele de autentificare corecte. Mai jos este un exemplu în Node.js cu autentificare 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: "Salut!", body: "Push de test" } }
})

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 trimis cu succes")
    }
})

După trimitere, APNS returnează statusul HTTP 200 la livrare reușită sau un cod de eroare cu descriere în corpul răspunsului. Este important să gestionați eroarea token-unregistered (410) — un astfel de token trebuie șters de pe server, deoarece aplicația a fost ștearsă de pe dispozitiv.

Erori APNS și gestionarea lor

APNS returnează statusuri HTTP pentru fiecare cerere de trimitere. Trimitere reușită — status 200. Erorile necesită strategii diferite de gestionare. BadDeviceToken (400) sau Unregistered (410) — tokenul dispozitivului este expirat, trebuie șters de pe server. PayloadTooLarge (413) — limita de 4 KB a fost depășită, reduceți payloadul.

Eroarea TooManyRequests (429) — limita de cereri a fost depășită. APNS stabilește o cotă pentru numărul de trimiteri pe secundă. La primirea 429, trebuie să implementațI o întârziere exponențială (exponential backoff) și să reîncercați trimiterea. Se recomandă să nu depășiți 100 de cereri pe secundă per conexiune HTTP/2.

Erori de partea APNS — 500 și 503 (Internal Server Error / Service Unavailable). Acestea sunt defecțiuni temporare ale infrastructurii Apple. În astfel de cazuri, repetați trimiterea cu o întârziere de 1–5 secunde, de cel mult 3 ori. Erorile constante 5xx pe un server complet funcțional sunt rare și de obicei legate de probleme ale conexiunii TLS.

Pentru mediul Production, implementați obligatoriu jurnalizarea tuturor erorilor APNS cu indicarea tokenului, codului de eroare și timpului. Aceasta va ajuta la identificarea rapidă a problemelor cu certificatele, cotele sau tokenurile specifice ale dispozitivelor. Verificați regulat termenul de valabilitate al certificatelor dacă utilizați autentificarea Certificate-based.