APNS: co to jest, budowa Apple Push Notification Service i jak działa

Co to jest APNS?

Apple Push Notification Service (APNS) — to własny serwis Apple do routingu powiadomień push z serwera aplikacji do urządzeń użytkowników. W przeciwieństwie do FCM, APNS nie obsługuje Androida ani innych platform — jest całkowicie związany z ekosystemem Apple.

Serwis działa poprzez stałe połączenie TLS, które każde urządzenie Apple ustanawia z serwerami APNS przy włączeniu. To połączenie jest utrzymywane w tle i używane do dostarczania powiadomień z minimalnym opóźnieniem.

APNS przejmuje całą infrastrukturę dostarczania: szyfrowanie, uwierzytelnianie, priorytetyzację i ponowne wysyłanie w przypadku niedostępności urządzenia. Deweloper musi tylko dostarczyć poprawnie sformatowany payload i ważny push token.

Ewolucja APNS

Początkowo APNS działał przez protokół binarny na porcie 2195–2196. Od 2015 roku Apple przeszło na nowoczesny protokół HTTP/2, który obsługuje multipleksowanie, kompresję nagłówków i serwerowe push. HTTP/2 stał się obowiązkowy od czerwca 2020 roku.

Jak działa Apple Push Notification Service?

Proces dostarczania powiadomienia push przez APNS składa się z pięciu etapów: rejestracja urządzenia, uzyskanie push token, wysłanie zapytania przez serwer, routing APNS i dostarczenie na urządzenie.

• Rejestracja — przy uruchomieniu aplikacja wywołuje registerForRemoteNotifications, system łączy się z APNS
• Token — APNS zwraca urządzeniu push token — unikalny ciąg identyfikujący aplikację na urządzeniu
• Wysyłanie — serwer aplikacji wysyła zapytanie POST na https://api.push.apple.com z tokenem i payloadem
• Routing — APNS znajduje urządzenie po tokenie i dostarcza wiadomość przez połączenie TLS
• Przetwarzanie — iOS/macOS wyświetla powiadomienie lub przekazuje je do aplikacji w zależności od stanu

Jeśli urządzenie jest niedostępne (wyłączone lub bez sieci), APNS przechowuje ostatnią wiadomość dla każdej aplikacji i dostarcza ją po przywróceniu połączenia. Maksymalny czas przechowywania — 4 tygodnie, po czym wiadomość jest usuwana.

Uwierzytelnianie w APNS: Token i Certyfikat

Apple obsługuje dwa sposoby uwierzytelniania serwera aplikacji przy wysyłaniu powiadomień push. Każdy sposób ma swoje cechy dotyczące okresu ważności, zarządzania i wygody użytkowania.

Token-based uwierzytelnianie — zalecany przez Apple sposób od 2019 roku. Tworzysz jeden klucz p8 w Apple Developer Console, ładujesz go na serwer i podpisujesz nim każde zapytanie APNS. Klucz nie wygasa i działa dla wszystkich aplikacji twojego konta.

Który sposób uwierzytelniania wybrać

Dla nowych projektów Token-based uwierzytelnianie jest jednoznacznie preferowane: jeden klucz p8 na całe konto, bezterminowy, bez zależności od środowiska. Certificate-based (.p12) jest nadal używany w legacy-projektach, ale wymaga corocznej wymiany i oddzielnych certyfikatów dla Sandbox i Production. Uwzględnij czas wygaśnięcia certyfikatu przy planowaniu CI/CD.

Typy powiadomień push APNS

APNS obsługuje trzy typy powiadomień push, które różnią się zachowaniem na urządzeniu i wymaganiami dotyczącymi atrybutów zapytania. Wybór typu zależy od scenariusza UX i pilności wiadomości.

• Alert — standardowe powiadomienie z tytułem, tekstem i opcjonalnymi przyciskami akcji
• Background — ciche dostarczanie danych (silent push) bez pokazywania użytkownikowi, przetwarzane w application:didReceiveRemoteNotification
• VOIP — specjalny typ dla aplikacji VoIP (PushKit), dostarczany natychmiast nawet przy zamkniętej aplikacji

Dla Background powiadomień należy wskazać klucz content-available: 1 i ustawić priorytet 5 (energooszczędne dostarczenie). System może ograniczyć liczbę powiadomień tła, jeśli aplikacja nie przetwarza ich na czas.

