# 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](#complete-appdelegate-adaptor-setup)
- [Full UNUserNotificationCenterDelegate](#full-unusernotificationcenterdelegate)
- [Deep Link Router](#deep-link-router)
- [Silent Push Handler](#silent-push-handler)
- [Notification Scheduling Manager](#notification-scheduling-manager)
- [Token Refresh and Update Flow](#token-refresh-and-update-flow)
- [Category Registration](#category-registration)
- [Testing Notifications](#testing-notifications)
- [Badge Management](#badge-management)
- [Provisional to Full Authorization Upgrade](#provisional-to-full-authorization-upgrade)

## Complete AppDelegate Adaptor Setup

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

```swift
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

```swift
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

```swift
@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.

```swift
@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.

```swift
@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.

```swift
@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.

```swift
@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.

```swift
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:

```json
{
    "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:

```bash
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:**

| Status | Meaning | Action |
|--------|---------|--------|
| 200 | Success | Notification accepted by APNs |
| 400 | Bad request | Check payload format (max 4096 bytes) |
| 403 | Forbidden | Certificate/key mismatch or expired |
| 405 | Method not allowed | Must use POST with HTTP/2 |
| 410 | Gone | Device token is no longer valid; remove from server |
| 413 | Payload too large | Reduce payload size (max 4096 bytes) |
| 429 | Too many requests | APNs is throttling; back off |
| 500 | Internal server error | APNs issue; retry later |

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.

```swift
// 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.

```swift
@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
    }
}
```