Notification Content Extension — ماهیت، UI سفارشی و پیکربندی در iOS

Notification Content Extension چیست

Notification Content Extension — یک app 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 را پیاده‌سازی می‌کند ایجاد می‌کند.

اندازه و محدودیت‌های رابط

حداکثر ارتفاع ناحیه سفارشی — ۳۲۰ نقطه در iPhone (برای مدل‌های با صفحه نمایش بزرگ) و ۳۵۲ نقطه در 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 برای مدیریت پخش‌کننده رسانه دریافت می‌کند. در این متد باید رابط را پیکربندی کرد — تصویر را بارگیری کرد، پخش‌کننده را راه‌اندازی کرد یا داده‌ها را نمایش داد. سیستم این متد را هر بار که اعلان در زمان واقعی به‌روزرسانی می‌شود فراخوانی می‌کند.

توجه به این نکته مهم است که افزونه زمان محدودی برای اجرا دارد — حدود ۳۰ ثانیه برای یک چرخه کامل نمایش. اگر رابط در این زمان آماده نشود، 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. حداکثر اندازه هر پیوست — ۵۰ مگابایت، تا ۴ پیوست برای هر اعلان. سیستم به طور خودکار پیوست‌ها را در پس‌زمینه قبل از نمایش اعلان دانلود می‌کند و دسترسی به 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 — یک اقدام ساده با عنوان و flag اختیاری مخرب بودن. 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: []
)