Push Notifications — Expert Decisions

Expert decision frameworks for notification choices. Claude knows UNUserNotificationCenter and APNs — this skill provides judgment calls for permission timing, delivery strategies, and architecture trade-offs.

Decision Trees

Permission Request Timing

When should you ask for notification permission? ├─ User explicitly wants notifications │ └─ After user taps "Enable Notifications" button │ Highest acceptance rate (70-80%) │ ├─ After demonstrating value │ └─ After user completes key action │ "Get notified when your order ships?" │ Context-specific, 50-60% acceptance │ ├─ First meaningful moment │ └─ After onboarding, before home screen │ Explain why, 30-40% acceptance │ └─ On app launch └─ AVOID — lowest acceptance (15-20%) No context, feels intrusive

The trap: Requesting permission on first launch. Users deny reflexively. Wait for a moment when notifications clearly add value.

Silent vs Visible Notification

What's the notification purpose? ├─ Background data sync │ └─ Silent notification (content-available: 1) │ No user interruption, wakes app │ ├─ User needs to know immediately │ └─ Visible alert │ Messages, time-sensitive info │ ├─ Informational, not urgent │ └─ Badge + silent │ User sees count, checks when ready │ └─ Needs user action └─ Visible with actions Reply, accept/decline buttons

Notification Extension Strategy

Do you need to modify notifications? ├─ Download images/media │ └─ Notification Service Extension │ mutable-content: 1 in payload │ ├─ Decrypt end-to-end encrypted content │ └─ Notification Service Extension │ Required for E2EE messaging │ ├─ Custom notification UI │ └─ Notification Content Extension │ Long-press/3D Touch custom view │ └─ Standard text/badge └─ No extension needed Less complexity, faster delivery

Token Management

How should you handle device tokens? ├─ Single device per user │ └─ Replace token on registration │ Simple, most apps need this │ ├─ Multiple devices per user │ └─ Register all tokens │ Send to all active devices │ ├─ Token changed (reinstall/restore) │ └─ Deduplicate on server │ Same device, new token │ └─ User logged out └─ Deregister token from user Prevents notifications to wrong user

NEVER Do

Permission Handling

NEVER request permission without context:

// ❌ First thing on app launch — user denies func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .badge, .sound]) { _, _ in } return true }

// ✅ After user action that demonstrates value func userTappedEnableNotifications() { showPrePermissionExplanation { Task { let granted = try? await UNUserNotificationCenter.current() .requestAuthorization(options: [.alert, .badge, .sound]) if granted == true { await MainActor.run { registerForRemoteNotifications() } } } } }

NEVER ignore denied permission:

// ❌ Keeps trying, annoys user func checkNotifications() { Task { let settings = await UNUserNotificationCenter.current().notificationSettings() if settings.authorizationStatus == .denied { // Ask again! <- User already said no requestPermission() } } }

// ✅ Respect denial, offer settings path func checkNotifications() { Task { let settings = await UNUserNotificationCenter.current().notificationSettings() switch settings.authorizationStatus { case .denied: showSettingsPrompt() // "Enable in Settings to receive..." case .notDetermined: showPrePermissionScreen() case .authorized, .provisional, .ephemeral: ensureRegistered() @unknown default: break } } }

Token Handling

NEVER cache device tokens long-term in app:

// ❌ Token may change without app knowing class TokenManager { static var cachedToken: String? // Stale after reinstall!

func getToken() -> String? {
    return Self.cachedToken  // May be invalid
}

}

// ✅ Always use fresh token from registration callback func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) { let token = deviceToken.hexString

// Send to server immediately — this is the source of truth
Task {
    await sendTokenToServer(token)
}

}

NEVER assume token format:

// ❌ Token format is not guaranteed let tokenString = String(data: deviceToken, encoding: .utf8) // Returns nil!

// ✅ Convert bytes to hex extension Data { var hexString: String { map { String(format: "%02x", $0) }.joined() } }

let tokenString = deviceToken.hexString

Silent Notifications

NEVER rely on silent notifications for time-critical delivery:

// ❌ Silent notifications are low priority // Server sends: {"aps": {"content-available": 1}} // Expecting: Immediate delivery // Reality: iOS may delay minutes/hours or drop entirely

// ✅ Use visible notification for time-critical content // Or use silent for prefetch, visible for alert { "aps": { "alert": {"title": "New Message", "body": "..."}, "content-available": 1 // Also prefetch in background } }

NEVER do heavy work in silent notification handler:

// ❌ System will kill your app func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async -> UIBackgroundFetchResult {

await downloadLargeFiles()  // Takes too long!
await processAllData()       // iOS terminates app

return .newData

}

// ✅ Quick fetch, defer heavy processing func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any]) async -> UIBackgroundFetchResult {

// 30 seconds max — fetch metadata only
do {
    let hasNew = try await checkForNewContent()
    if hasNew {
        scheduleBackgroundProcessing()  // BGProcessingTask
    }
    return hasNew ? .newData : .noData
} catch {
    return .failed
}

}

Notification Service Extension

NEVER forget expiration handler:

// ❌ System shows unmodified notification class NotificationService: UNNotificationServiceExtension { override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {

    // Start async work...
    downloadImage { image in
        // Never called if timeout!
        contentHandler(modifiedContent)
    }
}

// Missing serviceExtensionTimeWillExpire!

}

