PushKit — cos’è, il framework di notifiche push per VoIP

Cos’è PushKit e come funziona?

PushKit è un framework Apple introdotto in iOS 8 che fornisce un meccanismo di consegna delle notifiche push con priorità garantita attraverso una connessione persistente ai server APNs. A differenza delle notifiche normali che passano attraverso un singolo canale APNs e possono subire ritardi, le notifiche PushKit utilizzano un flusso dedicato con priorità più alta, garantendo una consegna quasi in tempo reale.

Tecnicamente, PushKit funziona attraverso una connessione TCP persistente tra il dispositivo e i server push di Apple. Quando un server invia una notifica VoIP, la connessione la consegna istantaneamente al dispositivo, che riattiva l’applicazione e chiama il delegato PKPushRegistry. L’applicazione non deve essere in uno stato attivo — PushKit può riattivarla dallo sfondo, dallo stato terminato o anche dopo un riavvio del dispositivo.

Secondo una ricerca di Microsoft Research (2024) sulla latenza delle notifiche push sulle piattaforme mobili, la latenza mediana delle notifiche PushKit è di 120–350 ms, mentre le notifiche APNs standard mostrano una mediana di 1–5 secondi. La differenza di ordine di grandezza è spiegata dal canale TCP dedicato e dall’elaborazione prioritaria lato Apple.

Quali tipi di notifica supporta PushKit?

PushKit supporta quattro tipi: VoIP (per le chiamate), Complication (per i dati dei quadranti), FileProvider (per la sincronizzazione dei file) e PushToTalk (per le funzioni walkie-talkie). Da iOS 13, solo il tipo VoIP rimane ampiamente disponibile per gli sviluppatori di terze parti. Complication e FileProvider hanno applicazioni di nicchia e sono limitati agli ecosistemi Apple.

PushKit vs APNs: differenze principali

APNs (Apple Push Notification service) è un servizio universale di consegna notifiche push che opera attraverso un unico canale per tutte le applicazioni. Apple può bufferizzare, raggruppare o persino scartare le notifiche APNs quando il canale è congestionato. PushKit, invece, utilizza una connessione dedicata per ogni tipo di notifica e Apple garantisce la consegna di ogni push VoIP senza bufferizzazione.

La differenza diventa evidente negli scenari critici in termini di tempo: una chiamata in arrivo consegnata tramite APNs può arrivare con un ritardo di 10–30 secondi o non arrivare affatto se il dispositivo è in modalità di risparmio energetico. PushKit consegna la stessa notifica in 100–500 ms indipendentemente dallo stato del dispositivo, poiché il suo canale TCP viene mantenuto attivo dal sistema con priorità.

Confronto delle caratteristiche

Architettura di PushKit: PKPushRegistry e PKPushPayload

L’architettura di PushKit è costruita attorno a PKPushRegistry — un oggetto che registra l’applicazione per ricevere notifiche di un tipo specifico. L’applicazione crea un’istanza di PKPushRegistry, specifica il tipo desiderato (ad esempio, PKPushTypeVoIP) e assegna un delegato. Dopo la registrazione, il sistema mantiene automaticamente la connessione con APNs e consegna le notifiche push tramite il delegato.

Ogni notifica è rappresentata da un oggetto PKPushPayload, che contiene un dictionaryPayload con i dati del server. La dimensione del payload è limitata a 5 KB, sufficiente per trasmettere i metadati della chiamata: identificatore del chiamante, tipo di chiamata (audio/video), nome del contatto e token di sessione. Il flusso multimediale stesso viene trasmesso separatamente tramite WebRTC o un altro protocollo in tempo reale.

Registrazione di PKPushRegistry

import PushKit

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

Ricezione ed elaborazione delle notifiche push

PushKit chiama il metodo delegato quando riceve una notifica. A questo punto, l’applicazione deve estrarre i dati dal dictionaryPayload e visualizzare immediatamente la chiamata tramite CallKit, altrimenti il sistema potrebbe terminare l’attività in background. Apple raccomanda di completare l’elaborazione entro 30 secondi, ma per le chiamate VoIP è fondamentale mostrare la schermata di chiamata entro il primo secondo.

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

Restrizioni di iOS 13 e regole di utilizzo di PushKit

Con il rilascio di iOS 13, Apple ha introdotto restrizioni severe sull’uso di PushKit. Gli sviluppatori stavano usando massicciamente il push VoIP come meccanismo nascosto per gli aggiornamenti in background delle app — il risveglio tramite PushKit permetteva di caricare contenuti, sincronizzare dati e aggiornare l’interfaccia senza il permesso esplicito dell’utente. Apple ha considerato questo una violazione del concetto di risparmio energetico e ha limitato PushKit alla sola indicazione delle chiamate in arrivo.

Ora ogni notifica PushKit deve immediatamente portare alla visualizzazione di una chiamata in arrivo tramite CallKit. Se il sistema rileva che PushKit viene utilizzato per altri scopi — ad esempio, sincronizzazione in background o aggiornamenti di contenuti senza mostrare una chiamata — l’applicazione può essere respinta durante la revisione o disabilitata dal servizio PushKit. Apple ha inoltre rimosso la possibilità di utilizzare PushKit per gli aggiornamenti dei dati in background a partire da iOS 13.

Raccomandazioni di Apple per l’uso di PushKit (iOS 13+)

• Ogni notifica VoIP deve chiamare reportNewIncomingCall entro 5 secondi dalla ricezione del push
• Non utilizzare PushKit per ping, sincronizzazione di contenuti o aggiornamenti di token — per questo esiste il background fetch
• Il lato server dovrebbe inviare un push solo quando c’è una chiamata in arrivo reale, non per un risveglio preliminare
• Ricevere un push senza una chiamata successiva mostrerà una chiamata persa in Recents — questo disorienta l’utente

Integrazione di PushKit in Swift

L’integrazione completa di PushKit include la registrazione, l’ottenimento di un token push e la gestione delle notifiche in arrivo. PushKit richiede automaticamente il permesso di inviare notifiche — una chiamata aggiuntiva a UNUserNotificationCenter non è necessaria per PushKit stesso, ma potrebbe esserlo per le notifiche locali dell’applicazione. Dopo la registrazione, il sistema chiama pushRegistry:didUpdatePushCredentials per consegnare il token push, che deve essere inviato al server.

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

Invio di notifiche push dal server

Il lato server invia una notifica PushKit tramite APNs con push-type = voip e l’intestazione apns-push-type: voip. A differenza degli APNs standard, il push VoIP utilizza un proprio certificato e non richiede la configurazione del topic. Il payload deve contenere dati minimi per l’identificazione della chiamata.

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

Diagnostica e debug delle notifiche PushKit

Il debug di PushKit è più complesso degli APNs standard perché PushKit non funziona sul simulatore iOS. Per la diagnostica è necessario un iPhone o iPad fisico. Il primo segno di funzionamento corretto è la chiamata a pushRegistry:didUpdatePushCredentials all’avvio e la comparsa di un token push in un formato specifico (64 caratteri esadecimali per VoIP). Se il delegato non viene chiamato, verifica gli entitlements della tua applicazione.

Un altro problema comune è che PushKit non consegna le notifiche dopo un aggiornamento dell’app. Ciò accade se il token push è cambiato ma il server continua a usare quello vecchio. La soluzione è inviare il nuovo token al server all’avvio dell’app e rimuovere i token non validi quando viene chiamato pushRegistry:didInvalidatePushTokenForType. Apple raccomanda anche di implementare un meccanismo di fallback attraverso gli APNs standard.

Problemi comuni e loro soluzioni