macos-notifications

macOS Notifications

Notify only when the user benefits from being pulled back — task finished, task failed, something needs their decision — and make every notification click land on the exact screen that resolves it.

When to use

Use this skill when the user says:

• notify when done / notification when the task finishes
• desktop notification / system notification
• UNUserNotificationCenter / UserNotifications
• notification permission
• notification actions / buttons
• clicking the notification should open …
• background job finished, tell the user
• reminder from a macOS app

Do not use this skill for push/APNs server setup, iOS-specific notification UI, or in-window status banners (those are in-app feedback — see apple-hig-feedback-status).

Core rule

Notify only when being pulled back saves the user something.
Every notification answers: what happened, and what happens
when I click it.

When to notify — and when not

Worth a notification (the app is likely in the background):

Completed     long task finished        → click opens the result
Failed        long task failed          → click opens the error + retry
Blocked       waiting on input/approval → click opens the decision
Needs review  output ready to check     → click opens the review view
Reminder      user-scheduled            → click opens the item

Not worth one:

• Progress ticks, intermediate states, "still working…"
• Anything the user is currently looking at (foreground, same screen)
• Marketing, tips, "did you know" — never
• Errors the app can recover from by itself

If the app fires more than a handful of notifications an hour, the model is wrong — batch them (one summary notification) or drop the low-value ones.

Permission

Request at the moment of need, with context, never at first launch:

import UserNotifications

enum Notifier {
    // Call right after the user does the thing that will later notify —
    // e.g. starts their first long-running task.
    static func requestPermission() async -> Bool {
        let center = UNUserNotificationCenter.current()
        do {
            return try await center.requestAuthorization(options: [.alert, .sound, .badge])
        } catch {
            return false
        }
    }

    // Never assume — settings can change behind the app's back.
    static func isAuthorized() async -> Bool {
        let settings = await UNUserNotificationCenter.current().notificationSettings()
        return settings.authorizationStatus == .authorized
                || settings.authorizationStatus == .provisional
    }
}