Notification Content Extension — същност, персонализиран UI и настройка в iOS

Какво е Notification Content Extension

Notification Content Extension — е разширение за приложение, което презаписва показването на push известие на iOS. Вместо стандартен банер със заглавие, тяло на съобщението и бутони може да се покаже интерфейс, напълно проектиран в Interface Builder или програмно чрез UIKit или SwiftUI.

За разлика от Notification Service Extension, което променя съдържанието преди показване, Content Extension отговаря само за визуалното представяне. Разширението получава готовото известие след всички модификации и решава как да го покаже. Това е ключовата разлика между двата типа разширения за известия.

Разширението се активира, когато потребителят извърши жест за разширяване — превърти известието надолу или кликне върху него (в зависимост от модела на устройството). iOS стартира процеса на разширението, създава контролера от посочения nib или storyboard и предава известието чрез UNNotificationContentExtension.

Създаване на персонализиран интерфейс за известие

Разработката започва с добавяне на нов target в Xcode с шаблон Notification Content Extension. Xcode създава файла MainInterface.storyboard и клас, наследяващ от UIViewController, имплементиращ протокола UNNotificationContentExtension.

Размер и ограничения на интерфейса

Максимална височина на персонализираната област — 320 точки на iPhone (за модели с голям екран) и 352 точки на iPad. Съдържанието, което излиза извън тези граници, се изрязва. За адаптиране към различни размери се препоръчва използването на Auto Layout и UIScrollView за превъртаемо съдържание. Ширината винаги е равна на ширината на известието и се променя автоматично при завъртане на устройството.

Apple Human Interface Guidelines предупреждават: интерфейсът на известието трябва да бъде стегнат и да съдържа само един основен елемент — изображение, плейър, карта или формуляр за бързо въвеждане. Множеството интерактивни елементи претоварват потребителя и усложняват взаимодействието.

Връзка с главното приложение

App Group — единственият механизъм за обмен на данни между разширението и главното приложение. Чрез общата директория на App Group могат да се предават кеширани изображения, токени и настройки. Директните извиквания на API на главното приложение или достъпът до неговия UserDefaults не са достъпни поради изолация на процесите.

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

Протокол UNNotificationContentExtension

UNNotificationContentExtension — основният протокол, който определя жизнения цикъл на персонализираното известие. Протоколът предоставя методи за получаване на съдържание, обработка на действия и управление на интерфейса.

Метод didReceive:with:

didReceive(_:with:) се извиква при получаване на известие. Разширението получава обект UNNotification и UNNotificationContentExtensionMediaPlayPauseButtonType за управление на медийния плейър. В този метод трябва да се конфигурира интерфейсът — да се зареди изображение, да се инициализира плейър или да се покажат данни. Системата извиква този метод всеки път, когато известието се актуализира в реално време.

Важно е да се има предвид, че разширението има ограничено време за изпълнение — около 30 секунди за пълен цикъл на показване. Ако интерфейсът не бъде подготвен за това време, iOS ще покаже системно известие. За тежки ресурси — зареждане на изображения от мрежата, декодиране на видео — се препоръчва използването на асинхронни операции с предварително кеширане чрез App Group.

Управление на медиен плейър

Протоколът включва опционални методи за бутони play/pause: mediaPlay, mediaPause и mediaPlayPauseButtonType. Ако известието съдържа аудио или видео съдържание, разширението може да покаже вграден плейър със системен контролен елемент. iOS автоматично добавя бутон за възпроизвеждане в горния десен ъгъл на разширението при връщане на съответния тип бутон.

Медийни прикачени файлове и тяхната обработка

UNNotificationAttachment — обектът, който съдържа медийни данни, прикачени към известието. Изображения, аудио файлове и видео се добавят на етапа на създаване на известието на сървъра или в Notification Service Extension чрез UNNotificationAttachment.

Поддържани формати

За изображения: JPEG, PNG, GIF, HEIF. За аудио: MP3, AAC, ALAC, WAV. За видео: MPEG-4, H.264, HEVC. Максимален размер на всеки прикачен файл — 50 MB, до 4 прикачени файла на известие. Системата автоматично изтегля прикачените файлове на заден фон преди показване на известието и предоставя на разширението достъп до локални URL адреси чрез security-scoped ресурси.

Според Apple, разширението не трябва самостоятелно да зарежда медия — UNNotificationAttachment вече съдържа локален URL след завършване на изтеглянето от системата. Въпреки това, ако прикаченият файл не е бил изтеглен навреме (например при слаба връзка), разширението може да покаже placeholder или алтернативен текст.

Работа със security-scoped ресурси

Всеки UNNotificationAttachment предоставя security-scoped URL, до който разширението трябва да получи достъп чрез startAccessingSecurityScopedResource() и да освободи чрез stopAccessingSecurityScopedResource(). Тези методи трябва да бъдат извикани по двойки — в противен случай ресурсът няма да бъде освободен и ще причини изтичане на права за достъп.

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)

Интерактивни известия и действия

Notification Content Extension поддържа персонализирани интерактивни действия — бутони, които се показват под съдържанието на известието. Действията се регистрират при създаване на категорията на известието чрез UNNotificationCategory и могат да бъдат разрушителни, текстови или фонов.

Типове действия

UNNotificationAction — просто действие със заглавие и опционален флаг за разрушителност. UNTextInputNotificationAction — действие с поле за въвеждане на текст, например за бърз отговор на съобщение. И двата типа поддържат опцията UNNotificationActionOptions.authenticationRequired — изискване за отключване на устройството преди изпълнение.

Разширението получава избраното действие чрез метода didReceive(_:withCompletionHandler:), където се предава обект UNNotificationResponse с идентификатор на действието и опционален текст. Разширението може да обработи отговора самостоятелно или да го предаде на главното приложение чрез общия контейнер на 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: []
)