Notification Service Extension — come funziona l'elaborazione delle notifiche push

Cos'è Notification Service Extension

Notification Service Extension è un'estensione dell'app in iOS che intercetta una notifica push in arrivo sul dispositivo e consente di modificarne il contenuto prima che l'utente la veda. Questo è l'unico tipo di estensione di notifica che lavora con il contenuto e non con la visualizzazione.

La differenza principale rispetto a Notification Content Extension: Service Extension funziona prima della visualizzazione della notifica e può modificare titolo, corpo, file audio e allegati. Content Extension funziona dopo la visualizzazione e gestisce solo la presentazione visiva della notifica pronta. Queste due estensioni possono lavorare insieme: Service Extension scarica un'immagine e Content Extension la visualizza in un'interfaccia personalizzata.

L'estensione si attiva automaticamente alla ricezione di una notifica push con l'attributo mutable-content:1 nel dizionario aps. iOS avvia l'estensione in background, le passa la UNNotificationRequest originale e attende una versione modificata da visualizzare.

Elaborazione delle notifiche push al volo

UNNotificationServiceExtension riceve la UNNotificationRequest completa con il contenuto originale. L'estensione può modificare qualsiasi campo di UNNotificationContent: title, subtitle, body, userInfo, attachments e sound. Le modifiche vengono applicate prima che la notifica venga visualizzata.

Scenari d'uso tipici

Decifratura del contenuto — se una notifica push contiene un payload crittografato, l'estensione lo decifra prima della visualizzazione. Download di media — allegare un'immagine o un video alla notifica. Localizzazione — adattare il testo della notifica alle impostazioni regionali del dispositivo. Arricchimento dei dati — aggiungere informazioni aggiuntive dalla memoria locale o dalla cache.

Secondo Apple, lo scenario più comune tra le applicazioni è il download di immagini per notifiche multimediali ricche. Il server invia un URL dell'immagine nel payload, l'estensione la scarica in una directory temporanea e crea un UNNotificationAttachment, che il sistema visualizza in un'interfaccia standard o personalizzata.

Modifica del testo e del titolo

L'estensione può riscrivere completamente il testo della notifica, sostituire il titolo o aggiungere un sottotitolo. Ad esempio, un'app di messaggistica può ricevere una notifica crittografata, decifrarla nell'estensione e visualizzare testo leggibile. Oppure un'app di notizie può aggiungere una categoria di notizia al sottotitolo prima della visualizzazione.

override func didReceive(
    _ request: UNNotificationRequest,
    withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
) {
    let content = request.content.mutableCopy()
        as! UNMutableNotificationContent
    if let imageURL = content.userInfo["media-url"]
        as? String {
        downloadAndAttach(imageURL: imageURL,
            content: content,
            handler: contentHandler)
    }
}

Protocollo UNNotificationServiceExtension

UNNotificationServiceExtension è la classe base da cui Service Extension eredita. La classe definisce due metodi del ciclo di vita: didReceive(_:withContentHandler:) — il metodo di elaborazione principale, e serviceExtensionTimeWillExpire() — il gestore del timeout.

Metodo didReceive:withContentHandler:

didReceive(_:withContentHandler:) viene chiamato quando viene ricevuta una notifica. L'estensione riceve una UNNotificationRequest e una chiusura contentHandler, che deve essere chiamata con il UNMutableNotificationContent modificato. L'estensione è obbligata a chiamare contentHandler — se non lo fa, iOS mostrerà la notifica originale dopo la scadenza del timeout.

Importante: l'estensione può elaborare solo una notifica alla volta. Se arrivano più notifiche contemporaneamente, iOS crea istanze separate dell'estensione per ciascuna. Non è possibile utilizzare lo stato globale per l'elaborazione sequenziale.

Metodo serviceExtensionTimeWillExpire:

serviceExtensionTimeWillExpire() viene chiamato dal sistema quando il tempo di esecuzione rimanente sta per scadere. In questo metodo, è necessario chiamare immediatamente contentHandler con qualsiasi contenuto pronto in quel momento — anche se il file multimediale non ha terminato il download. Se non si chiama contentHandler in questo metodo, iOS mostrerà la notifica originale.

