Push Notifications

Push Notifications

Implement, review, and debug local and remote notifications on iOS/macOS using UserNotifications and APNs. Covers permission flow, token registration, payload structure, foreground handling, notification actions, grouping, and rich notifications. Targets iOS 26+ with Swift 6.3, backward-compatible to iOS 16 unless noted.

Keep adjacent domains separate: Live Activity content-state payloads belong in activitykit; PushKit/VoIP call pushes belong in callkit; App Clip ephemeral notification setup belongs in app-clips; long-running or scheduled background work after a silent push belongs in background-processing.

Contents

• Correction Reviews
• Permission Flow
• APNs Registration
• Local Notifications
• Remote Notification Payload
• Notification Handling
• Notification Actions and Categories
• Notification Grouping
• Common Mistakes
• Review Checklist
• References

Correction Reviews

When reviewing flawed notification proposals, explicitly name the violated contract. APNs token reviews must say token registration is independent from alert authorization, upload on every didRegister callback, avoid local-cache-as-truth logic, never assume token length, and treat Simulator registration failure as expected while noting .apns files or simctl push can simulate delivery. Background-push reviews must say content-available only, apns-push-type: background, apns-priority: 5, Remote notifications background mode, low priority, throttled, not guaranteed, not every few minutes, and bounded didReceiveRemoteNotification returning the correct UIBackgroundFetchResult. Rich-notification reviews must say service extensions require mutable-content: 1 plus an alert payload, silent pushes do not trigger them, attachments are supported on-disk files that the system validates and stores, secrets use Keychain Sharing while App Groups are for shared files/UserDefaults, communication notifications require capability + NSUserActivityTypes + INInteraction donation + content.updating(from:), and every service-extension path including attachment/download failures and serviceExtensionTimeWillExpire() must call the content handler exactly once with original, best-attempt, or updated content.

Permission Flow

Request notification authorization before scheduling or displaying user-visible alerts, sounds, or badges. The system prompt appears only once; subsequent calls return the stored decision. APNs token registration is separate: call registerForRemoteNotifications() when the app needs a device token, even if the user hasn't granted alert authorization.

import UserNotifications

@MainActor
func requestNotificationPermission() async -> Bool {
    let center = UNUserNotificationCenter.current()
    do {
        let granted = try await center.requestAuthorization(
            options: [.alert, .sound, .badge]
        )
        return granted
    } catch {
        print("Authorization request failed: \(error)")
        return false
    }
}

Checking Current Status

Always check status before assuming permissions. The user can change settings at any time.

@MainActor
func checkNotificationStatus() async -> UNAuthorizationStatus {
    let settings = await UNUserNotificationCenter.current().notificationSettings()
    return settings.authorizationStatus
    // .notDetermined, .denied, .authorized, .provisional, .ephemeral
}

Provisional Notifications

Provisional notifications deliver quietly to the notification center without interrupting the user. The user can then choose to keep or turn them off. Use for onboarding flows where you want to demonstrate value before asking for full permission.

// Delivers silently -- no permission prompt shown to the user
try await center.requestAuthorization(options: [.alert, .sound, .badge, .provisional])

Critical Alerts

Critical alerts bypass Do Not Disturb and the mute switch. Requires a special entitlement from Apple (request via developer portal). Use only for health, safety, or security scenarios.

// Requires com.apple.developer.usernotifications.critical-alerts entitlement
try await center.requestAuthorization(
    options: [.alert, .sound, .badge, .criticalAlert]
)

Handling Denied Permissions

When the user has denied notifications, guide them to Settings with UIApplication.openSettingsURLString. Do not repeatedly prompt or nag.

APNs Registration

Use UIApplicationDelegateAdaptor to receive the device token in a SwiftUI app. The AppDelegate callbacks are the only way to receive APNs tokens.

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        UNUserNotificationCenter.current().delegate = NotificationDelegate.shared
        return true
    }

    func application(
        _ application: UIApplication,
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
    ) {
        let token = deviceToken.map { String(format: "%02x", $0) }.joined()
        print("APNs token: \(token)")
        // Send token to your server
        Task { await TokenService.shared.upload(token: token) }
    }

    func application(
        _ application: UIApplication,
        didFailToRegisterForRemoteNotificationsWithError error: Error
    ) {
        print("APNs registration failed: \(error.localizedDescription)")
        // Simulator can simulate pushes, but it does not register with APNs.
    }
}

Registration Order

Configure delegates and categories at launch. Then request user-notification authorization in context for visible notifications, and register with APNs whenever the app needs a device token. Do not gate APNs registration on .authorized; without alert authorization, remote notifications are delivered silently.

@MainActor
func configureNotifications() async {
    let center = UNUserNotificationCenter.current()
    let settings = await center.notificationSettings()

    if settings.authorizationStatus == .notDetermined {
        _ = await requestNotificationPermission()
    }

    // Needed for APNs token delivery and silent remote notifications.
    UIApplication.shared.registerForRemoteNotifications()
}

Token Handling

Device tokens change. Re-send the token to your server every time didRegisterForRemoteNotificationsWithDeviceToken fires, not just the first time. Do not persist tokens locally as a source of truth or assume a fixed token length.

Local Notifications

Schedule notifications directly from the device without a server. Useful for reminders, timers, and location-based alerts.

Creating Content

let content = UNMutableNotificationContent()
content.title = "Workout Reminder"
content.subtitle = "Time to move"
content.body = "You have a scheduled workout in 15 minutes."
content.sound = .default
content.badge = NSNumber(value: 1)
content.userInfo = ["workoutId": "abc123"]
content.threadIdentifier = "workouts"  // groups in notification center

Trigger Types

// Fire after a time interval (minimum 60 seconds for repeating)
let timeTrigger = UNTimeIntervalNotificationTrigger(timeInterval: 300, repeats: false)

// Fire at a specific date/time
var dateComponents = DateComponents()
dateComponents.hour = 8
dateComponents.minute = 30
let calendarTrigger = UNCalendarNotificationTrigger(
    dateMatching: dateComponents, repeats: true  // daily at 8:30 AM
)

// Fire when entering a geographic region
let region = CLCircularRegion(
    center: CLLocationCoordinate2D(latitude: 37.33, longitude: -122.01),
    radius: 100,
    identifier: "gym"
)
region.notifyOnEntry = true
region.notifyOnExit = false
let locationTrigger = UNLocationNotificationTrigger(region: region, repeats: false)
// Requires "When In Use" location permission at minimum

Scheduling and Managing

let request = UNNotificationRequest(
    identifier: "workout-reminder-abc123",
    content: content,
    trigger: timeTrigger
)

let center = UNUserNotificationCenter.current()
try await center.add(request)

// Remove specific pending notifications
center.removePendingNotificationRequests(withIdentifiers: ["workout-reminder-abc123"])

// Remove all pending
center.removeAllPendingNotificationRequests()

// Remove delivered notifications from notification center
center.removeDeliveredNotifications(withIdentifiers: ["workout-reminder-abc123"])
center.removeAllDeliveredNotifications()

