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

Co to jest PushKit

PushKit to framework od Apple, wprowadzony w iOS 8, który zapewnia dostarczanie powiadomień push z niskim opóźnieniem dla aplikacji VoIP. W przeciwieństwie do standardowego APNs (Apple Push Notification service), PushKit pozwala aplikacji obudzić się w tle po otrzymaniu połączenia przychodzącego, bez wyświetlania powiadomienia użytkownikowi. Jest to krytyczne dla aplikacji głosowych i wideo — użytkownik otrzymuje połączenie natychmiast, nawet jeśli aplikacja jest zamknięta. Według Apple WWDC 2024, PushKit przetwarza ponad 2 miliardy powiadomień VoIP dziennie na całym świecie.

Jak działa PushKit

Mechanizm działania opiera się na bezpośrednim połączeniu między urządzeniem a serwerem push Apple, omijając standardowy kanał powiadomień. Gdy serwer aplikacji wysyła powiadomienie VoIP, przechodzi ono przez dedykowany serwer PushKit i jest dostarczane na urządzenie z maksymalnym priorytetem. System budzi aplikację w tle i wywołuje metodę delegata pushRegistry:didReceiveIncomingPushWithPayload:forType:. Aplikacja otrzymuje payload, przetwarza połączenie i wywołuje completion handler w celu potwierdzenia. Cały cykl od wysłania do przetworzenia zajmuje nie więcej niż 5 sekund, co zostało potwierdzone specyfikacją Apple.

Różnice między PushKit a APNs

Podstawowa różnica między PushKit a APNs polega na mechanizmie dostarczania i przetwarzania. APNs używa standardowego kanału powiadomień z wyświetlaniem banera, dźwięku lub plakietki, podczas gdy PushKit dostarcza dane bezpośrednio do aplikacji bez wizualnego powiadomienia. Poniżej znajduje się tabela porównawcza kluczowych cech.

PushKit nie obsługuje również bogatych załączników multimedialnych i nie może być używany do zwykłych powiadomień marketingowych. Apple ściśle kontroluje użycie PushKit — aplikacja musi mieć wyraźną funkcjonalność VoIP, w przeciwnym razie zostanie odrzucona podczas recenzji. APNs pozostaje uniwersalnym rozwiązaniem dla wszystkich innych scenariuszy.

Rejestracja i otrzymywanie powiadomień VoIP

Aby korzystać z PushKit, aplikacja musi zarejestrować się przez PKPushRegistry z typem pushType .voIP. Rejestracja odbywa się raz przy pierwszym uruchomieniu, po czym system generuje unikalny token push i przekazuje go przez delegata. Token ten jest wysyłany na serwer aplikacji w celu późniejszego wysyłania powiadomień VoIP. Poniżej znajduje się przykład rejestracji PushKit i uzyskania tokena w Swift.

Konfiguracja rejestracji PushKit

import PushKit

let registry = PKPushRegistry(queue: DispatchQueue.main)
registry.delegate = self
registry.desiredPushTypes = [.voIP]

// MARK: - PKPushRegistryDelegate
func pushRegistry(
    _ registry: PKPushRegistry,
    didUpdate pushCredentials: PKPushCredentials,
    for type: PKPushType
) {
    let deviceToken = pushCredentials.token
        .map { String.format("%02x", $0) }
        .joined()
    sendVoIPTokenToServer(deviceToken)
}

Po wywołaniu desiredPushTypes z PKPushType.voIP system automatycznie żąda uprawnień do otrzymywania powiadomień VoIP. W metodzie pushRegistry:didUpdatePushCredentials:forType: aplikacja otrzymuje device token w postaci Data, który jest konwertowany na hex-string i wysyłany na serwer. Token jest unikalny dla każdego urządzenia i zmienia się przy ponownej instalacji aplikacji — serwer musi obsługiwać aktualizację tokena.

Otrzymywanie powiadomienia przychodzącego

func pushRegistry(
    _ registry: PKPushRegistry,
    didReceiveIncomingPushWith payload: PKPushPayload,
    for type: PKPushType,
    completion: @escaping VoidBlock
) {
    guard let caller = payload.dictionaryPayload["caller"] as? String else {
        completion()
        return
    }

    let update = CXCallUpdate()
    update.remoteHandle = CXHandle(type: .generic, value: caller)

    provider.reportNewIncomingCall(
        with: UUID(),
        update: update,
        completion: { error in
            if let error = error {
                print("Call error: \(error)")
            }
            completion()
        }
    )
}

W metodzie didReceiveIncomingPushWith aplikacja otrzymuje payload z danymi połączenia. Po wyodrębnieniu informacji o dzwoniącym tworzony jest CXCallUpdate z frameworku CallKit w celu wyświetlenia ekranu połączenia przychodzącego. Ważne jest wywołanie completion handler po zakończeniu przetwarzania — w przeciwnym razie system może przymusowo zakończyć proces aplikacji z powodu przekroczenia czasu. Maksymalny czas przetwarzania wynosi 30 sekund, po którym iOS uznaje powiadomienie za nieprzetworzone.

