Notification Content Extension — podstata, vlastní UI a nastavení v iOS

Co je Notification Content Extension

Notification Content Extension — je rozšíření aplikace, které přepisuje zobrazení push oznámení na iOS. Místo standardního banneru s názvem, tělem zprávy a tlačítky lze zobrazit rozhraní zcela navržené v Interface Builder nebo programově přes UIKit či SwiftUI.

Na rozdíl od Notification Service Extension, které mění obsah před zobrazením, je Content Extension zodpovědné pouze za vizuální prezentaci. Rozšíření obdrží hotové oznámení po všech úpravách a rozhodne, jak jej zobrazit. To je klíčový rozdíl mezi těmito dvěma typy rozšíření oznámení.

Rozšíření se aktivuje, když uživatel provede gesto rozšíření — posune oznámení dolů nebo na něj klikne (v závislosti na modelu zařízení). iOS spustí proces rozšíření, vytvoří řadič z určeného nib nebo storyboard a předá oznámení prostřednictvím UNNotificationContentExtension.

Vytvoření vlastního rozhraní oznámení

Vývoj začíná přidáním nového targetu v Xcode se šablonou Notification Content Extension. Xcode vytvoří soubor MainInterface.storyboard a třídu dědící z UIViewController, implementující protokol UNNotificationContentExtension.

Velikost a omezení rozhraní

Maximální výška vlastní oblasti — 320 bodů na iPhone (pro modely s velkým displejem) a 352 bodů na iPadu. Obsah přesahující tyto hranice je oříznut. Pro přizpůsobení různým velikostem se doporučuje použít Auto Layout a UIScrollView pro posouvatelný obsah. Šířka je vždy rovna šířce oznámení a mění se automaticky při otočení zařízení.

Apple Human Interface Guidelines varuje: rozhraní oznámení by mělo být stručné a obsahovat pouze jeden hlavní prvek — obrázek, přehrávač, mapu nebo formulář rychlého vstupu. Více interaktivních prvků uživatele přetěžuje a komplikuje interakci.

Komunikace s hlavní aplikací

App Group — jediný mechanismus výměny dat mezi rozšířením a hlavní aplikací. Prostřednictvím sdíleného adresáře App Group lze přenášet kešované obrázky, tokeny a nastavení. Přímá volání API hlavní aplikace nebo přístup k jejímu UserDefaults nejsou kvůli izolaci procesů dostupné.

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

Protokol UNNotificationContentExtension

UNNotificationContentExtension — hlavní protokol, který definuje životní cyklus vlastního oznámení. Protokol poskytuje metody pro příjem obsahu, zpracování akcí a správu rozhraní.

Metoda didReceive:with:

didReceive(_:with:) je volána při přijetí oznámení. Rozšíření obdrží objekt UNNotification a UNNotificationContentExtensionMediaPlayPauseButtonType pro správu multimediálního přehrávače. V této metodě je třeba nakonfigurovat rozhraní — načíst obrázek, inicializovat přehrávač nebo zobrazit data. Systém volá tuto metodu pokaždé, když je oznámení aktualizováno v reálném čase.

Je důležité vzít v úvahu, že rozšíření má omezený čas na provedení — přibližně 30 sekund na celý cyklus zobrazení. Pokud rozhraní není v tomto čase připraveno, iOS zobrazí systémové oznámení. Pro náročné zdroje — načítání obrázků ze sítě, dekódování videa — se doporučuje používat asynchronní operace s předchozím kešováním prostřednictvím App Group.

Správa multimediálního přehrávače

Protokol obsahuje volitelné metody pro tlačítka play/pause: mediaPlay, mediaPause a mediaPlayPauseButtonType. Pokud oznámení obsahuje audio nebo video obsah, rozšíření může zobrazit vestavěný přehrávač s ovládacím prvkem systému. iOS automaticky přidá tlačítko přehrávání do pravého horního rohu rozšíření při vrácení odpovídajícího typu tlačítka.

Multimediální přílohy a jejich zpracování

UNNotificationAttachment — objekt, který obsahuje multimediální data připojená k oznámení. Obrázky, audio soubory a video se přidávají ve fázi vytváření oznámení na serveru nebo v Notification Service Extension prostřednictvím UNNotificationAttachment.

Podporované formáty

Pro obrázky: JPEG, PNG, GIF, HEIF. Pro audio: MP3, AAC, ALAC, WAV. Pro video: MPEG-4, H.264, HEVC. Maximální velikost každé přílohy — 50 MB, až 4 přílohy na oznámení. Systém automaticky stahuje přílohy na pozadí před zobrazením oznámení a poskytuje rozšíření přístup k místním URL prostřednictvím security-scoped zdrojů.

Podle Apple by rozšíření nemělo načítat média samostatně — UNNotificationAttachment již obsahuje místní URL po dokončení stahování systémem. Pokud však příloha nebyla stažena včas (např. při špatném připojení), rozšíření může zobrazit placeholder nebo alternativní text.

Práce se security-scoped zdroji

Každý UNNotificationAttachment poskytuje security-scoped URL, ke kterému musí rozšíření získat přístup přes startAccessingSecurityScopedResource() a uvolnit ho přes stopAccessingSecurityScopedResource(). Tyto metody musí být volány v párech — jinak zdroj nebude uvolněn a způsobí únik přístupových práv.

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)

Interaktivní oznámení a akce

Notification Content Extension podporuje vlastní interaktivní akce — tlačítka, která se zobrazují pod obsahem oznámení. Akce se registrují při vytváření kategorie oznámení prostřednictvím UNNotificationCategory a mohou být destruktivní, textové nebo na pozadí.

Typy akcí

UNNotificationAction — jednoduchá akce s názvem a volitelným příznakem destruktivnosti. UNTextInputNotificationAction — akce s polem pro zadání textu, například pro rychlou odpověď na zprávu. Oba typy podporují volbu UNNotificationActionOptions.authenticationRequired — požadavek na odemknutí zařízení před provedením.

Rozšíření obdrží vybranou akci prostřednictvím metody didReceive(_:withCompletionHandler:), kde je předán objekt UNNotificationResponse s identifikátorem akce a volitelným textem. Rozšíření může zpracovat odpověď samostatně nebo ji předat hlavní aplikaci prostřednictvím sdíleného kontejneru 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: []
)