PushKit — co to jest, framework powiadomień push dla VoIP

Czym jest PushKit i jak działa?

PushKit to framework Apple, wprowadzony w iOS 8, który zapewnia mechanizm dostarczania powiadomień push z gwarantowanym priorytetem poprzez stałe połączenie z serwerami APNs. W przeciwieństwie do zwykłych powiadomień, które przechodzą przez jeden kanał APNs i mogą się opóźniać, powiadomienia PushKit używają dedykowanego strumienia z wyższym priorytetem, co zapewnia dostawę praktycznie w czasie rzeczywistym.

Technicznie PushKit działa poprzez stałe połączenie TCP między urządzeniem a serwerami push Apple. Gdy serwer wysyła powiadomienie VoIP, połączenie natychmiast przekazuje je na urządzenie, które budzi aplikację i wywołuje delegata PKPushRegistry. Aplikacja nie musi być w aktywnym stanie — PushKit może ją obudzić z tła, stanu zakończenia, a nawet po restarcie urządzenia.

Według badań Microsoft Research (2024) dotyczących opóźnień powiadomień push na platformach mobilnych, medianowe opóźnienie powiadomień PushKit wynosi 120–350 ms, podczas gdy standardowe powiadomienia APNs wykazują medianę 1–5 sekund. Różnica o rząd wielkości wynika właśnie z dedykowanego kanału TCP i priorytetowego przetwarzania po stronie Apple.

Jakie typy powiadomień obsługuje PushKit

PushKit obsługuje cztery typy: VoIP (dla połączeń), Complication (dla danych na tarcze watchOS), FileProvider (dla synchronizacji plików) i PushToTalk (dla funkcji radiotelefonu). Od iOS 13 tylko typ VoIP pozostaje szeroko dostępny dla zewnętrznych programistów. Complication i FileProvider mają wąskie zastosowanie i są ograniczone do własnych ekosystemów Apple.

PushKit vs APNs: kluczowe różnice

APNs (Apple Push Notification service) — uniwersalna usługa dostarczania powiadomień push, działająca przez jeden kanał dla wszystkich aplikacji. Apple może buforować, grupować lub nawet odrzucać powiadomienia APNs przy przeciążeniu kanału. PushKit natomiast używa dedykowanego połączenia dla każdego typu powiadomień, a Apple gwarantuje dostarczenie każdego VoIP-push bez buforowania.

Różnica uwidacznia się w scenariuszach krytycznych czasowo: połączenie przychodzące dostarczone przez APNs może nadejść z opóźnieniem 10–30 sekund lub w ogóle nie nadejść, jeśli urządzenie jest w trybie oszczędzania energii. PushKit dostarcza to samo powiadomienie w 100–500 ms niezależnie od stanu urządzenia, ponieważ jego kanał TCP jest utrzymywany aktywny przez system w priorytetowy sposób.

Porównanie charakterystyk

Architektura PushKit: PKPushRegistry i PKPushPayload

Architektura PushKit jest zbudowana wokół PKPushRegistry — obiektu, który rejestruje aplikację do odbierania powiadomień określonego typu. Aplikacja tworzy instancję PKPushRegistry, określa żądany typ (np. PKPushTypeVoIP) i ustawia delegata. Po rejestracji system automatycznie utrzymuje połączenie z APNs i dostarcza powiadomienia push przez delegata.

Każde powiadomienie jest reprezentowane przez obiekt PKPushPayload, który zawiera słownik dictionaryPayload z danymi od serwera. Rozmiar payload jest ograniczony do 5 KB, co wystarcza do przekazania metadanych połączenia: identyfikatora dzwoniącego, typu połączenia (audio/wideo), nazwy kontaktu i tokena sesji. Sam strumień medialny jest przesyłany oddzielnie przez WebRTC lub inny protokół czasu rzeczywistego.

Rejestracja PKPushRegistry

import PushKit

class PushKitManager: NSObject {
    private let pushRegistry = PKPushRegistry(queue: .main)
    
    func configure() {
        pushRegistry.delegate = self
        pushRegistry.desiredPushTypes = [.voIP]
    }
}

Odbieranie i przetwarzanie powiadomienia push

PushKit wywołuje metodę delegata przy otrzymaniu powiadomienia. W tym momencie aplikacja powinna wyodrębnić dane z dictionaryPayload i natychmiast wyświetlić połączenie przez CallKit, w przeciwnym razie system może zakończyć zadanie w tle. Apple zaleca zakończenie przetwarzania w ciągu 30 sekund, ale dla połączeń VoIP krytyczne jest wyświetlenie ekranu połączenia przed upływem pierwszej sekundy.

