Notification Content Extension — istota, niestandardowy UI i konfiguracja w iOS

Co to jest Notification Content Extension

Notification Content Extension — to app extension, które nadpisuje wyświetlanie powiadomienia push na iOS. Zamiast standardowego baneru z tytułem, treścią wiadomości i przyciskami można pokazać interfejs w pełni zaprojektowany w Interface Builder lub programowo przez UIKit lub SwiftUI.

W przeciwieństwie do Notification Service Extension, które modyfikuje treść przed wyświetleniem, Content Extension odpowiada tylko za prezentację wizualną. Rozszerzenie otrzymuje gotowe powiadomienie po wszystkich modyfikacjach i decyduje, jak je wyświetlić. To kluczowa różnica między tymi dwoma typami rozszerzeń powiadomień.

Rozszerzenie aktywuje się, gdy użytkownik wykona gest rozszerzenia — przewinie powiadomienie w dół lub kliknie na nie (w zależności od modelu urządzenia). iOS uruchamia proces rozszerzenia, tworzy kontroler z określonego nib lub storyboard i przekazuje powiadomienie przez UNNotificationContentExtension.

Tworzenie niestandardowego interfejsu powiadomienia

Tworzenie rozpoczyna się od dodania nowego targetu w Xcode z szablonem Notification Content Extension. Xcode tworzy plik MainInterface.storyboard i klasę dziedziczącą po UIViewController, implementującą protokół UNNotificationContentExtension.

Rozmiar i ograniczenia interfejsu

Maksymalna wysokość niestandardowego obszaru — 320 punktów na iPhonie (dla modeli z dużym ekranem) i 352 punkty na iPadzie. Treść wykraczająca poza te granice jest przycinana. Do adaptacji do różnych rozmiarów zaleca się używanie Auto Layout i UIScrollView dla przewijanego kontentu. Szerokość jest zawsze równa szerokości powiadomienia i zmienia się automatycznie przy obrocie urządzenia.

Apple Human Interface Guidelines ostrzegają: interfejs powiadomienia powinien być zwięzły i zawierać tylko jeden główny element — obraz, odtwarzacz, mapę lub formularz szybkiego wprowadzania. Wielokrotne elementy interaktywne przeciążają użytkownika i utrudniają interakcję.

Komunikacja z główną aplikacją

App Group — to jedyny mechanizm wymiany danych między rozszerzeniem a główną aplikacją. Poprzez wspólny katalog App Group można przekazywać buforowane obrazy, tokeny i ustawienia. Bezpośrednie wywołania API głównej aplikacji lub dostęp do jej UserDefaults są niedostępne ze względu na izolację procesów.

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

Protokół UNNotificationContentExtension

UNNotificationContentExtension — główny protokół, który określa cykl życia niestandardowego powiadomienia. Protokół udostępnia metody do pobierania treści, obsługi akcji i zarządzania interfejsem.

Metoda didReceive:with:

didReceive(_:with:) jest wywoływana przy otrzymaniu powiadomienia. Rozszerzenie otrzymuje obiekt UNNotification i UNNotificationContentExtensionMediaPlayPauseButtonType do zarządzania odtwarzaczem multimedialnym. W tej metodzie należy skonfigurować interfejs — załadować obraz, zainicjować odtwarzacz lub wyświetlić dane. System wywołuje tę metodę za każdym razem przy aktualizacji powiadomienia w czasie rzeczywistym.

Ważne jest, aby uwzględnić, że rozszerzenie ma ograniczony czas na wykonanie — około 30 sekund na pełny cykl wyświetlania. Jeśli interfejs nie zostanie przygotowany w tym czasie, iOS pokaże systemowe powiadomienie. Dla zasobochłonnych operacji — ładowania obrazów z sieci, dekodowania wideo — zaleca się używanie operacji asynchronicznych z wcześniejszym buforowaniem przez App Group.

Zarządzanie odtwarzaczem multimedialnym

Protokół zawiera opcjonalne metody dla przycisków play/pause: mediaPlay, mediaPause i mediaPlayPauseButtonType. Jeśli powiadomienie zawiera treść audio lub wideo, rozszerzenie może pokazać wbudowany odtwarzacz z systemowym elementem sterowania. iOS automatycznie dodaje przycisk odtwarzania w prawym górnym rogu rozszerzenia przy zwróceniu odpowiedniego typu przycisku.

Załączniki multimedialne i ich obsługa

UNNotificationAttachment — obiekt, który zawiera dane multimedialne dołączone do powiadomienia. Obrazy, pliki audio i wideo są dodawane na etapie tworzenia powiadomienia na serwerze lub w Notification Service Extension przez UNNotificationAttachment.

Obsługiwane formaty

Dla obrazów: JPEG, PNG, GIF, HEIF. Dla audio: MP3, AAC, ALAC, WAV. Dla wideo: MPEG-4, H.264, HEVC. Maksymalny rozmiar każdego załącznika — 50 MB, do 4 załączników na jedno powiadomienie. System automatycznie pobiera załączniki w tle przed wyświetleniem powiadomienia i udostępnia rozszerzeniu dostęp do lokalnych URL-i przez zasoby security-scoped.

Według Apple, rozszerzenie nie powinno samodzielnie ładować mediów — UNNotificationAttachment zawiera już lokalny URL po zakończeniu pobierania przez system. Jeśli jednak załącznik nie został pobrany na czas (np. przy słabym połączeniu), rozszerzenie może wyświetlić placeholder lub tekst alternatywny.

Praca z zasobami security-scoped

Każdy UNNotificationAttachment udostępnia security-scoped URL, do którego rozszerzenie musi uzyskać dostęp przez startAccessingSecurityScopedResource() i zwolnić przez stopAccessingSecurityScopedResource(). Te metody muszą być wywoływane parami — w przeciwnym razie zasób nie zostanie zwolniony i spowoduje wyciek uprawnień dostępu.

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)

Interaktywne powiadomienia i akcje

Notification Content Extension obsługuje niestandardowe interaktywne akcje — przyciski, które są wyświetlane pod treścią powiadomienia. Akcje są rejestrowane przy tworzeniu kategorii powiadomienia przez UNNotificationCategory i mogą być destrukcyjne, tekstowe lub tła.

Typy akcji

UNNotificationAction — prosta akcja z tytułem i opcjonalną flagą destrukcyjności. UNTextInputNotificationAction — akcja z polem wprowadzania tekstu, na przykład do szybkiej odpowiedzi na wiadomość. Oba typy obsługują opcję UNNotificationActionOptions.authenticationRequired — wymóg odblokowania urządzenia przed wykonaniem.

Rozszerzenie otrzymuje wybraną akcję przez metodę didReceive(_:withCompletionHandler:), gdzie przekazywany jest obiekt UNNotificationResponse z identyfikatorem akcji i opcjonalnym tekstem. Rozszerzenie może przetworzyć odpowiedź samodzielnie lub przekazać ją do głównej aplikacji przez wspólny kontener 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: []
)