PushKit — ce este, framework-ul notificărilor VoIP pentru iOS

Ce este PushKit

PushKit este un framework de la Apple, introdus în iOS 8, care asigură livrarea notificărilor push cu latență redusă pentru aplicațiile VoIP. Spre deosebire de APNs standard (Apple Push Notification service), PushKit permite aplicației să se trezească în fundal la primirea unui apel primit, fără a afișa o notificare utilizatorului. Acest lucru este critic pentru aplicațiile de voce și video — utilizatorul primește apelul instantaneu, chiar dacă aplicația este închisă. Potrivit Apple WWDC 2024, PushKit procesează peste 2 miliarde de notificări VoIP zilnic la nivel mondial.

Cum funcționează PushKit

Mecanismul de funcționare se bazează pe o conexiune directă între dispozitiv și serverul push Apple, ocolind canalul standard de notificări. Când serverul aplicației trimite o notificare VoIP, aceasta trece printr-un server dedicat PushKit și este livrată către dispozitiv cu prioritate maximă. Sistemul trezește aplicația în fundal și apelează metoda delegatului pushRegistry:didReceiveIncomingPushWithPayload:forType:. Aplicația primește payload-ul, procesează apelul și apelează completion handler-ul pentru confirmare. Întregul ciclu de la trimitere la procesare durează cel mult 5 secunde, conform specificațiilor Apple.

Diferențele dintre PushKit și APNs

Diferența principală între PushKit și APNs constă în mecanismul de livrare și procesare. APNs folosește canalul standard de notificări cu afișarea unui banner, sunet sau insignă, în timp ce PushKit livrează datele direct în aplicație fără notificare vizuală. Mai jos este un tabel comparativ al caracteristicilor cheie.

PushKit nu suportă nici atașamente media bogate și nu poate fi folosit pentru notificări obișnuite de marketing. Apple controlează strict utilizarea PushKit — aplicația trebuie să aibă o funcționalitate VoIP explicită, altfel va fi respinsă la revizuire. APNs rămâne soluția universală pentru toate celelalte scenarii.

Înregistrarea și primirea notificărilor VoIP

Pentru a utiliza PushKit, aplicația trebuie să se înregistreze prin PKPushRegistry cu tipul pushType .voIP. Înregistrarea se face o singură dată la prima pornire, după care sistemul generează un token push unic și îl transmite prin delegat. Acest token este trimis pe serverul aplicației pentru trimiterea ulterioară a notificărilor VoIP. Mai jos este un exemplu de înregistrare PushKit și obținere token în Swift.

Configurarea înregistrării 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)
}

După apelarea desiredPushTypes cu PKPushType.voIP, sistemul solicită automat permisiunea de a primi notificări VoIP. În metoda pushRegistry:didUpdatePushCredentials:forType: aplicația primește device token ca Data, care este convertit într-un șir hex și trimis pe server. Token-ul este unic pentru fiecare dispozitiv și se schimbă la reinstalarea aplicației — serverul trebuie să gestioneze actualizarea token-ului.

Primirea notificării primite

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()
        }
    )
}

În metoda didReceiveIncomingPushWith aplicația primește payload-ul cu datele apelului. După extragerea informațiilor despre apelant, se creează un CXCallUpdate din framework-ul CallKit pentru afișarea ecranului apelului primit. Este important să se apeleze completion handler-ul după terminarea procesării — altfel, sistemul poate termina forțat procesul aplicației din cauza depășirii timpului. Timpul maxim de procesare este de 30 de secunde, după care iOS consideră notificarea neprocesată.

Gestionarea apelurilor primite cu CallKit

PushKit este strâns integrat cu CallKit — framework-ul pentru afișarea interfeței sistemice de apeluri pe iOS. Când aplicația primește o notificare VoIP prin PushKit, trebuie să creeze un CXProvider și CXCallController pentru gestionarea apelului. CallKit afișează automat ecranul apelului primit pe ecranul de blocare, chiar dacă aplicația este minimizată. Mai jos este un exemplu de configurare a provider-ului 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 definește aspectul și comportamentul ecranului de apel — numele aplicației, suportul video, numărul de apeluri simultane. Integrarea PushKit cu CallKit este obligatorie pentru aplicațiile VoIP: fără ea, sistemul nu va afișa ecranul apelului primit, iar utilizatorul va pierde apelul. Apple impune utilizarea CallKit pentru toate aplicațiile care folosesc PushKit.

Caracteristici și limitări

Utilizarea PushKit impune o serie de limitări stricte stabilite de Apple. Framework-ul poate fi folosit doar pentru funcționalitatea VoIP — orice încercare de a trimite notificări de marketing prin PushKit va duce la blocarea aplicației. Dimensiunea payload-ului nu trebuie să depășească 4 KB și poate conține doar date JSON fără atașamente. Începând cu iOS 13, Apple a introdus o limitare a frecvenței de trimitere a notificărilor VoIP — cel mult o notificare pe minut per dispozitiv. Serverul trebuie să respecte această limitare, altfel notificările vor fi respinse de sistem. PushKit nu funcționează nici pe simulatorul iOS — testarea este posibilă doar pe un dispozitiv fizic.

Structura payload-ului PushKit

Payload-ul notificării VoIP este un dicționar JSON cu date personalizate despre apel. Spre deosebire de APNs, PushKit nu suportă câmpurile standard alert, badge și sound — toate datele sunt definite de dezvoltator. Structura tipică include identificatorul apelantului (caller), tipul apelului (voice sau video), identificatorul camerei sau sesiunii și marcajul temporal. Dimensiunea fiecărui câmp trebuie să fie minimă pentru a economisi spațiu în limita de 4 KB. Apple recomandă includerea în payload doar a datelor necesare pentru afișarea ecranului apelului primit pe ecranul de blocare, iar restul informațiilor (avatar, istoricul conversațiilor) să fie încărcate după ce utilizatorul răspunde, printr-o cerere de rețea separată. Exemplu de payload minim: { „caller“: „Anna“, „caller_id“: „+79161234567“, „type“: „audio“, „room“: „uuid-room-1234“, „ts“: 1718534400 }. Toate cheile din payload trebuie să fie scurte, fără ambiguități și documentate pe partea de server pentru compatibilitate între versiunile aplicației.

Gestionarea erorilor și reîncercări

La lucrul cu PushKit trebuie prevăzută gestionarea erorilor de livrare și a pierderii conexiunii. Dacă dispozitivul este în modul offline sau deconectat de la rețea, notificarea VoIP nu va fi livrată — PushKit nu suportă stocarea și retrimiterea, spre deosebire de APNs, care stochează notificarea până la 24 de ore pentru reîncercare. Serverul trebuie să urmărească singur notificările nelivrate și să reîncerce după restabilirea conexiunii. În acest scop se utilizează mecanismul push kit feedback service — acesta returnează o listă de notificări nelivrate cu indicarea cauzei erorii. Se recomandă configurarea monitorizării succesului livrării notificărilor VoIP prin analitică pe server și notificarea dezvoltatorului când procentul livrărilor reușite scade sub 95%. Sistemul PushKit garantează livrarea doar când există o conexiune activă la internet pe dispozitiv — în lipsa acesteia, notificarea se pierde iremediabil, ceea ce este critic de luat în considerare la proiectarea unui sistem fiabil de apeluri VoIP cu livrare garantată.