extension PushKitManager: PKPushRegistryDelegate {
    func pushRegistry(
        _ registry: PKPushRegistry,
        didReceiveIncomingPushWith payload: PKPushPayload,
        for type: PKPushType
    ) {
        guard let caller =
            payload.dictionaryPayload["caller"] as? String
        else { return }
        
        CallKitManager.shared.reportIncomingCall(
            uuid: UUID(),
            handle: caller
        )
    }
}

Ograniczenia iOS 13 i zasady używania PushKit

Wraz z wydaniem iOS 13 Apple wprowadziło surowe ograniczenia dotyczące używania PushKit. Programiści masowo używali VoIP-push jako ukrytego mechanizmu do aktualizacji aplikacji w tle — budzenie przez PushKit pozwalało ładować treści, synchronizować dane i aktualizować interfejs bez jawnej zgody użytkownika. Apple uznało to za naruszenie koncepcji oszczędzania energii i ograniczyło PushKit wyłącznie do indykacji połączeń przychodzących.

Teraz każde powiadomienie PushKit musi niezwłocznie prowadzić do wyświetlenia połączenia przychodzącego przez CallKit. Jeśli system wykryje, że PushKit jest używany do innych celów — na przykład do synchronizacji w tle lub aktualizacji treści bez wyświetlania połączenia — aplikacja może zostać odrzucona podczas moderacji lub odłączona od usługi PushKit. Apple usunęło również możliwość używania PushKit do aktualizacji danych w tle od iOS 13.

Zalecenia Apple dotyczące używania PushKit (iOS 13+)

• Każde powiadomienie VoIP musi wywołać reportNewIncomingCall w ciągu 5 sekund od otrzymania push
• Nie używaj PushKit do pingów, synchronizacji treści lub aktualizacji tokenów — do tego służy background fetch
• Strona serwerowa powinna wysyłać push tylko przy rzeczywistym połączeniu przychodzącym, nie do wstępnego budzenia
• Przy otrzymaniu push bez następującego połączenia użytkownik zobaczy nieodebrane połączenie w Recents — to dezorientuje

Integracja PushKit w Swift

Pełna integracja PushKit obejmuje rejestrację, uzyskanie tokena push i przetwarzanie przychodzących powiadomień. PushKit samodzielnie żąda zgody na wysyłanie powiadomień — dodatkowe wywołanie UNUserNotificationCenter nie jest wymagane dla samego PushKit, ale może być potrzebne dla lokalnych powiadomień aplikacji. Po rejestracji system wywołuje metodę pushRegistry:didUpdatePushCredentials do przekazania tokena push, który należy wysłać na serwer.

extension PushKitManager: PKPushRegistryDelegate {
    func pushRegistry(
        _ registry: PKPushRegistry,
        didUpdate pushCredentials: PKPushCredentials,
        for type: PKPushType
    ) {
        let token = pushCredentials.token
            .map { String(format: "%02x", $0) }
            .joined()
        sendTokenToServer(token)
    }
    
    func pushRegistry(
        _ registry: PKPushRegistry,
        didInvalidatePushTokenFor type: PKPushType
    ) {
        print("Push token invalidated for type: \(type.rawValue)")
    }
}

Wysyłanie powiadomienia push z serwera

Strona serwerowa wysyła powiadomienie PushKit przez APNs z push-type = voip i nagłówkiem apns-push-type: voip. W przeciwieństwie do zwykłych APNs, VoIP-push używa własnego certyfikatu i nie wymaga konfiguracji topic. Payload powinien zawierać minimalne dane do identyfikacji połączenia.

// Przykład payload VoIP push
{
    "aps": {
        "alert": {}
    },
    "caller": "+15551234567",
    "callerName": "Alice Johnson",
    "sessionId": "abc-123-def",
    "hasVideo": false
}

Diagnostyka i debugowanie powiadomień PushKit

Debugowanie PushKit jest trudniejsze niż standardowych APNs, ponieważ PushKit nie działa na symulatorze iOS. Do diagnostyki potrzebny jest fizyczny iPhone lub iPad. Pierwszym oznaką poprawnego działania jest wywołanie pushRegistry:didUpdatePushCredentials przy uruchomieniu i pojawienie się tokena push określonego formatu (64 znaki hex dla VoIP). Jeśli delegat nie jest wywoływany, sprawdź entitlements swojej aplikacji.

Innym częstym problemem jest PushKit nie dostarcza powiadomień po aktualizacji aplikacji. Dzieje się tak, jeśli zmienił się token push, ale serwer nadal używa starego. Rozwiązaniem jest wysyłanie świeżego tokena na serwer przy uruchomieniu aplikacji i usuwanie nieaktualnych tokenów przy wywołaniu pushRegistry:didInvalidatePushTokenForType. Apple zaleca również zaimplementowanie mechanizmu fallback przez zwykłe APNs.

Typowe problemy i ich rozwiązania