// List all pending requests
let pending = await center.pendingNotificationRequests()

Remote Notification Payload

Standard APNs Payload

{
    "aps": {
        "alert": {
            "title": "New Message",
            "subtitle": "From Alice",
            "body": "Hey, are you free for lunch?"
        },
        "badge": 3,
        "sound": "default",
        "thread-id": "chat-alice",
        "category": "MESSAGE_CATEGORY"
    },
    "messageId": "msg-789",
    "senderId": "user-alice"
}

Silent / Background Push

Set content-available: 1 with no alert, sound, or badge. Requires "Background Modes > Remote notifications" plus APNs headers apns-push-type: background and apns-priority: 5. The system treats these as low priority, throttled, and not guaranteed; do not send them every few minutes or rely on them for immediate freshness. In didReceiveRemoteNotification, do bounded work and return a UIBackgroundFetchResult promptly, within the background execution window.

{
    "aps": {
        "content-available": 1
    },
    "updateType": "new-data"
}

Handle in AppDelegate:

func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any]
) async -> UIBackgroundFetchResult {
    guard let updateType = userInfo["updateType"] as? String else {
        return .noData
    }
    do {
        try await DataSyncService.shared.sync(trigger: updateType)
        return .newData
    } catch {
        return .failed
    }
}

Mutable Content

Set mutable-content: 1 plus an alert dictionary to let a Notification Service Extension modify an alerting remote notification before display. Silent pushes do not trigger the service extension. Use service extensions for bounded work such as downloading supported on-disk attachments, decrypting display text, or configuring communication notifications; call the content handler on every success, failure, and timeout path. For communication notifications, enable the capability, add NSUserActivityTypes, donate the INInteraction, then call content.updating(from:).

{
    "aps": {
        "alert": { "title": "Photo", "body": "Alice sent a photo" },
        "mutable-content": 1
    },
    "imageUrl": "https://example.com/photo.jpg"
}

Localized Notifications

Use localization keys so the notification displays in the user's language:

{
    "aps": {
        "alert": {
            "title-loc-key": "NEW_MESSAGE_TITLE",
            "loc-key": "NEW_MESSAGE_BODY",
            "loc-args": ["Alice"]
        }
    }
}

Notification Handling

UNUserNotificationCenterDelegate

Implement the delegate to control foreground display and handle user taps. Set the delegate as early as possible -- in application(_:didFinishLaunchingWithOptions:) or App.init.

@MainActor
final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
    static let shared = NotificationDelegate()

    // Called when notification arrives while app is in FOREGROUND
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification
    ) async -> UNNotificationPresentationOptions {
        // Return which presentation elements to show
        // Without this, foreground notifications are silently suppressed
        return [.banner, .sound, .badge]
    }

    // Called when user TAPS the notification
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse
    ) async {
        let userInfo = response.notification.request.content.userInfo
        let actionIdentifier = response.actionIdentifier

        switch actionIdentifier {
        case UNNotificationDefaultActionIdentifier:
            // User tapped the notification body
            await handleNotificationTap(userInfo: userInfo)
        case UNNotificationDismissActionIdentifier:
            // User dismissed the notification
            break
        default:
            // Custom action button tapped
            await handleCustomAction(actionIdentifier, userInfo: userInfo)
        }
    }
}

Deep Linking from Notifications

Route notification taps to the correct screen using a shared @Observable router. The delegate writes a pending destination; the SwiftUI view observes and consumes it.

@Observable @MainActor
final class DeepLinkRouter {
    static let shared = DeepLinkRouter()

    var pendingDestination: AppDestination?
}

// In NotificationDelegate:
func handleNotificationTap(userInfo: [AnyHashable: Any]) async {
    guard let id = userInfo["messageId"] as? String else { return }
    DeepLinkRouter.shared.pendingDestination = .chat(id: id)
}

// In SwiftUI -- observe and consume:
.onChange(of: router.pendingDestination) { _, destination in
    if let destination {
        path.append(destination)
        router.pendingDestination = nil
    }
}

See references/notification-patterns.md for the full deep-linking handler with tab switching.

Notification Actions and Categories

Define interactive actions that appear as buttons on the notification. Register categories at launch.

Defining Categories and Actions

func registerNotificationCategories() {
    let replyAction = UNTextInputNotificationAction(
        identifier: "REPLY_ACTION",
        title: "Reply",
        options: [],
        textInputButtonTitle: "Send",
        textInputPlaceholder: "Type a reply..."
    )

    let likeAction = UNNotificationAction(
        identifier: "LIKE_ACTION",
        title: "Like",
        options: []
    )

    let deleteAction = UNNotificationAction(
        identifier: "DELETE_ACTION",
        title: "Delete",
        options: [.destructive, .authenticationRequired]
    )

    let messageCategory = UNNotificationCategory(
        identifier: "MESSAGE_CATEGORY",
        actions: [replyAction, likeAction, deleteAction],
        intentIdentifiers: [],
        options: [.customDismissAction]  // fires didReceive on dismiss too
    )

    UNUserNotificationCenter.current().setNotificationCategories([messageCategory])
}

Handling Action Responses

func handleCustomAction(_ identifier: String, userInfo: [AnyHashable: Any]) async {
    switch identifier {
    case "REPLY_ACTION":
        // response is UNTextInputNotificationResponse for text input actions
        break
    case "LIKE_ACTION":
        guard let messageId = userInfo["messageId"] as? String else { return }
        await MessageService.shared.likeMessage(id: messageId)
    case "DELETE_ACTION":
        guard let messageId = userInfo["messageId"] as? String else { return }
        await MessageService.shared.deleteMessage(id: messageId)
    default:
        break
    }
}

Action options:

• .authenticationRequired -- device must be unlocked to perform the action
• .destructive -- displayed in red; use for delete/remove actions
• .foreground -- launches the app to the foreground when tapped

Notification Grouping

Group related notifications with threadIdentifier (or thread-id in the APNs payload). Each unique thread becomes a separate group in Notification Center.

content.threadIdentifier = "chat-alice"  // all messages from Alice group together
content.summaryArgument = "Alice"
content.summaryArgumentCount = 3         // "3 more notifications from Alice"

Customize the summary format string in the category:

let category = UNNotificationCategory(
    identifier: "MESSAGE_CATEGORY",
    actions: [replyAction],
    intentIdentifiers: [],
    categorySummaryFormat: "%u more messages from %@",
    options: []
)

Common Mistakes

