Notification Content Extension — cos'è e come creare un'interfaccia personalizzata per iOS

Cos'è Notification Content Extension

Notification Content Extension è un'estensione dell'app in iOS che sostituisce il modello standard di visualizzazione delle notifiche push con una UIView personalizzata. A differenza di una notifica normale, dove il contenuto è limitato a titolo, sottotitolo e corpo, l'estensione consente di visualizzare qualsiasi interfaccia UIKit: una mappa con coordinate, un grafico, una galleria di immagini o un modulo di input.

Come funziona

Quando iOS riceve una notifica push con un categoryIdentifier specificato, il sistema verifica se è registrata un'estensione per questa categoria. Se sì — il sistema avvia l'estensione in un processo separato e le trasmette il contenuto della notifica. L'estensione mostra la propria interfaccia invece di quella standard. L'utente interagisce con l'interfaccia personalizzata senza aprire l'applicazione principale.

Differenza da Notification Service Extension

È importante non confondere Notification Content Extension con Notification Service Extension. La Service Extension elabora il contenuto prima della visualizzazione della notifica (download degli allegati, decifratura). La Content Extension sostituisce l'interfaccia dopo aver ricevuto il contenuto pronto. Entrambe le estensioni possono lavorare insieme: la Service Extension prepara i dati, la Content Extension li visualizza.

Limitazioni dell'estensione

Notification Content Extension opera in un processo isolato con risorse limitate. L'estensione non ha accesso all'archivio principale dell'applicazione tramite NSUserDefaults, tranne tramite App Group. La dimensione dell'estensione è limitata a 50 MB decompressa. Anche il tempo per la visualizzazione del contenuto è limitato — se l'estensione non completa l'aggiornamento in un tempo ragionevole, il sistema la termina.

Creare Notification Content Extension in Xcode

Per creare l'estensione in Xcode, è necessario aggiungere un nuovo target di tipo Notification Content Extension. Xcode crea automaticamente MainInterface.storyboard con un controller che eredita da UIViewController e implementa UNNotificationContentExtension.

Aggiunta del target estensione

In Xcode, seleziona File → New → Target → Notification Content Extension. Specifica il nome dell'estensione, il linguaggio (Swift o Objective-C) e assicurati che il progetto sia connesso allo stesso team di sviluppo. Dopo la creazione del target, appare una cartella con tre file: MainInterface.storyboard, Info.plist e il file del controller.

Configurazione di Info.plist

Nel Info.plist dell'estensione, è obbligatorio specificare l'array NSExtensionAttributes con la chiave UNNotificationExtensionCategory. Questo array contiene gli identificatori delle categorie di notifica per cui l'estensione verrà attivata. La chiave opzionale UNNotificationExtensionInitialContentSizeRatio definisce il rapporto d'aspetto iniziale dell'interfaccia personalizzata per un corretto posizionamento.

Architettura delle cartelle dell'estensione

Si raccomanda di mantenere un'architettura pulita nel target dell'estensione: una cartella separata per i controller, una separata per le viste personalizzate. Poiché l'estensione è un binario separato, il codice dell'applicazione principale non è direttamente accessibile. Per la condivisione del codice, crea un framework separato o utilizza App Group per i dati.

Implementare il protocollo UNNotificationContentExtension

UNNotificationContentExtension è il protocollo che il controller in Notification Content Extension deve implementare. L'unico metodo obbligatorio è didReceive(_:with:), chiamato alla ricezione di una notifica. Il controller riceve la notifica e il view controller pronto che deve essere aggiornato con i dati.

Implementazione base del controller

Il controller dell'estensione deve ereditare da UIViewController e implementare UNNotificationContentExtension. Lo Storyboard o xib è collegato a questo controller. Alla ricezione di una notifica, il metodo didReceive trasmette il contenuto e il controller aggiorna le sue viste.

import UIKit
import UserNotifications
import UserNotificationsUI

class CustomNotificationViewController: UIViewController {

    @IBOutlet var titleLabel: UILabel!
    @IBOutlet var customImageView: UIImageView!

    func didReceive(
        notification: UNNotification
    ) {
        let content = notification.request.content
        titleLabel.text = content.title
        loadAttachment(content.attachments.first)
    }

    private func loadAttachment(attachment: UNNotificationAttachment?) {
        guard let url = attachment?.URL else { return }
        if let image = UIImage(contentsOfFile: url.path) {
            customImageView.image = image
        }
    }
}

extension CustomNotificationViewController: UNNotificationContentExtension {
    func didReceive(
        notification: UNNotification
    ) {
        didReceive(notification: notification)
    }
}

Controllo della dimensione dell'interfaccia

Il sistema determina la dimensione dell'interfaccia personalizzata in base alla chiave UNNotificationExtensionInitialContentSizeRatio in Info.plist e al contenuto corrente. Si consiglia di impostare questa chiave a 0.1 per una dimensione iniziale minima, quindi modificare la dimensione tramite preferredContentSize dopo il caricamento del contenuto.