// ✅ Always implement expiration handler class NotificationService: UNNotificationServiceExtension { var contentHandler: ((UNNotificationContent) -> Void)? var bestAttemptContent: UNMutableNotificationContent?

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

    downloadImage { [weak self] image in
        guard let self, let content = self.bestAttemptContent else { return }
        if let image { content.attachments = [image] }
        contentHandler(content)
    }
}

override func serviceExtensionTimeWillExpire() {
    // Called ~30 seconds — deliver what you have
    if let content = bestAttemptContent {
        contentHandler?(content)
    }
}

}

Essential Patterns

Permission Flow with Pre-Permission

@MainActor final class NotificationPermissionManager: ObservableObject { @Published var status: UNAuthorizationStatus = .notDetermined

func checkStatus() async {
    let settings = await UNUserNotificationCenter.current().notificationSettings()
    status = settings.authorizationStatus
}

func requestPermission() async -> Bool {
    do {
        let granted = try await UNUserNotificationCenter.current()
            .requestAuthorization(options: [.alert, .badge, .sound])

        if granted {
            UIApplication.shared.registerForRemoteNotifications()
        }

        await checkStatus()
        return granted
    } catch {
        return false
    }
}

func openSettings() {
    guard let url = URL(string: UIApplication.openSettingsURLString) else { return }
    UIApplication.shared.open(url)
}

}

// Pre-permission screen struct NotificationPermissionView: View { @StateObject private var manager = NotificationPermissionManager() @State private var showSystemPrompt = false

var body: some View {
    VStack(spacing: 24) {
        Image(systemName: "bell.badge")
            .font(.system(size: 60))

        Text("Stay Updated")
            .font(.title)

        Text("Get notified about new messages, order updates, and important alerts.")
            .multilineTextAlignment(.center)

        Button("Enable Notifications") {
            Task { await manager.requestPermission() }
        }
        .buttonStyle(.borderedProminent)

        Button("Not Now") { dismiss() }
            .foregroundColor(.secondary)
    }
    .padding()
}

}

Notification Action Handler

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

private let router: DeepLinkRouter

func userNotificationCenter(_ center: UNUserNotificationCenter,
    willPresent notification: UNNotification) async -> UNNotificationPresentationOptions {
    // App is in foreground
    let userInfo = notification.request.content.userInfo

    // Check if we should show banner or handle silently
    if shouldShowInForeground(userInfo) {
        return [.banner, .sound, .badge]
    } else {
        handleSilently(userInfo)
        return []
    }
}

func userNotificationCenter(_ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse) async {
    let userInfo = response.notification.request.content.userInfo

    switch response.actionIdentifier {
    case UNNotificationDefaultActionIdentifier:
        // User tapped notification
        await handleNotificationTap(userInfo)

    case "REPLY_ACTION":
        if let textResponse = response as? UNTextInputNotificationResponse {
            await handleReply(text: textResponse.userText, userInfo: userInfo)
        }

    case "MARK_READ_ACTION":
        await markAsRead(userInfo)

    case UNNotificationDismissActionIdentifier:
        // User dismissed
        break

    default:
        await handleCustomAction(response.actionIdentifier, userInfo: userInfo)
    }
}

private func handleNotificationTap(_ userInfo: [AnyHashable: Any]) async {
    guard let deepLink = userInfo["deep_link"] as? String,
          let url = URL(string: deepLink) else { return }

    await router.navigate(to: url)
}

}

Rich Notification Service

class NotificationService: UNNotificationServiceExtension { var contentHandler: ((UNNotificationContent) -> Void)? 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 {
        // Download and attach media
        if let mediaURL = request.content.userInfo["media_url"] as? String {
            if let attachment = await downloadAttachment(from: mediaURL) {
                content.attachments = [attachment]
            }
        }

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

        contentHandler(content)
    }
}

override func serviceExtensionTimeWillExpire() {
    if let content = bestAttemptContent {
        contentHandler?(content)
    }
}

private func downloadAttachment(from urlString: String) async -> UNNotificationAttachment? {
    guard let url = URL(string: urlString) else { return nil }

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

        let fileExtension = (response as? HTTPURLResponse)?
            .mimeType.flatMap { mimeToExtension[$0] } ?? "jpg"

        let destURL = FileManager.default.temporaryDirectory
            .appendingPathComponent(UUID().uuidString)
            .appendingPathExtension(fileExtension)

        try FileManager.default.moveItem(at: localURL, to: destURL)

        return try UNNotificationAttachment(identifier: "media", url: destURL)
    } catch {
        return nil
    }
}

}

Quick Reference

Payload Structure

Field Purpose Value

alert Visible notification {title, subtitle, body}

badge App icon badge Number

sound Notification sound "default" or filename

content-available Silent/background 1

mutable-content Service extension 1

category Action buttons Category identifier

thread-id Notification grouping Thread identifier

Permission States

Status Meaning Action

notDetermined Never asked Show pre-permission

denied User declined Show settings prompt

authorized Full access Register for remote

provisional Quiet delivery Consider upgrade prompt

ephemeral App clip temporary Limited time

Extension Limits

Extension Time Limit Use Case

Service Extension ~30 seconds Download media, decrypt

Content Extension User interaction Custom UI

Background fetch ~30 seconds Data refresh

Red Flags

Smell Problem Fix

Permission on launch Low acceptance Wait for user action

Cached device token May be stale Always use callback

String(data:encoding:) for token Returns nil Use hex encoding

Silent for time-critical May be delayed Use visible notification

Heavy work in silent handler App terminated Quick fetch, defer work

No serviceExtensionTimeWillExpire Unmodified content shown Always implement

Ignoring denied status Frustrates user Offer settings path