DON'T: Gate APNs token registration on alert authorization when the app needs silent pushes or server token binding. DO: Request authorization for alerts/sounds/badges, and register with APNs whenever a device token is needed. DON'T: Convert device token with String(data: deviceToken, encoding: .utf8). DO: Use hex: deviceToken.map { String(format: "%02x", $0) }.joined(). DON'T: Promise every-few-minutes silent refresh or immediate background delivery. DO: Say background pushes are low priority, throttled, not guaranteed, limited to a few per hour in practice, and require bounded didReceiveRemoteNotification work that returns the correct UIBackgroundFetchResult. DON'T: Expect a silent push to run a Notification Service Extension, or leave the extension without calling its content handler. DO: Use mutable-content: 1 with an alert payload, supported on-disk attachments that the system validates and stores, INInteraction donation plus content.updating(from:) for communication notifications, and original or best-attempt content on every success, failure, and timeout path. DON'T: Forget foreground handling. Without willPresent, notifications are silently suppressed. DO: Implement willPresent and return .banner, .sound, .badge. DON'T: Set delegate too late or register from SwiftUI views without AppDelegate adaptor. DO: Set delegate in App.init; use UIApplicationDelegateAdaptor for APNs. DON'T: Upload APNs tokens only when they "change" or assume a fixed token length. DO: Upload on every didRegister callback and treat the token as opaque data converted to hex. DON'T: Put Live Activity, VoIP, or App Clip-specific notification rules here. DO: Route those to activitykit, callkit, and app-clips.

Review Checklist

• [ ] Authorization requested before visible alerts/sounds/badges; denied case handled (Settings link)
• [ ] APNs registration not incorrectly blocked by alert authorization status
• [ ] Device token converted to hex, uploaded on every callback, and not treated as a locally cached or fixed-length constant
• [ ] UNUserNotificationCenterDelegate set in App.init or application(_:didFinishLaunching:)
• [ ] Foreground (willPresent) and tap (didReceive) handling implemented
• [ ] Categories/actions registered at launch if interactive notifications needed
• [ ] Silent push uses content-available: 1, no alert/sound/badge, apns-push-type: background, apns-priority: 5, Background Modes > Remote notifications, throttling caveats, and correct UIBackgroundFetchResult

References

• references/notification-patterns.md — AppDelegate setup, APNs callbacks, deep-link router, silent push, debugging
• references/rich-notifications.md — Service Extension, Content Extension, attachments, communication notifications
• Apple docs: APNs registration, permission, payloads, background pushes

Notification Patterns

Detailed implementation patterns for push notifications in iOS apps. Covers the complete lifecycle from AppDelegate wiring through debugging delivery issues.

Contents

• Complete AppDelegate Adaptor Setup
• Full UNUserNotificationCenterDelegate
• Deep Link Router
• Silent Push Handler
• Notification Scheduling Manager
• Token Refresh and Update Flow
• Category Registration
• Testing Notifications
• Badge Management
• Provisional to Full Authorization Upgrade

Complete AppDelegate Adaptor Setup

The full AppDelegate wiring for a SwiftUI app that handles both remote and local notifications.

import SwiftUI
import UserNotifications

@main
struct MyApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
    @State private var router = DeepLinkRouter.shared

    init() {
        // Set delegate as early as possible so no notifications are missed.
        // App.init runs before application(_:didFinishLaunchingWithOptions:).
        UNUserNotificationCenter.current().delegate = NotificationDelegate.shared
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(router)
                .task { await setupNotifications() }
        }
    }

    private func setupNotifications() async {
        registerNotificationCategories()

        let center = UNUserNotificationCenter.current()
        let settings = await center.notificationSettings()

        if settings.authorizationStatus == .notDetermined {
            _ = try? await center.requestAuthorization(
                options: [.alert, .sound, .badge]
            )
        }

        // APNs registration is independent from alert authorization. If the
        // user denies alerts, remote notifications can still arrive silently.
        await MainActor.run {
            UIApplication.shared.registerForRemoteNotifications()
        }
    }
}

AppDelegate Class

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        // Delegate may also be set here if not set in App.init.
        // Setting in App.init is preferred because it runs earlier.
        return true
    }

    func application(
        _ application: UIApplication,
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
    ) {
        let token = deviceToken.map { String(format: "%02x", $0) }.joined()
        print("APNs device token: \(token)")

        // Always send token to server -- tokens can change between launches.
        Task { @MainActor in
            await TokenService.shared.upload(token: token)
        }
    }

    func application(
        _ application: UIApplication,
        didFailToRegisterForRemoteNotificationsWithError error: Error
    ) {
        #if targetEnvironment(simulator)
        // Simulator can simulate pushes with .apns files or simctl, but it
        // does not register with APNs for a real device token.
        print("Simulator: APNs device-token registration is unavailable.")
        #else
        print("APNs registration failed: \(error.localizedDescription)")
        // Log to your analytics/crash reporting service
        #endif
    }

    // Silent push / background notification handler
    func application(
        _ application: UIApplication,
        didReceiveRemoteNotification userInfo: [AnyHashable: Any]
    ) async -> UIBackgroundFetchResult {
        await BackgroundNotificationHandler.shared.handle(userInfo: userInfo)
    }
}

Full UNUserNotificationCenterDelegate

@MainActor
final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
    static let shared = NotificationDelegate()

    private override init() { super.init() }

    /// Called when a notification arrives while the app is in the foreground.
    /// Return which presentation options to use. Without this method,
    /// foreground notifications are silently suppressed.
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification
    ) async -> UNNotificationPresentationOptions {
        let userInfo = notification.request.content.userInfo

        // Example: suppress banner for the chat screen the user is already viewing
        if let chatId = userInfo["chatId"] as? String,
           NavigationState.shared.currentChatId == chatId {
            // Still update badge/list but do not show a banner
            return [.badge, .list, .sound]
        }

        return [.banner, .sound, .badge, .list]
    }

    /// Called when the user taps the notification or a notification action button.
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse
    ) async {
        let userInfo = response.notification.request.content.userInfo
        let categoryIdentifier = response.notification.request.content.categoryIdentifier

        switch response.actionIdentifier {
        case UNNotificationDefaultActionIdentifier:
            await routeNotificationTap(category: categoryIdentifier, userInfo: userInfo)

        case UNNotificationDismissActionIdentifier:
            // User swiped away the notification. Only fires if the category
            // was created with .customDismissAction option.
            break

        default:
            // Custom action button
            await handleAction(
                response.actionIdentifier,
                category: categoryIdentifier,
                response: response,
                userInfo: userInfo
            )
        }
    }

    // MARK: - Routing

    private func routeNotificationTap(
        category: String,
        userInfo: [AnyHashable: Any]
    ) async {
        switch category {
        case "MESSAGE_CATEGORY":
            guard let chatId = userInfo["chatId"] as? String else { return }
            DeepLinkRouter.shared.navigate(to: .chat(id: chatId))

        case "WORKOUT_CATEGORY":
            guard let workoutId = userInfo["workoutId"] as? String else { return }
            DeepLinkRouter.shared.navigate(to: .workout(id: workoutId))

        default:
            // Unknown category -- open the app to its default state
            break
        }
    }

    private func handleAction(
        _ actionIdentifier: String,
        category: String,
        response: UNNotificationResponse,
        userInfo: [AnyHashable: Any]
    ) async {
        switch (category, actionIdentifier) {
        case ("MESSAGE_CATEGORY", "REPLY_ACTION"):
            guard let textResponse = response as? UNTextInputNotificationResponse,
                  let chatId = userInfo["chatId"] as? String else { return }
            await MessageService.shared.sendReply(
                text: textResponse.userText,
                chatId: chatId
            )

        case ("MESSAGE_CATEGORY", "LIKE_ACTION"):
            guard let messageId = userInfo["messageId"] as? String else { return }
            await MessageService.shared.likeMessage(id: messageId)

        case ("MESSAGE_CATEGORY", "MARK_READ_ACTION"):
            guard let chatId = userInfo["chatId"] as? String else { return }
            await MessageService.shared.markAsRead(chatId: chatId)

        default:
            break
        }
    }
}

