Notification Content Extension — essenza, UI personalizzata e configurazione in iOS

Cos'e Notification Content Extension

Notification Content Extension è un'estensione dell'app che sovrascrive la visualizzazione delle notifiche push su iOS. Invece di un banner standard con titolo, corpo del messaggio e pulsanti, puoi mostrare un'interfaccia completamente progettata in Interface Builder o programmaticamente tramite UIKit o SwiftUI.

A differenza di Notification Service Extension, che modifica il contenuto prima della visualizzazione, Content Extension è responsabile solo della presentazione visiva. . L'estensione riceve la notifica completa dopo tutte le modifiche e decide come visualizzarla. Questa è la differenza chiave tra i due tipi di estensioni di notifica.

L'estensione viene attivata quando l'utente esegue un gesto di espansione — scorrendo verso il basso la notifica o toccandola (a seconda del modello di dispositivo). iOS avvia il processo dell'estensione, crea un controller dal nib o storyboard specificato e consegna la notifica tramite UNNotificationContentExtension .

Creazione di un'interfaccia di notifica personalizzata

Lo sviluppo inizia aggiungendo un nuovo target in Xcode con il template Notification Content Extension. Xcode crea un file MainInterface.storyboard e una classe che eredita da UIViewController che implementa il protocollo UNNotificationContentExtension.

Dimensioni e limiti dell'interfaccia

L'altezza massima dell'area personalizzata è di 320 punti su iPhone (per modelli con schermo grande) e 352 punti su iPad. Il contenuto che supera questi limiti viene tagliato. Per adattarsi a diverse dimensioni, si consiglia di utilizzare Auto Layout e UIScrollView per contenuto scorrevole. La larghezza corrisponde sempre alla larghezza della notifica e cambia automaticamente quando il dispositivo viene ruotato.

Le linee guida dell'interfaccia umana di Apple avvertono: l'interfaccia di notifica deve essere concisa e contenere un solo elemento principale — un'immagine, un lettore, una mappa o un modulo di input rapido. Molteplici elementi interattivi sopraffanno l'utente e complicano l'interazione.

Comunicazione con l'app principale

App Group è l'unico meccanismo per condividere dati tra l'estensione e l'applicazione principale. Attraverso la directory condivisa di App Group, è possibile trasferire immagini memorizzate nella cache, token e impostazioni. Le chiamate API dirette all'applicazione principale o l'accesso ai suoi UserDefaults non sono disponibili a causa dell'isolamento dei processi.

class NotificationViewController: UIViewController {

    func didReceive(
        _ notification: UNNotification
    ) {
        guard let attachment = notification
            .request.content.attachments.first()
        else { return }
        if attachment.url.startAccessingSecurityScopedResource() {
            imageView.image = UIImage(contentsOfFile:
                attachment.url.path)
            attachment.url.stopAccessingSecurityScopedResource()
        }
    }
}

Protocollo UNNotificationContentExtension

UNNotificationContentExtension è il protocollo principale che definisce il ciclo di vita di una notifica personalizzata. Il protocollo fornisce metodi per ricevere contenuto, gestire azioni e amministrare l'interfaccia.

Metodo didReceive:with:

didReceive(_:with:) viene chiamato quando viene ricevuta una notifica. L'estensione riceve un oggetto UNNotification e UNNotificationContentExtensionMediaPlayPauseButtonType per gestire il lettore multimediale. In questo metodo, devi configurare l'interfaccia — caricare un'immagine, inizializzare il lettore o visualizzare dati. Il sistema chiama questo metodo ogni volta che la notifica viene aggiornata in tempo reale.

È importante notare che l'estensione ha tempo limitato per eseguire — circa 30 secondi per un ciclo di visualizzazione completo. Se l'interfaccia non viene preparata entro questo tempo, iOS mostrerà la notifica di sistema. Per risorse pesanti — caricamento di immagini dalla rete, decodifica video — si consiglia di utilizzare operazioni asincrone con pre-caching tramite App Group.

Controllo del lettore multimediale

Il protocollo include metodi opzionali per i pulsanti play/pause: mediaPlay, mediaPause, mediaPlayPauseButtonType. Se la notifica contiene contenuto audio o video, l'estensione può mostrare un lettore integrato con un elemento di controllo del sistema. iOS aggiunge automaticamente un pulsante di riproduzione nell'angolo superiore destro dell'estensione quando viene restituito il tipo di pulsante appropriato.

Allegati multimediali e loro elaborazione

UNNotificationAttachment è un oggetto che contiene dati multimediali allegati a una notifica. Immagini, file audio e video vengono aggiunti nella fase di creazione della notifica sul server o in Notification Service Extension tramite UNNotificationAttachment.

Formati supportati

Per immagini: JPEG, PNG, GIF, HEIF. Per audio: MP3, AAC, ALAC, WAV. Per video: MPEG-4, H.264, HEVC. Dimensione massima di ogni allegato: 50 MB, fino a 4 allegati per notifica. Il sistema scarica automaticamente gli allegati in background prima di visualizzare la notifica e fornisce all'estensione l'accesso agli URL locali tramite risorse con ambito di sicurezza.

Secondo Apple, l'estensione non dovrebbe scaricare i media da sola — UNNotificationAttachment contiene già un URL locale dopo che il sistema ha completato il download. Tuttavia, se l'allegato non è stato scaricato in tempo (ad esempio, a causa di una connessione scarsa), l'estensione può mostrare un segnaposto o un testo alternativo.

Lavorare con le risorse con ambito di sicurezza

Ogni UNNotificationAttachment fornisce un URL con ambito di sicurezza a cui l'estensione deve accedere tramite startAccessingSecurityScopedResource() e rilasciare tramite stopAccessingSecurityScopedResource(). Questi metodi devono essere chiamati in coppia — altrimenti la risorsa non verrà rilasciata e causerà una perdita di diritti di accesso.

let attachment = notification.request.content.attachments.first()
guard attachment.url.startAccessingSecurityScopedResource()
else { return }
defer { attachment.url.stopAccessingSecurityScopedResource() }
let data = try Data(contentsOf: attachment.url)
imageView.image = UIImage(data: data)

Notifiche interattive e azioni

Notification Content Extension supporta azioni interattive personalizzate — pulsanti visualizzati sotto il contenuto della notifica. Le azioni vengono registrate durante la creazione della categoria di notifica tramite UNNotificationCategory e possono essere distruttive, testuali o in background.

Tipi di azioni

UNNotificationAction è un'azione semplice con un titolo e un flag opzionale di distruttività. UNTextInputNotificationAction è un'azione con un campo di input di testo, ad esempio per risposte rapide ai messaggi. Entrambi i tipi supportano l'opzione UNNotificationActionOptions.authenticationRequired — che richiede lo sblocco del dispositivo prima dell'esecuzione.

L'estensione riceve l'azione selezionata tramite il metodo didReceive(_:withCompletionHandler:), che passa un oggetto UNNotificationResponse con l'identificatore dell'azione e testo opzionale. L'estensione può elaborare la risposta da sola o passarla all'applicazione principale tramite il contenitore condiviso di App Group.

let category = UNNotificationCategory(
    identifier: "message",
    actions: [
        UNTextInputNotificationAction(
            identifier: "reply",
            title: "Reply",
            options: .authenticationRequired
        ),
        UNNotificationAction(
            identifier: "mark_read",
            title: "Mark Read",
            options: .foreground
        )
    ],
    intentIdentifiers: []
)