Si consiglia di salvare un contenuto minimamente accettabile in questo metodo — ad esempio, una notifica con testo e titolo ma senza un'immagine il cui download non è stato completato in tempo.

Crittografia e allegati multimediali

UNNotificationAttachment è un oggetto creato dall'estensione per allegare un file multimediale alla notifica. L'estensione scarica il file dalla rete, lo salva in una directory temporanea e crea un UNNotificationAttachment specificando il tipo di contenuto.

Creazione di un allegato da un file scaricato

UNNotificationAttachment viene creato utilizzando l'inizializzatore init(identifier:url:options:). L'URL deve puntare a un file locale nella directory temporanea accessibile all'estensione. Dopo la creazione, l'allegato viene aggiunto all'array attachments di UNMutableNotificationContent.

Apple consiglia di utilizzare URLSession con configurazione in background per il download — utilizzando URLSession standard, il download blocca il thread e consuma tempo dal limite di 30 secondi. URLSession in background continua il download anche quando l'estensione termina e il risultato può essere utilizzato all'avvio successivo.

Decifratura di un payload crittografato

Se il server invia una notifica crittografata, l'estensione deve decifrare il payload prima di chiamare contentHandler. La decifratura di solito comporta la richiesta di una chiave da Keychain o App Group, la decifratura tramite CommonCrypto e la sostituzione del body o userInfo della notifica. In caso di errore di decifratura, è necessario chiamare contentHandler con il contenuto originale — in modo che l'utente veda almeno che una notifica è arrivata, anche se illeggibile.

func downloadAndAttach(
    imageURL: String,
    content: UNMutableNotificationContent,
    handler: @escaping (UNNotificationContent) -> Void
) {
    let task = URLSession.shared.dataTask(with:
        URL(string: imageURL)!) { data, _, _ in
        let url = FileManager.default
            .temporaryDirectory
            .appendingPathComponent("image.jpg")
        try? data?.write(to: url)
        let attachment = try? UNNotificationAttachment(
            identifier: "image", url: url)
        content.attachments = [attachment].compactMap { $0 }
        handler(content)
    }
    task.resume()
}

Timeout e meccanismi di fallback

Notification Service Extension opera entro tempi rigorosi. iOS alloca un tempo di esecuzione fisso — circa 30 secondi dall'attivazione. Se l'estensione non ha chiamato contentHandler entro questo tempo, il sistema termina forzatamente il processo e mostra la notifica originale invariata.

Strategia di degradazione graduale

Si consiglia di implementare un fallback multilivello: prima provare a scaricare il supporto, in caso di successo chiamare contentHandler con il contenuto completo; in caso di fallimento chiamare contentHandler con il testo ma senza supporto; in caso di errore critico passare il contenuto originale. Questo approccio garantisce che l'utente veda sempre una notifica e non una schermata vuota.

Secondo Apple, la causa più comune di timeout è il download di file multimediali di grandi dimensioni su connessione lenta. Per ridurre il rischio, si consiglia di ottimizzare la dimensione delle immagini sul server — inviare anteprime fino a 300 KB invece della risoluzione completa. Le immagini a dimensione intera dovrebbero essere scaricate all'apertura dell'app.

Monitoraggio delle prestazioni

Per tracciare timeout ed errori dell'estensione, è possibile utilizzare os_log per registrare messaggi diagnostici nel Unified Logging System. Sebbene la registrazione diretta su file nell'estensione sia difficile, os_log consente l'analisi delle prestazioni tramite Console.app sul dispositivo dello sviluppatore. Apple consiglia di aggiungere metriche a ogni chiamata didReceive — tempo di download, dimensione del file, risultato dell'operazione.

override func serviceExtensionTimeWillExpire() {
    let fallback = bestEffortContent as?
        UNMutableNotificationContent
        ?? request.content.mutableCopy()
        as! UNMutableNotificationContent
    contentHandler(fallback)
}