Deep Link Router

An @Observable router that bridges notification taps to SwiftUI navigation. The router holds a pending destination that the view layer observes and consumes.

@Observable
@MainActor
final class DeepLinkRouter {
    static let shared = DeepLinkRouter()

    var pendingDestination: AppDestination?

    func navigate(to destination: AppDestination) {
        pendingDestination = destination
    }
}

enum AppDestination: Hashable {
    case chat(id: String)
    case workout(id: String)
    case profile(userId: String)
    case settings
}

// In the root view:
struct RootView: View {
    @Environment(DeepLinkRouter.self) private var router
    @State private var selectedTab: Tab = .home
    @State private var homePath = NavigationPath()
    @State private var chatPath = NavigationPath()

    var body: some View {
        TabView(selection: $selectedTab) {
            Tab("Home", systemImage: "house", value: .home) {
                NavigationStack(path: $homePath) {
                    HomeView()
                        .navigationDestination(for: AppDestination.self) { dest in
                            destinationView(for: dest)
                        }
                }
            }
            Tab("Chat", systemImage: "message", value: .chat) {
                NavigationStack(path: $chatPath) {
                    ChatListView()
                        .navigationDestination(for: AppDestination.self) { dest in
                            destinationView(for: dest)
                        }
                }
            }
        }
        .onChange(of: router.pendingDestination) { _, destination in
            guard let destination else { return }
            handleDeepLink(destination)
            router.pendingDestination = nil
        }
    }

    private func handleDeepLink(_ destination: AppDestination) {
        switch destination {
        case .chat:
            selectedTab = .chat
            chatPath = NavigationPath()
            chatPath.append(destination)
        case .workout:
            selectedTab = .home
            homePath = NavigationPath()
            homePath.append(destination)
        case .profile, .settings:
            selectedTab = .home
            homePath = NavigationPath()
            homePath.append(destination)
        }
    }

    @ViewBuilder
    private func destinationView(for destination: AppDestination) -> some View {
        switch destination {
        case .chat(let id): ChatDetailView(chatId: id)
        case .workout(let id): WorkoutDetailView(workoutId: id)
        case .profile(let userId): ProfileView(userId: userId)
        case .settings: SettingsView()
        }
    }
}

Silent Push Handler

Silent pushes wake the app in the background to fetch new content. The system gives approximately 30 seconds of background execution time. Return the correct UIBackgroundFetchResult so the system can learn the app's data patterns and schedule future wakes efficiently.

@MainActor
final class BackgroundNotificationHandler {
    static let shared = BackgroundNotificationHandler()

    func handle(userInfo: [AnyHashable: Any]) async -> UIBackgroundFetchResult {
        guard let action = userInfo["action"] as? String else {
            return .noData
        }

        do {
            switch action {
            case "sync":
                let hasNewData = try await DataSyncService.shared.performSync()
                return hasNewData ? .newData : .noData

            case "refresh-config":
                try await ConfigService.shared.refreshRemoteConfig()
                return .newData

            case "clear-cache":
                await CacheManager.shared.clearExpired()
                return .newData

            default:
                return .noData
            }
        } catch {
            print("Background notification handling failed: \(error)")
            return .failed
        }
    }
}

Important: The Background Modes capability with "Remote notifications" must be enabled in the Xcode project for silent push to work. Send background pushes with aps.content-available = 1, no alert/sound/badge keys, apns-push-type: background, and apns-priority: 5. Delivery is low priority, throttled, and not guaranteed; Apple cautions against more than two or three per hour, so do not use silent pushes for every-few-minutes polling or user-visible notification behavior. Keep didReceiveRemoteNotification work bounded and return the correct UIBackgroundFetchResult within the background execution window.

When reviewing a background-push proposal, explicitly call out these contracts: background pushes are not immediate freshness signals; APNs may throttle or drop them; the app needs Background Modes > Remote notifications; the app delegate handler must finish promptly and return .newData, .noData, or .failed based on the actual result.

Notification Scheduling Manager

A service that encapsulates local notification scheduling, making it testable and reusable.

@MainActor
final class NotificationScheduler {
    private let center = UNUserNotificationCenter.current()

    // MARK: - Schedule

    func scheduleReminder(
        id: String,
        title: String,
        body: String,
        at date: Date,
        repeats: Bool = false,
        categoryIdentifier: String? = nil,
        userInfo: [String: String] = [:]
    ) async throws {
        let content = UNMutableNotificationContent()
        content.title = title
        content.body = body
        content.sound = .default
        content.userInfo = userInfo
        if let category = categoryIdentifier {
            content.categoryIdentifier = category
        }

        let components = Calendar.current.dateComponents(
            [.year, .month, .day, .hour, .minute],
            from: date
        )
        let trigger = UNCalendarNotificationTrigger(
            dateMatching: components,
            repeats: repeats
        )

        let request = UNNotificationRequest(
            identifier: id,
            content: content,
            trigger: trigger
        )

        try await center.add(request)
    }

    func scheduleDailyReminder(
        id: String,
        title: String,
        body: String,
        hour: Int,
        minute: Int
    ) async throws {
        let content = UNMutableNotificationContent()
        content.title = title
        content.body = body
        content.sound = .default

        var components = DateComponents()
        components.hour = hour
        components.minute = minute

        let trigger = UNCalendarNotificationTrigger(
            dateMatching: components,
            repeats: true
        )

        let request = UNNotificationRequest(
            identifier: id,
            content: content,
            trigger: trigger
        )

        try await center.add(request)
    }

    // MARK: - Manage

    func cancelNotification(id: String) {
        center.removePendingNotificationRequests(withIdentifiers: [id])
        center.removeDeliveredNotifications(withIdentifiers: [id])
    }

    func cancelAll() {
        center.removeAllPendingNotificationRequests()
        center.removeAllDeliveredNotifications()
    }

    func pendingNotifications() async -> [UNNotificationRequest] {
        await center.pendingNotificationRequests()
    }

    func isScheduled(id: String) async -> Bool {
        let pending = await center.pendingNotificationRequests()
        return pending.contains { $0.identifier == id }
    }
}

Token Refresh and Update Flow

Device tokens can change between app launches. Treat the token as ephemeral and always send the latest to your server from every didRegisterForRemoteNotificationsWithDeviceToken callback. Do not use UserDefaults as the source of truth for skipping upload, and do not assume a fixed token length.

@MainActor
@Observable
final class TokenService {
    static let shared = TokenService()

    private(set) var currentToken: String?

