Notification Content Extension — esența, UI personalizat și configurarea în iOS

Ce este Notification Content Extension

Notification Content Extension — este o extensie de aplicație care suprascrie afișarea notificării push pe iOS. În locul unui banner standard cu titlu, corp de mesaj și butoane, se poate afișa o interfață complet proiectată în Interface Builder sau programatic prin UIKit ori SwiftUI.

Spre deosebire de Notification Service Extension, care modifică conținutul înainte de afișare, Content Extension răspunde doar de prezentarea vizuală. Extensia primește notificarea gata după toate modificările și decide cum să o afișeze. Aceasta este diferența cheie între cele două tipuri de extensii de notificări.

Extensia se activează când utilizatorul execută un gest de extindere — derulează notificarea în jos sau face clic pe ea (în funcție de modelul dispozitivului). iOS pornește procesul extensiei, creează controlerul din nib-ul sau storyboard-ul specificat și transmite notificarea prin UNNotificationContentExtension.

Crearea unei interfețe personalizate de notificare

Dezvoltarea începe cu adăugarea unui nou target în Xcode cu șablonul Notification Content Extension. Xcode creează fișierul MainInterface.storyboard și o clasă care moștenește UIViewController, implementând protocolul UNNotificationContentExtension.

Dimensiunea și limitările interfeței

Înălțimea maximă a zonei personalizate — 320 de puncte pe iPhone (pentru modelele cu ecran mare) și 352 de puncte pe iPad. Conținutul care depășește aceste limite este tăiat. Pentru adaptarea la diferite dimensiuni, se recomandă utilizarea Auto Layout și UIScrollView pentru conținut derulabil. Lățimea este întotdeauna egală cu lățimea notificării și se modifică automat la rotirea dispozitivului.

Apple Human Interface Guidelines avertizează: interfața notificării trebuie să fie concisă și să conțină un singur element principal — imagine, player, hartă sau formular de introducere rapidă. Elementele interactive multiple supraîncarcă utilizatorul și complică interacțiunea.

Comunicarea cu aplicația principală

App Group — este singurul mecanism de schimb de date între extensie și aplicația principală. Prin directorul comun App Group se pot transmite imagini cache, tokeni și setări. Apelurile directe API ale aplicației principale sau accesul la UserDefaults-ul acesteia nu sunt disponibile din cauza izolării proceselor.

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

Protocolul UNNotificationContentExtension

UNNotificationContentExtension — protocolul principal care definește ciclul de viață al notificării personalizate. Protocolul oferă metode pentru primirea conținutului, procesarea acțiunilor și gestionarea interfeței.

Metoda didReceive:with:

didReceive(_:with:) este apelată la primirea notificării. Extensia primește un obiect UNNotification și UNNotificationContentExtensionMediaPlayPauseButtonType pentru gestionarea playerului media. În această metodă trebuie configurată interfața — încărcată imaginea, inițializat playerul sau afișate datele. Sistemul apelează această metodă de fiecare dată când notificarea este actualizată în timp real.

Este important de reținut că extensia are timp limitat pentru execuție — aproximativ 30 de secunde pentru un ciclu complet de afișare. Dacă interfața nu este pregătită în acest timp, iOS va afișa o notificare de sistem. Pentru resurse grele — încărcarea imaginilor din rețea, decodarea video — se recomandă utilizarea operațiilor asincrone cu cache prealabil prin App Group.

Gestionarea playerului media

Protocolul include metode opționale pentru butoanele play/pause: mediaPlay, mediaPause și mediaPlayPauseButtonType. Dacă notificarea conține conținut audio sau video, extensia poate afișa un player încorporat cu element de control de sistem. iOS adaugă automat un buton de redare în colțul din dreapta sus al extensiei la returnarea tipului de buton corespunzător.

Atașamentele media și procesarea lor

UNNotificationAttachment — obiectul care conține datele media atașate notificării. Imaginile, fișierele audio și video sunt adăugate în etapa de creare a notificării pe server sau în Notification Service Extension prin UNNotificationAttachment.

Formate suportate

Pentru imagini: JPEG, PNG, GIF, HEIF. Pentru audio: MP3, AAC, ALAC, WAV. Pentru video: MPEG-4, H.264, HEVC. Dimensiunea maximă a fiecărui atașament — 50 MB, până la 4 atașamente per notificare. Sistemul descarcă automat atașamentele în fundal înainte de afișarea notificării și oferă extensiei acces la URL-uri locale prin resurse security-scoped.

Conform Apple, extensia nu ar trebui să încarce media independent — UNNotificationAttachment conține deja un URL local după finalizarea descărcării de către sistem. Totuși, dacă atașamentul nu a fost descărcat la timp (de exemplu, la conexiune slabă), extensia poate afișa un placeholder sau text alternativ.

Lucrul cu resursele security-scoped

Fiecare UNNotificationAttachment oferă un security-scoped URL, la care extensia trebuie să acceseze prin startAccessingSecurityScopedResource() și să îl elibereze prin stopAccessingSecurityScopedResource(). Aceste metode trebuie apelate în perechi — altfel resursa nu va fi eliberată și va cauza scurgerea permisiunilor de acces.

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)

Notificări interactive și acțiuni

Notification Content Extension suportă acțiuni interactive personalizate — butoane care sunt afișate sub conținutul notificării. Acțiunile sunt înregistrate la crearea categoriei de notificare prin UNNotificationCategory și pot fi distructive, text sau de fundal.

Tipuri de acțiuni

UNNotificationAction — o acțiune simplă cu titlu și un flag opțional de distructivitate. UNTextInputNotificationAction — o acțiune cu câmp de introducere text, de exemplu pentru răspuns rapid la un mesaj. Ambele tipuri suportă opțiunea UNNotificationActionOptions.authenticationRequired — cerința de deblocare a dispozitivului înainte de execuție.

Extensia primește acțiunea selectată prin metoda didReceive(_:withCompletionHandler:), unde este transmis un obiect UNNotificationResponse cu identificatorul acțiunii și textul opțional. Extensia poate procesa răspunsul independent sau îl poate transmite aplicației principale prin containerul comun 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: []
)