Obsługa połączeń przychodzących z CallKit

PushKit jest ściśle zintegrowany z CallKit — frameworkiem do wyświetlania systemowego interfejsu połączeń na iOS. Gdy aplikacja otrzymuje powiadomienie VoIP przez PushKit, musi utworzyć CXProvider i CXCallController w celu zarządzania połączeniem. CallKit automatycznie pokazuje ekran połączenia przychodzącego na ekranie blokady, nawet jeśli aplikacja jest zminimalizowana. Poniżej znajduje się przykład konfiguracji dostawcy CallKit.

let config = CXProviderConfiguration(localizedName: "MyApp")
config.supportsVideo = true
config.maximumCallGroups = 1
config.maximumCallsPerCallGroup = 1
config.supportedHandleTypes = [.phoneNumber, .generic]

let provider = CXProvider(configuration: config)
provider.setDelegate(self, queue: nil)

CXProviderConfiguration określa wygląd i zachowanie ekranu połączenia — nazwę aplikacji, obsługę wideo, liczbę jednoczesnych połączeń. Integracja PushKit z CallKit jest obowiązkowa dla aplikacji VoIP: bez niej system nie pokaże ekranu połączenia przychodzącego, a użytkownik przegapi połączenie. Apple wymaga używania CallKit dla wszystkich aplikacji korzystających z PushKit.

Funkcje i ograniczenia

Korzystanie z PushKit nakłada szereg ścisłych ograniczeń ustanowionych przez Apple. Framework może być używany tylko do funkcjonalności VoIP — wszelkie próby wysyłania powiadomień marketingowych przez PushKit doprowadzą do zablokowania aplikacji. Rozmiar payload nie może przekraczać 4 KB i może zawierać tylko dane JSON bez załączników. Począwszy od iOS 13, Apple wprowadziło ograniczenie częstotliwości wysyłania powiadomień VoIP — nie więcej niż jedno powiadomienie na minutę na urządzenie. Serwer musi przestrzegać tego ograniczenia, w przeciwnym razie powiadomienia zostaną odrzucone przez system. PushKit nie działa również na symulatorze iOS — testowanie jest możliwe tylko na fizycznym urządzeniu.

Struktura payloadu PushKit

Payload powiadomienia VoIP to słownik JSON z niestandardowymi danymi o połączeniu. W przeciwieństwie do APNs, PushKit nie obsługuje standardowych pól alert, badge i sound — wszystkie dane są definiowane przez programistę. Typowa struktura obejmuje identyfikator dzwoniącego (caller), typ połączenia (voice lub video), identyfikator pokoju lub sesji oraz znacznik czasu. Rozmiar każdego pola powinien być minimalny, aby zaoszczędzić miejsce w limicie 4 KB. Apple zaleca umieszczanie w payload tylko danych niezbędnych do wyświetlenia ekranu połączenia przychodzącego na ekranie blokady, a pozostałe informacje (avatar, historię czatu) ładować po odebraniu przez użytkownika osobnym żądaniem sieciowym. Przykład minimalnego payloadu: { „caller“: „Anna“, „caller_id“: „+79161234567“, „type“: „audio“, „room“: „uuid-room-1234“, „ts“: 1718534400 }. Wszystkie klucze w payload powinny być krótkie, jednoznaczne i udokumentowane po stronie serwera w celu zachowania zgodności między wersjami aplikacji.

Obsługa błędów i ponowne próby

Podczas pracy z PushKit należy przewidzieć obsługę błędów dostarczenia i utraty połączenia. Jeśli urządzenie jest w trybie offline lub odłączone od sieci, powiadomienie VoIP nie zostanie dostarczone — PushKit nie obsługuje przechowywania i ponownego wysyłania, w przeciwieństwie do APNs, które przechowują powiadomienie do 24 godzin w celu ponownej próby. Serwer musi samodzielnie śledzić niedostarczone powiadomienia i ponawiać próbę po przywróceniu połączenia. W tym celu wykorzystuje się mechanizm push kit feedback service — zwraca on listę niedostarczonych powiadomień z wskazaniem przyczyny błędu. Zaleca się skonfigurowanie monitorowania skuteczności dostarczania powiadomień VoIP poprzez analitykę serwerową i powiadamianie programisty o spadku odsetka pomyślnie dostarczonych powiadomień poniżej 95%. System PushKit gwarantuje dostarczenie tylko przy aktywnym połączeniu internetowym na urządzeniu — w przypadku jego braku powiadomienie jest bezpowrotnie tracone, co jest krytyczne przy projektowaniu niezawodnego systemu połączeń VoIP z gwarantowanym dostarczeniem.