    func upload(token: String) async {
        do {
            try await APIClient.shared.registerDeviceToken(token)
            currentToken = token
        } catch {
            print("Failed to upload APNs token: \(error)")
            // Retry on next launch -- didRegisterForRemoteNotifications fires again
        }
    }

    /// Call when the user logs out to disassociate the token from their account.
    func invalidate() async {
        guard let token = currentToken else { return }
        try? await APIClient.shared.unregisterDeviceToken(token)
        currentToken = nil
    }
}

Logout flow: When a user logs out, unregister the device token from your server. Otherwise the old user's account continues receiving pushes on this device.

Category Registration

Register categories at app launch, before any notification arrives. Calling setNotificationCategories replaces the entire set, so register all categories in one call.

func registerNotificationCategories() {
    // Message category
    let replyAction = UNTextInputNotificationAction(
        identifier: "REPLY_ACTION",
        title: "Reply",
        options: [],
        textInputButtonTitle: "Send",
        textInputPlaceholder: "Type a reply..."
    )
    let markReadAction = UNNotificationAction(
        identifier: "MARK_READ_ACTION",
        title: "Mark as Read",
        options: []
    )
    let messageCategory = UNNotificationCategory(
        identifier: "MESSAGE_CATEGORY",
        actions: [replyAction, markReadAction],
        intentIdentifiers: [],
        categorySummaryFormat: "%u more messages from %@",
        options: [.customDismissAction]
    )

    // Workout category
    let startAction = UNNotificationAction(
        identifier: "START_WORKOUT_ACTION",
        title: "Start",
        options: [.foreground]
    )
    let skipAction = UNNotificationAction(
        identifier: "SKIP_WORKOUT_ACTION",
        title: "Skip",
        options: [.destructive]
    )
    let workoutCategory = UNNotificationCategory(
        identifier: "WORKOUT_CATEGORY",
        actions: [startAction, skipAction],
        intentIdentifiers: [],
        options: []
    )

    UNUserNotificationCenter.current().setNotificationCategories([
        messageCategory,
        workoutCategory,
    ])
}

Testing Notifications

Simulator Limitations

• Remote notifications cannot be received via APNs on the simulator.
• Drag-and-drop `.apns` files onto the simulator to simulate remote notifications.
• Local notifications work normally on the simulator.
• didFailToRegisterForRemoteNotificationsWithError always fires on the simulator.

Simulating Remote Notifications

Create a .apns file and drag it onto the running simulator:

{
    "Simulator Target Bundle": "com.example.myapp",
    "aps": {
        "alert": {
            "title": "Test Notification",
            "body": "This is a simulated push notification."
        },
        "badge": 1,
        "sound": "default",
        "category": "MESSAGE_CATEGORY"
    },
    "messageId": "test-123",
    "chatId": "chat-abc"
}

Or use the xcrun simctl push command:

xcrun simctl push booted com.example.myapp payload.apns

Testing on Device

Use the APNs sandbox environment during development. The device token from a development build uses the sandbox; production builds use the production APNs endpoint.

For quick testing without a server, use tools like:

• Apple Push Notification Console to send development-environment test payloads and inspect delivery logs
• Command-line APNs requests generated by the console or your own provider scripts

Debugging Delivery

1. Check entitlements: Ensure the push notification entitlement is in the app's provisioning profile. The aps-environment key must be present.

2. Verify token format: The token you send to your provider should be the hexadecimal bytes from deviceToken. Do not hard-code a token length; APNs says not to make assumptions about device token size.

3. Check APNs response codes:

4. Console.app: Connect the device, open Console.app on Mac, filter by dasd or apsd or your app's bundle identifier. Look for delivery confirmations or rejection reasons.

5. Common reasons notifications do not arrive:

• App is in Low Power Mode and the system defers delivery
• Focus / Do Not Disturb is active and the app is not in the allowed list
• The device has no internet connection
• The device token has changed and the server is using a stale token (status 410)
• Silent pushes are rate-limited by the system (typically a few per hour)
• The notification payload exceeds 4096 bytes
• The APNs certificate or key has expired

6. Background push debugging: Silent pushes are heavily throttled. The system decides when and whether to wake the app. During development, the system is more generous. In production, expect delays. Use BGTaskScheduler for more reliable background processing.

Badge Management

Reset the badge count when the user opens the app so stale badge numbers do not persist.

// In AppDelegate or SceneDelegate
func sceneDidBecomeActive(_ scene: UIScene) {
    UNUserNotificationCenter.current().setBadgeCount(0)
}

// Or in SwiftUI with the scene phase
struct ContentView: View {
    @Environment(\.scenePhase) private var scenePhase

    var body: some View {
        MainView()
            .onChange(of: scenePhase) { _, phase in
                if phase == .active {
                    Task {
                        try? await UNUserNotificationCenter.current().setBadgeCount(0)
                    }
                }
            }
    }
}

setBadgeCount(_:) (iOS 16+) is the modern UserNotifications API for updating the badge count. Use availability checks if you still support older deployment targets.

Provisional to Full Authorization Upgrade

If you started with provisional notifications, you can later ask for full authorization. The system shows the permission prompt again.

@MainActor
func upgradeToFullAuthorization() async -> Bool {
    let center = UNUserNotificationCenter.current()
    let settings = await center.notificationSettings()

    guard settings.authorizationStatus == .provisional else {
        return settings.authorizationStatus == .authorized
    }

    do {
        // This presents the system prompt to the user
        let granted = try await center.requestAuthorization(
            options: [.alert, .sound, .badge]
        )
        return granted
    } catch {
        return false
    }
}

Rich Notifications

Rich notifications enhance the standard notification banner with images, video, audio, custom UI, and interactive elements. They use two extension types: Notification Service Extension (modifies content before display) and Notification Content Extension (provides custom UI in the expanded notification).

Contents

• Notification Service Extension
• Notification Attachments
• Notification Content Extension
• Communication Notifications
• Extension Gotchas
• Complete Service Extension Example

Notification Service Extension

A Notification Service Extension runs for an alerting remote notification whose payload has mutable-content: 1 and an alert dictionary with title, subtitle, or body content. It has approximately 30 seconds to modify the notification content before the system displays it. Call the content handler on every path: success, partial failure, invalid payload, and serviceExtensionTimeWillExpire(). If the extension does not call the handler in time, the system displays the original notification.

When reviewing a flawed rich-notification design, explicitly correct four contracts: silent pushes do not trigger service extensions; attachments must be supported files on disk and are validated and stored by the system; communication notifications require the capability, NSUserActivityTypes, INInteraction donation, and content.updating(from:); every service-extension path, including download/decryption failures and serviceExtensionTimeWillExpire(), must call the content handler exactly once with original, best-attempt, or updated content.

Creating the Extension

In Xcode: File > New > Target > Notification Service Extension. This creates a new target with a NotificationService class.

import UserNotifications

class NotificationService: UNNotificationServiceExtension {
    private var contentHandler: ((UNNotificationContent) -> Void)?
    private var bestAttemptContent: UNMutableNotificationContent?
    private var didComplete = false

    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        self.contentHandler = contentHandler
        bestAttemptContent = request.content.mutableCopy() as? UNMutableNotificationContent