Konfiguracja priorytetu dostarczenia

APNS obsługuje dwie wartości priorytetu: 10 (natychmiastowe dostarczenie) i 5 (energooszczędne). Dla alertów używaj 10 — użytkownik powinien otrzymać je od razu. Dla background używaj 5 — system może opóźnić dostarczenie w celu oszczędzania baterii. Nieprawidłowy priorytet dla background może spowodować odrzucenie powiadomienia przez APNS.

Format ładunku APNS

APNS przyjmuje payload w formacie JSON z maksymalnym rozmiarem 4 KB dla zwykłych powiadomień i 5 KB dla VOIP. Payload zawiera obowiązkowy słownik aps z ustawieniami wyświetlania i opcjonalne pola niestandardowe.

{
    "aps": {
        "alert": {
            "title": "Nowa wiadomość",
            "body": "Masz 3 nieprzeczytane czaty"
        },
        "badge": 3,
        "sound": "default",
        "category": "message_category",
        "thread-id": "chat_room_42"
    },
    "customData": {
        "chatId": "42"
    }
}

Klucz thread-id łączy powiadomienia w grupy w Centrum powiadomień iOS. Klucz category łączy powiadomienie z UNNotificationCategory do wyświetlania przycisków akcji. Bez tych kluczy wszystkie powiadomienia są wyświetlane osobno.

Niestandardowe pola w APNS-payładzie

Oprócz obowiązkowego słownika aps, APNS-payład może zawierać dowolne niestandardowe pola na najwyższym poziomie. Te pola są dostępne aplikacji poprzez słownik userInfo przy przetwarzaniu powiadomienia. Niestandardowe dane są wygodne do przekazywania identyfikatorów encji, ekranów lub linków. Maksymalny rozmiar payładu to 4 KB, więc unikaj przesyłania dużych ilości danych przez push; ładuj je przez API po otwarciu powiadomienia.

Przykład wysyłania przez HTTP/2 API

Aby wysłać powiadomienie push na serwerze, należy wykonać zapytanie POST do endpointu APNS z poprawnymi nagłówkami uwierzytelniania. Poniżej znajduje się przykład w Node.js z użyciem uwierzytelniania 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: "Cześć!", body: "Testowy 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 wysłany pomyślnie")
    }
})

Po wysłaniu APNS zwraca status HTTP 200 przy udanym dostarczeniu lub kod błędu z opisem w treści odpowiedzi. Ważne jest obsługiwanie błędów token-unregistered (410) — taki token należy usunąć z serwera, ponieważ aplikacja została usunięta z urządzenia.

Błędy APNS i ich obsługa

APNS zwraca statusy HTTP dla każdego zapytania wysyłania. Udane wysyłanie — status 200. Błędy wymagają różnych strategii obsługi. BadDeviceToken (400) lub Unregistered (410) — token urządzenia jest nieaktualny, należy go usunąć z serwera. PayloadTooLarge (413) — przekroczony limit 4 KB, skróć payład.

Błąd TooManyRequests (429) — przekroczony limit zapytań. APNS ustawia limit na liczbę wysyłek na sekundę. Przy otrzymaniu 429 należy wdrożyć opóźnienie wykładnicze (exponential backoff) i powtórzyć wysyłanie. Zaleca się nie przekraczać 100 zapytań na sekundę na jedno połączenie HTTP/2.

Błędy po stronie APNS — 500 i 503 (Internal Server Error / Service Unavailable). Są to tymczasowe awarie infrastruktury Apple. W takich przypadkach powtarzaj wysyłanie z opóźnieniem 1–5 sekund, nie więcej niż 3 próby. Stałe błędy 5xx przy w pełni działającym serwerze są rzadkim zjawiskiem, zwykle związanym z problemami połączenia TLS.

Dla środowiska Production obowiązkowo zaimplementuj logowanie wszystkich błędów APNS z wskazaniem tokena, kodu błędu i czasu. Pomoże to szybko wykryć problemy z certyfikatami, limitami lub konkretnymi tokenami urządzeń. Regularnie sprawdzaj okres ważności certyfikatów, jeśli używasz uwierzytelniania Certificate-based.