PushKit — cos’è, framework di notifiche VoIP iOS

Cos’è PushKit

PushKit è un framework di Apple, introdotto in iOS 8, che fornisce notifiche push a bassa latenza per applicazioni VoIP. A differenza dell’APNs standard (Apple Push Notification service), PushKit consente all’app di risvegliarsi in background alla ricezione di una chiamata in arrivo, senza mostrare una notifica all’utente. Questo è fondamentale per le app di voce e videochiamata — l’utente riceve la chiamata istantaneamente, anche se l’app è chiusa. Secondo Apple WWDC 2024, PushKit elabora oltre 2 miliardi di notifiche VoIP al giorno in tutto il mondo.

Come funziona PushKit

Il meccanismo si basa su una connessione diretta tra il dispositivo e il server push di Apple, bypassando il canale di notifiche standard. Quando il server dell’app invia una notifica VoIP, questa passa attraverso un server PushKit dedicato e viene consegnata al dispositivo con priorità massima. Il sistema risveglia l’app in background e chiama il metodo delegato pushRegistry:didReceiveIncomingPushWithPayload:forType:. L’app riceve il payload, elabora la chiamata e chiama il completion handler per conferma. L’intero ciclo dall’invio all’elaborazione non richiede più di 5 secondi, secondo le specifiche Apple.

PushKit vs APNs

La differenza principale tra PushKit e APNs risiede nel meccanismo di consegna e nell’elaborazione. APNs utilizza il canale di notifiche standard mostrando un banner, un suono o un badge, mentre PushKit consegna i dati direttamente all’app senza notifica visiva. Di seguito è riportata una tabella comparativa delle caratteristiche principali.

PushKit inoltre non supporta allegati multimediali ricchi e non può essere utilizzato per normali notifiche di marketing. Apple controlla rigorosamente l’uso di PushKit — l’app deve avere funzionalità VoIP esplicita, altrimenti verrà respinta durante la revisione. APNs rimane la soluzione universale per tutti gli altri scenari.

Registrazione e ricezione di notifiche VoIP

Per utilizzare PushKit, l’app deve registrarsi tramite PKPushRegistry con il tipo pushType .voIP. La registrazione viene effettuata una volta al primo avvio, dopodiché il sistema genera un token push univoco e lo trasmette tramite il delegato. Questo token viene inviato al server dell’app per l’invio successivo di notifiche VoIP. Di seguito è riportato un esempio di registrazione PushKit e ottenimento del token in Swift.

Configurazione della registrazione 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)
}

Dopo aver chiamato desiredPushTypes con PKPushType.voIP, il sistema richiede automaticamente l’autorizzazione a ricevere notifiche VoIP. Nel metodo pushRegistry:didUpdatePushCredentials:forType:, l’app riceve il token del dispositivo come Data, che viene convertito in una stringa esadecimale e inviato al server. Il token è univoco per ogni dispositivo e cambia quando l’app viene reinstallata — il server deve gestire gli aggiornamenti del token.

Ricezione di una notifica in arrivo

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

Nel metodo didReceiveIncomingPushWith, l’app riceve il payload con i dati della chiamata. Dopo aver estratto le informazioni del chiamante, viene creato un CXCallUpdate dal framework CallKit per visualizzare la schermata di chiamata in arrivo. È importante chiamare il completion handler dopo l’elaborazione — altrimenti il sistema potrebbe terminare forzatamente il processo dell’app per timeout. Il tempo di elaborazione massimo è di 30 secondi, dopo i quali iOS considera la notifica non elaborata.

Gestione delle chiamate in arrivo con CallKit

PushKit è strettamente integrato con CallKit — un framework per visualizzare l’interfaccia di chiamata di sistema su iOS. Quando l’app riceve una notifica VoIP tramite PushKit, deve creare un CXProvider e CXCallController per gestire la chiamata. CallKit mostra automaticamente la schermata di chiamata in arrivo sulla schermata di blocco, anche se l’app è minimizzata. Di seguito è riportato un esempio di configurazione di un provider 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 definisce l’aspetto e il comportamento della schermata di chiamata — il nome dell’app, il supporto video, il numero di chiamate simultanee. L’integrazione di PushKit con CallKit è obbligatoria per le app VoIP: senza di essa, il sistema non mostrerà la schermata di chiamata in arrivo e l’utente perderà la chiamata. Apple richiede l’uso di CallKit per tutte le app che utilizzano PushKit.

Caratteristiche e limitazioni

L’uso di PushKit comporta una serie di restrizioni severe stabilite da Apple. Il framework può essere utilizzato solo per funzionalità VoIP — qualsiasi tentativo di inviare notifiche di marketing tramite PushKit porterà al blocco dell’app. La dimensione del payload non deve superare i 4 KB e può contenere solo dati JSON senza allegati. A partire da iOS 13, Apple ha introdotto un limite sulla frequenza di invio delle notifiche VoIP — non più di una notifica al minuto per dispositivo. Il server deve rispettare questo limite, altrimenti le notifiche verranno rifiutate dal sistema. PushKit inoltre non funziona sul simulatore iOS — il test è possibile solo su un dispositivo fisico.

Struttura del payload PushKit

Un payload di notifica VoIP è un dizionario JSON con dati di chiamata personalizzati. A differenza di APNs, PushKit non supporta i campi standard alert, badge e sound — tutti i dati sono definiti dallo sviluppatore. Una struttura tipica include l’identificativo del chiamante (caller), il tipo di chiamata (voice o video), l’identificativo della stanza o sessione e un timestamp. La dimensione di ogni campo dovrebbe essere minima per risparmiare spazio entro il limite di 4 KB. Apple raccomanda di includere nel payload solo i dati necessari per visualizzare la schermata di chiamata in arrivo sulla schermata di blocco e di caricare il resto delle informazioni (avatar, cronologia messaggi) dopo che l’utente ha risposto tramite una richiesta di rete separata. Esempio di payload minimo: { "caller": "Anna", "caller_id": "+79161234567", "type": "audio", "room": "uuid-room-1234", "ts": 1718534400 }. Tutte le chiavi nel payload devono essere brevi, univoche e documentate lato server per la compatibilità tra le versioni dell’app.

Gestione degli errori e nuovi tentativi

Quando si lavora con PushKit, è necessario gestire errori di consegna e perdita di connessione. Se il dispositivo è offline o disconnesso dalla rete, la notifica VoIP non verrà consegnata — PushKit non supporta l’archiviazione e l’invio, a differenza di APNs che memorizza le notifiche fino a 24 ore per un nuovo tentativo. Il server deve tracciare autonomamente le notifiche non consegnate e riprovare quando la connessione viene ripristinata. Il meccanismo push kit feedback service viene utilizzato a questo scopo — restituisce un elenco di notifiche non consegnate con il motivo dell’errore. Si consiglia di configurare il monitoraggio del successo di consegna delle notifiche VoIP tramite analisi del server e di notificare lo sviluppatore se il tasso di consegna riuscita scende al di sotto del 95%. Il sistema PushKit garantisce la consegna solo quando il dispositivo ha una connessione Internet attiva — in sua assenza, la notifica viene persa permanentemente, cosa fondamentale da considerare quando si progetta un sistema affidabile di chiamate VoIP con consegna garantita.