        guard let content = bestAttemptContent else {
            contentHandler(request.content)
            return
        }

        // Modify the notification content here
        Task {
            await processNotification(content: content)
            contentHandler(content)
        }
    }

    /// Called if the extension is about to be terminated (ran out of time).
    /// Deliver the best attempt -- even a partially modified notification
    /// is better than nothing.
    override func serviceExtensionTimeWillExpire() {
        if let handler = contentHandler, let content = bestAttemptContent {
            handler(content)
        }
    }

    private func processNotification(content: UNMutableNotificationContent) async {
        // Download image if URL is provided
        if let imageUrlString = content.userInfo["imageUrl"] as? String {
            await attachImage(from: imageUrlString, to: content)
        }

        // Decrypt body if encrypted
        if let encrypted = content.userInfo["encryptedBody"] as? String {
            content.body = decrypt(encrypted)
        }
    }
}

Downloading Images and Media

Download media from a URL and attach it to the notification. The attachment must be written to disk in the extension's temporary directory.

extension NotificationService {
    private func attachImage(
        from urlString: String,
        to content: UNMutableNotificationContent
    ) async {
        guard let url = URL(string: urlString) else { return }

        do {
            let (data, response) = try await URLSession.shared.data(from: url)

            // Determine file extension from MIME type
            let ext = fileExtension(for: response.mimeType)
            let tempDir = FileManager.default.temporaryDirectory
            let fileURL = tempDir.appendingPathComponent(UUID().uuidString + ext)

            try data.write(to: fileURL)

            let attachment = try UNNotificationAttachment(
                identifier: "image",
                url: fileURL,
                options: nil
            )
            content.attachments = [attachment]
        } catch {
            print("Failed to download notification image: \(error)")
            // Notification displays without the image -- graceful degradation
        }
    }

    private func fileExtension(for mimeType: String?) -> String {
        switch mimeType {
        case "image/jpeg": return ".jpg"
        case "image/png": return ".png"
        case "image/gif": return ".gif"
        case "video/mp4", "video/mpeg4": return ".mp4"
        case "audio/mpeg", "audio/mp3": return ".mp3"
        case "audio/wav": return ".wav"
        default: return ".jpg"
        }
    }
}

Decrypting Encrypted Payloads

Use the service extension to decrypt sensitive notification content. The APNs payload carries an encrypted blob; the extension decrypts it before display.

extension NotificationService {
    private func decrypt(_ encryptedBase64: String) -> String {
        guard let data = Data(base64Encoded: encryptedBase64) else {
            return "New notification"  // fallback
        }
        // Use your encryption library (CryptoKit, etc.) to decrypt
        // Store notification decryption keys in a Keychain access group shared
        // by the app and extension, not in UserDefaults or the APNs payload.
        do {
            let decrypted = try EncryptionService.shared.decrypt(data)
            return String(data: decrypted, encoding: .utf8) ?? "New notification"
        } catch {
            return "New notification"
        }
    }
}

Sharing Data with Extensions

The service extension runs in a separate process from the main app. Use App Groups for shared files and UserDefaults; use Keychain Sharing for secrets or tokens.

1. Enable "App Groups" capability on both the main app target and the extension target. 2. Use the same group identifier (e.g., group.com.example.myapp). 3. Enable "Keychain Sharing" on both targets for shared keychain items. The kSecAttrAccessGroup value must be one of the target's keychain access groups, not the App Group container identifier.

// Shared UserDefaults
let sharedDefaults = UserDefaults(suiteName: "group.com.example.myapp")

// Shared file container
let sharedContainer = FileManager.default.containerURL(
    forSecurityApplicationGroupIdentifier: "group.com.example.myapp"
)

// Shared Keychain: set kSecAttrAccessGroup to a Keychain Sharing access group
// that both targets include in their entitlements.

Extension memory: Notification Service Extensions are memory-constrained. Do not load large frameworks or perform memory-intensive operations. If the system terminates the extension, it shows the original notification.

Notification Attachments

UNNotificationAttachment supports images, GIFs, video, and audio. The system displays a thumbnail in the collapsed notification and the full media in the expanded view.

Supported Formats and Limits

Creating Attachments

// From a local file URL
let attachment = try UNNotificationAttachment(
    identifier: "photo",
    url: localFileURL,
    options: nil
)

// With options for thumbnailing
let attachment = try UNNotificationAttachment(
    identifier: "photo",
    url: localFileURL,
    options: [
        UNNotificationAttachmentOptionsThumbnailClippingRectKey:
            CGRect(x: 0, y: 0, width: 1, height: 0.5).dictionaryRepresentation,
        UNNotificationAttachmentOptionsThumbnailTimeKey: 0  // for video: thumbnail at 0 seconds
    ]
)

// Attach to content
content.attachments = [attachment]

Important: The file URL must point to a supported audio, image, or video file on disk. For service extensions, write downloads to the extension's temporary directory before creating UNNotificationAttachment; do not attach arbitrary remote URLs or unsupported file types. For local notifications, create the attachment from a file the app can read when scheduling. The system validates attachments and moves them into its attachment data store; it copies attachments located inside the app bundle.

Multiple Attachments

You can attach multiple items, but only the first attachment is shown as the thumbnail in the collapsed notification. The expanded view can show all attachments.

content.attachments = [imageAttachment, audioAttachment]
// imageAttachment appears as the thumbnail

GIF Animations

GIF files are supported image attachments and may contain an animated image sequence. Test the expanded notification UI for the actual presentation you need.

let gifURL = tempDir.appendingPathComponent("animation.gif")
try gifData.write(to: gifURL)
let attachment = try UNNotificationAttachment(
    identifier: "animation",
    url: gifURL,
    options: nil
)

Notification Content Extension

A Notification Content Extension provides a custom view controller that displays when the user long-presses (or expands) a notification. Use it for richer UI than attachments alone can provide.

Creating the Extension

In Xcode: File > New > Target > Notification Content Extension. This creates a new target with a storyboard and a NotificationViewController.

Configuration (Info.plist)

The extension's Info.plist must declare which notification categories it handles:

<key>NSExtension</key>
<dict>
    <key>NSExtensionAttributes</key>
    <dict>
        <key>UNNotificationExtensionCategory</key>
        <!-- Use a string for one category, or an array for multiple. -->
        <array>
            <string>MESSAGE_CATEGORY</string>
            <string>PHOTO_CATEGORY</string>
        </array>
        <!-- Optional: size ratio (height / width). Default 1.0 -->
        <key>UNNotificationExtensionInitialContentSizeRatio</key>
        <real>0.5</real>
        <!-- Optional: hide the default notification body below the custom UI -->
        <key>UNNotificationExtensionDefaultContentHidden</key>
        <true/>
        <!-- Optional: allow user interaction in the custom UI -->
        <key>UNNotificationExtensionUserInteractionEnabled</key>
        <true/>
    </dict>
    <key>NSExtensionMainStoryboard</key>
    <string>MainInterface</string>
    <key>NSExtensionPointIdentifier</key>
    <string>com.apple.usernotifications.content-extension</string>