Personalizzazione dell'interfaccia e interattività

Notification Content Extension offre completa libertà nella creazione dell'interfaccia. È possibile utilizzare qualsiasi componente UIKit: UITableView, MKMapView, WKWebView, UIStackView. Tuttavia, è importante considerare lo spazio limitato della notifica e ottimizzare le prestazioni.

Aggiungere una mappa alla notifica

Uno degli scenari popolari è visualizzare una mappa con posizione. Per farlo, si aggiunge MKMapView allo Storyboard dell'estensione e il controller passa le coordinate dal contenuto della notifica. Non dimenticare di aggiungere MapKit al target dell'estensione. Quando si usa la mappa, considera il limite di memoria dell'estensione — il caricamento di tile complessi potrebbe superare le risorse disponibili.

Animazioni e transizioni

Notification Content Extension supporta le animazioni UIView, inclusi ridimensionamento, spostamento e trasparenza degli elementi. All'ingresso nella modalità estesa della notifica, si può avviare un'animazione di apparizione del contenuto. Le animazioni devono essere brevi (fino a 0,5 secondi) e non interferire con l'interazione dell'utente con la notifica. Evita animazioni infinite — consumano batteria e riducono le prestazioni.

Gestione dei tocchi sull'interfaccia personalizzata

Poiché l'estensione è un UIViewController completo, puoi aggiungere gesture e gestori di tocchi. I gesture UIKit (UITapGestureRecognizer, UIButton) funzionano in modo standard. Per azioni che richiedono l'apertura dell'applicazione, usa il delegato dell'estensione o userNotificationCenter. Gli elementi interattivi devono essere abbastanza grandi per un tocco comodo nello spazio limitato — la dimensione minima del target di tocco è di 44x44 punti secondo le raccomandazioni Apple.

Lavorare con media e allegati

Il contenuto multimediale è la funzionalità chiave di Notification Content Extension. La notifica può contenere immagini, GIF, audio e video che vengono visualizzati nell'interfaccia personalizzata. Gli allegati vengono consegnati tramite UNNotificationAttachment, che può essere aggiunto dal server tramite il payload o da Notification Service Extension dopo il download. I formati supportati sono JPEG, PNG, MPEG-4 e MP3.

Visualizzare i media nell'estensione

Per visualizzare un'immagine, basta ottenere UNNotificationAttachment dal contenuto della notifica e caricarlo dall'URL locale. È importante ricordare che l'estensione ha accesso solo ai file locali — le risorse remote devono essere scaricate preventivamente da Service Extension. Dimensione massima dell'allegato — 50 MB su iOS 15+, il limite cambia con ogni aggiornamento successivo. Per supportare più immagini, usa UNNotificationAttachment con identificatori diversi e visualizzali tramite UIPageViewController.

Caricamento e visualizzazione delle immagini

Per visualizzare un'immagine nell'interfaccia personalizzata, l'estensione ottiene UNNotificationAttachment dal contenuto della notifica e lo carica dall'URL locale. L'allegato deve essere stato scaricato preventivamente da Notification Service Extension — Content Extension non ha accesso alla rete. Dimensione massima dell'allegato multimediale — 50 MB su iOS 15+, nelle versioni precedenti il limite era di 10 MB. L'estensione deve gestire correttamente l'assenza dell'allegato e visualizzare un'interfaccia di fallback. Per precaricare immagini a bassa risoluzione, usa versioni thumbnail create da Service Extension prima dell'allegato.

Riproduzione video nella notifica

iOS supporta la riproduzione video in Notification Content Extension tramite AVPlayerLayer. L'estensione può visualizzare un lettore video con pulsanti di controllo direttamente nella notifica. Questo è particolarmente utile per applicazioni di sorveglianza, streaming o anteprime di contenuti. La riproduzione automatica senza audio è consentita se l'utente si aspetta contenuti multimediali in questa notifica. Nell'implementare il lettore video, aggiungi elementi di controllo: play/pausa, barra di avanzamento e pulsante di chiusura. Assicurati che il video non parta automaticamente con l'audio — viola le raccomandazioni Apple sull'esperienza utente. Per uno slideshow di più immagini, usa una transizione animata tra di esse tramite UIView.transition con l'opzione di transizione di giramento pagina.

Ottimizzazione delle prestazioni dell'estensione

Notification Content Extension opera in un ambiente limitato con un limite di memoria di circa 50 MB. Per ottimizzare le prestazioni, usa il caricamento lazy delle immagini, evita calcoli pesanti sul thread principale e applica Auto Layout con constraint semplici. Le operazioni pesanti come l'elaborazione di immagini o l'analisi dei dati, eseguile in code di background (DispatchQueue.global). Se il limite di memoria viene superato, il sistema terminerà l'estensione e l'utente vedrà la notifica standard. Si consiglia di profilare l'estensione tramite Instruments (Allocations e Time Profiler) prima della pubblicazione, oltre a verificare il consumo di memoria su dispositivi reali con diverse versioni di iOS.