</dict>

View Controller Implementation

import UIKit
import UserNotifications
import UserNotificationsUI

class NotificationViewController: UIViewController, UNNotificationContentExtension {
    @IBOutlet weak var titleLabel: UILabel!
    @IBOutlet weak var bodyLabel: UILabel!
    @IBOutlet weak var imageView: UIImageView!

    func didReceive(_ notification: UNNotification) {
        let content = notification.request.content
        titleLabel.text = content.title
        bodyLabel.text = content.body

        // Display the first attachment
        if let attachment = content.attachments.first,
           attachment.url.startAccessingSecurityScopedResource() {
            defer { attachment.url.stopAccessingSecurityScopedResource() }
            if let data = try? Data(contentsOf: attachment.url) {
                imageView.image = UIImage(data: data)
            }
        }
    }

    /// Called when the user taps a notification action while the content
    /// extension is visible.
    func didReceive(
        _ response: UNNotificationResponse,
        completionHandler completion: @escaping (UNNotificationContentExtensionResponseOption) -> Void
    ) {
        switch response.actionIdentifier {
        case "LIKE_ACTION":
            // Update UI to show "liked" state
            animateLikeConfirmation()
            // Dismiss after a short delay
            Task {
                try? await Task.sleep(for: .seconds(0.5))
                completion(.dismiss)
            }

        case "REPLY_ACTION":
            if let textResponse = response as? UNTextInputNotificationResponse {
                // Handle reply inline without opening the app
                showReplySentConfirmation(text: textResponse.userText)
                Task {
                    try? await Task.sleep(for: .seconds(1.0))
                    completion(.dismiss)
                }
            }

        default:
            // Forward to the app's notification delegate
            completion(.dismissAndForwardAction)
        }
    }
}

Response Options

Media Playback in Notifications

The content extension can play audio or video. Implement mediaPlayPauseButtonType and mediaPlayPauseButtonFrame for a system-provided play/pause button.

class MediaNotificationViewController: UIViewController, UNNotificationContentExtension {
    var player: AVPlayer?

    override var mediaPlayPauseButtonType: UNNotificationContentExtensionMediaPlayPauseButtonType {
        return .overlay  // .none, .default, .overlay
    }

    override var mediaPlayPauseButtonFrame: CGRect {
        return CGRect(x: 0, y: 0, width: view.bounds.width, height: view.bounds.height)
    }

    func mediaPlay() {
        player?.play()
    }

    func mediaPause() {
        player?.pause()
    }

    func didReceive(_ notification: UNNotification) {
        guard let attachment = notification.request.content.attachments.first,
              attachment.url.startAccessingSecurityScopedResource() else { return }

        let playerItem = AVPlayerItem(url: attachment.url)
        player = AVPlayer(playerItem: playerItem)

        let playerLayer = AVPlayerLayer(player: player)
        playerLayer.frame = view.bounds
        view.layer.addSublayer(playerLayer)
    }
}

Interactive Custom UI

With UNNotificationExtensionUserInteractionEnabled set to true, the content extension supports gesture recognizers, buttons, and other interactive elements.

class InteractiveNotificationViewController: UIViewController, UNNotificationContentExtension {
    private var ratingStars: [UIButton] = []
    private var selectedRating = 0

    override func viewDidLoad() {
        super.viewDidLoad()
        setupRatingUI()
    }

    func didReceive(_ notification: UNNotification) {
        // Configure with notification content
    }

    private func setupRatingUI() {
        let stack = UIStackView()
        stack.axis = .horizontal
        stack.spacing = 8
        stack.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(stack)

        for i in 1...5 {
            let button = UIButton(type: .system)
            button.setImage(UIImage(systemName: "star"), for: .normal)
            button.tag = i
            button.addTarget(self, action: #selector(starTapped(_:)), for: .touchUpInside)
            stack.addArrangedSubview(button)
            ratingStars.append(button)
        }

        NSLayoutConstraint.activate([
            stack.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            stack.centerYAnchor.constraint(equalTo: view.centerYAnchor),
        ])
    }

    @objc private func starTapped(_ sender: UIButton) {
        selectedRating = sender.tag
        for (index, button) in ratingStars.enumerated() {
            let imageName = index < selectedRating ? "star.fill" : "star"
            button.setImage(UIImage(systemName: imageName), for: .normal)
        }
        // Send rating to server
        Task {
            await submitRating(selectedRating)
        }
    }
}

Communication Notifications

Communication notifications display the sender's avatar and name prominently. They use SiriKit intents (INSendMessageIntent or INStartCallIntent) to provide participant information and can have different Focus and summary behavior, so use them only for real person-to-person communication.

Setup

1. Enable the Communication Notifications capability on the app target. 2. Add supported intent class names, such as INSendMessageIntent, to NSUserActivityTypes in Info.plist. 3. Add the Intents framework to the Notification Service Extension target. 4. Configure an INSendMessageIntent, create an INInteraction, set direction = .incoming, donate the interaction, then call content.updating(from:) before passing the updated content to the content handler.

import Intents
import UserNotifications

extension NotificationService {
    func configureCommunicationNotification(
        content: UNMutableNotificationContent,
        senderName: String,
        senderImageURL: String?,
        conversationId: String
    ) async -> UNNotificationContent? {
        // Create the sender identity
        let handle = INPersonHandle(value: conversationId, type: .unknown)
        var avatar: INImage? = nil

        // Download sender avatar
        if let urlString = senderImageURL,
           let url = URL(string: urlString) {
            if let (data, _) = try? await URLSession.shared.data(from: url) {
                avatar = INImage(imageData: data)
            }
        }

        let nameComponents = PersonNameComponentsFormatter()
            .personNameComponents(from: senderName)

        let sender = INPerson(
            personHandle: handle,
            nameComponents: nameComponents,
            displayName: senderName,
            image: avatar,
            contactIdentifier: nil,
            customIdentifier: conversationId
        )

        // Create the messaging intent
        let intent = INSendMessageIntent(
            recipients: nil,
            outgoingMessageType: .outgoingMessageText,
            content: content.body,
            speakableGroupName: nil,
            conversationIdentifier: conversationId,
            serviceName: nil,
            sender: sender,
            attachments: nil
        )

        // Donate the interaction so Siri learns about this contact
        let interaction = INInteraction(intent: intent, response: nil)
        interaction.direction = .incoming
        try? await interaction.donate()

        do {
            return try content.updating(from: intent)
        } catch {
            print("Failed to update content with intent: \(error)")
            return nil
        }
    }
}

Handling in the Service Extension

The complete flow integrates communication notifications into the standard service extension:

override func didReceive(
    _ request: UNNotificationRequest,
    withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
) {
    guard let content = request.content.mutableCopy() as? UNMutableNotificationContent else {
        contentHandler(request.content)
        return
    }

    Task {
        // Download and attach image
        if let imageUrl = content.userInfo["imageUrl"] as? String {
            await attachImage(from: imageUrl, to: content)
        }

        // Configure as communication notification if sender info is present
        if let senderName = content.userInfo["senderName"] as? String,
           let conversationId = content.userInfo["conversationId"] as? String {
            let senderImage = content.userInfo["senderImageUrl"] as? String

            let handle = INPersonHandle(value: conversationId, type: .unknown)
            var avatar: INImage? = nil
            if let urlString = senderImage,
               let url = URL(string: urlString),
               let (data, _) = try? await URLSession.shared.data(from: url) {
                avatar = INImage(imageData: data)
            }

            let nameComponents = PersonNameComponentsFormatter()
                .personNameComponents(from: senderName)

            let sender = INPerson(
                personHandle: handle,
                nameComponents: nameComponents,
                displayName: senderName,
                image: avatar,
                contactIdentifier: nil,
                customIdentifier: conversationId
            )

            let intent = INSendMessageIntent(
                recipients: nil,
                outgoingMessageType: .outgoingMessageText,
                content: content.body,
                speakableGroupName: nil,
                conversationIdentifier: conversationId,
                serviceName: nil,
                sender: sender,
                attachments: nil
            )

            let interaction = INInteraction(intent: intent, response: nil)
            interaction.direction = .incoming
            try? await interaction.donate()

            if let updatedContent = try? content.updating(from: intent) {
                contentHandler(updatedContent)
                return
            }
        }

        contentHandler(content)
    }
}

Extension Gotchas

Service extension not running:

• Verify mutable-content: 1 is set in the APNs payload.
• The notification must have an alert (title or body). Silent pushes do not trigger the service extension.
• Confirm the service extension target is embedded in the containing app and its bundle identifier/provisioning profile are valid.
• Confirm both targets include the same App Group or Keychain Sharing entitlements if they share data.

Content extension not showing:

• Verify the UNNotificationExtensionCategory in Info.plist matches the categoryIdentifier in the notification.
• Check that the storyboard or programmatic UI is properly configured.
• Ensure UNNotificationExtensionInitialContentSizeRatio is set to a reasonable value.

Memory pressure:

• Extensions are memory-constrained and can be terminated under pressure.
• Avoid loading large frameworks (no SwiftUI, no heavy networking libraries).
• Use URLSession directly for network requests in extensions.

Fallback handling:

• Always call the content handler exactly once on every path.
• On download, decryption, donation, or content.updating(from:) failure, return the original or best-attempt content rather than dropping the notification.
• In serviceExtensionTimeWillExpire(), stop waiting for in-flight work and call the content handler immediately with the best content available.

Network access in extensions:

• Extensions can make network requests. Use URLSession with the .default configuration.
• Keep requests fast -- the service extension has approximately 30 seconds total.
• Handle network failures gracefully; fall back to showing what the original payload contains.

Debugging extensions:

• In Xcode, select the extension scheme and attach to the extension process.
• Use Debug > Attach to Process by PID or Name with the extension's process name.
• Use os_log or print statements and view them in Console.app filtered by the extension's bundle identifier.
• Set breakpoints in the extension target and trigger a notification to hit them.

Complete Service Extension Example

A production-ready service extension that handles image download, body decryption, and communication notifications:

import UserNotifications
import Intents

class NotificationService: UNNotificationServiceExtension {
    private var contentHandler: ((UNNotificationContent) -> Void)?
    private var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        self.contentHandler = contentHandler
        bestAttemptContent = request.content.mutableCopy() as? UNMutableNotificationContent

        guard let content = bestAttemptContent else {
            contentHandler(request.content)
            return
        }

        Task {
            // Step 1: Decrypt body if needed
            if let encrypted = content.userInfo["encryptedBody"] as? String,
               let decrypted = decryptBody(encrypted) {
                content.body = decrypted
            }

            // Step 2: Download and attach image
            if let imageUrl = content.userInfo["imageUrl"] as? String {
                await attachMedia(from: imageUrl, to: content)
            }

            // Step 3: Configure communication notification
            if let senderName = content.userInfo["senderName"] as? String,
               let convId = content.userInfo["conversationId"] as? String {
                if let updated = await configureAsCommunication(
                    content: content,
                    senderName: senderName,
                    senderImageURL: content.userInfo["senderImage"] as? String,
                    conversationId: convId
                ) {
                    finish(with: updated)
                    return
                }
            }

            finish(with: content)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        if let content = bestAttemptContent {
            finish(with: content)
        }
    }

    // MARK: - Private

    private func finish(with content: UNNotificationContent) {
        guard !didComplete, let handler = contentHandler else { return }
        didComplete = true
        handler(content)
    }

    private func decryptBody(_ base64: String) -> String? {
        guard let data = Data(base64Encoded: base64) else { return nil }
        guard let keyData = SharedKeychain.loadData(
            account: "notificationEncryptionKey"
        ) else { return nil }
        // Decrypt using CryptoKit or similar
        return try? Decryptor.decrypt(data, key: keyData)
    }

    private func attachMedia(
        from urlString: String,
        to content: UNMutableNotificationContent
    ) async {
        guard let url = URL(string: urlString) else { return }
        do {
            let (data, response) = try await URLSession.shared.data(from: url)
            let ext = fileExtension(for: response.mimeType)
            let fileURL = FileManager.default.temporaryDirectory
                .appendingPathComponent(UUID().uuidString + ext)
            try data.write(to: fileURL)
            let attachment = try UNNotificationAttachment(
                identifier: UUID().uuidString,
                url: fileURL,
                options: nil
            )
            content.attachments = [attachment]
        } catch {
            // Image download failed -- notification displays without media
        }
    }

    private func configureAsCommunication(
        content: UNMutableNotificationContent,
        senderName: String,
        senderImageURL: String?,
        conversationId: String
    ) async -> UNNotificationContent? {
        let handle = INPersonHandle(value: conversationId, type: .unknown)
        var avatar: INImage? = nil

        if let urlStr = senderImageURL,
           let url = URL(string: urlStr),
           let (data, _) = try? await URLSession.shared.data(from: url) {
            avatar = INImage(imageData: data)
        }

        let nameComponents = PersonNameComponentsFormatter()
            .personNameComponents(from: senderName)

        let sender = INPerson(
            personHandle: handle,
            nameComponents: nameComponents,
            displayName: senderName,
            image: avatar,
            contactIdentifier: nil,
            customIdentifier: conversationId
        )

        let intent = INSendMessageIntent(
            recipients: nil,
            outgoingMessageType: .outgoingMessageText,
            content: content.body,
            speakableGroupName: nil,
            conversationIdentifier: conversationId,
            serviceName: nil,
            sender: sender,
            attachments: nil
        )

        let interaction = INInteraction(intent: intent, response: nil)
        interaction.direction = .incoming
        try? await interaction.donate()

        return try? content.updating(from: intent)
    }

    private func fileExtension(for mimeType: String?) -> String {
        switch mimeType {
        case "image/jpeg": return ".jpg"
        case "image/png": return ".png"
        case "image/gif": return ".gif"
        case "video/mp4": return ".mp4"
        case "audio/mpeg": return ".mp3"
        default: return ".jpg"
        }
    }
}