Push Notifications

Implement, review, and debug local and remote notifications with UserNotifications and APNs. Target the project's deployment range; examples assume modern Swift concurrency and note availability when using newer APIs.

Keep adjacent domains separate: Live Activity content-state pushes belong to activitykit; PushKit/VoIP calls to callkit; App Clip ephemeral setup to app-clips; long-running or scheduled background work to background-processing.

Contents

• Route by task
• Core workflow
• Authorization and APNs registration
• Payload and delivery contracts
• Runtime handling and routing
• Categories and actions
• Correction reviews
• Common mistakes
• Review checklist

Route by task

Read only the references needed for the request:

• For notification authorization, APNs registration, token lifecycle, provider headers, visible/background payloads, or delivery diagnosis, read APNs lifecycle and remote delivery.
• For time, calendar, or location reminders scheduled on-device, read local notifications.
• For complete application-delegate wiring, foreground/tap handling, deep-link routing, and categories, read notification runtime and routing.
• For .apns, simctl, APNs Sandbox Simulator coverage, provider/device matrices, or delivery diagnosis, read notification delivery testing.
• For service-extension mutation and exactly-once completion, read service extensions.
• For custom expanded UI, read content extensions; for Messages-style presentation, read communication notifications.
• For the focused reference index, read notification patterns or rich notifications. Use complete notification patterns and complete rich-notification recipes only for broad end-to-end examples or migration.

Do not read every reference for a narrow task. Keep the response scoped to the failed or requested delivery path.

Core workflow

1. Classify the notification as local, visible remote, background remote, Live Activity, VoIP, or extension-modified.
2. Inspect entitlements, capabilities, bundle/topic, delegate installation, categories, provider ownership, and target platform.
3. Separate visible authorization from APNs registration and server token binding.
4. Define payload keys, APNs headers, expiry/collapse behavior, and sensitive-data policy.
5. Implement foreground presentation, response/action routing, and bounded background or extension work.
6. Verify each boundary independently: scheduling/provider acceptance, device receipt, extension execution, presentation, and response routing.

Authorization and APNs registration

Notification authorization controls user-visible alerts, sounds, and badges. Request it in context and check notificationSettings() because the user can change settings later.

APNs registration is a separate path. Call registerForRemoteNotifications() whenever a device token is needed, including server binding or background delivery. Do not gate it on .authorized.

Receive tokens through application-delegate callbacks. Treat token data as opaque, convert it to hex for transport, and upload on every successful callback. Do not assume a fixed length or treat a locally cached token as provider truth.

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let token = deviceToken.map { String(format: "%02x", $0) }.joined()
    Task { await tokenService.upload(token) }
}

On supported current Xcode/OS hosts, iOS Simulator can register with the APNs Sandbox and receives a simulator-specific, variable-length token. Provider delivery to that Simulator is useful for sandbox end-to-end checks. .apns files and simctl push simulate delivery without exercising the provider path; host/CI support varies. Verify production entitlements, signing, and hardware-specific behavior on a physical device.

Payload and delivery contracts

Put Apple keys inside aps and minimal app routing identifiers beside it. Treat payload data as untrusted: validate identity/authorization against current app or server state before navigation or mutation. Avoid sensitive plaintext.

Background pushes are hints to fetch current state, not a timer. Enable Background Modes > Remote notifications, perform bounded work, and return the correct UIBackgroundFetchResult. Route BGTaskScheduler design to background-processing.

Runtime handling and routing

Set UNUserNotificationCenter.current().delegate during launch, before responses can arrive.

@MainActor
final class NotificationDelegate: NSObject, UNUserNotificationCenterDelegate {
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification
    ) async -> UNNotificationPresentationOptions {
        [.banner, .list, .sound, .badge]
    }

    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse
    ) async {
        await notificationRouter.handle(response)
    }
}

Keep payload parsing in a testable boundary. Hand a validated destination or intent to the app's existing navigation/state owner; notification delegates should not create a competing navigation architecture.

Foreground receipt does not automatically show UI. Return only the presentation options the product wants. Handle body taps, dismiss callbacks when registered, and custom action identifiers deliberately.

Categories and actions

Register categories during launch. Payload category and local categoryIdentifier values must exactly match the registered identifier.

Choose action options from behavior:

• .foreground launches the app for UI work;
• .authenticationRequired protects sensitive actions until unlock;
• .destructive communicates irreversible intent;
• UNTextInputNotificationAction supports inline text response.

Validate identifiers in userInfo again before calling services. Define idempotency for actions the system or user may invoke more than once.

Correction reviews

For flawed designs, name the violated contract rather than only showing replacement code:

• Registration gated by alert permission: separate authorization and token registration.
• Token cached to skip provider upload: upload on every callback and let the provider reconcile.
• Frequent priority-10 silent pushes: use background payload/headers and state that delivery is throttled and not guaranteed.
• Service extension triggered by silent push: require alert content plus mutable-content: 1.
• Extension secrets in App Group defaults: use Keychain Sharing for secrets; App Groups for shared files/defaults.
• Attachment from arbitrary remote URL: download a supported file to disk, then construct UNNotificationAttachment.
• Extension missing fallback: call the content handler exactly once on success, failure, and serviceExtensionTimeWillExpire().

Common mistakes

• Setting the center delegate after launch or inside a transient SwiftUI view.
• Treating a missing banner as proof that APNs didn't deliver.
• Assuming background delivery is immediate or periodic.
• Converting device token data as UTF-8 or assuming token length.
• Doing unbounded network work in a background callback or extension.
• Putting authorization state, secrets, or trusted navigation decisions in payload data.
• Using removeAll… for a feature that doesn't own every app notification.
• Mixing Live Activity, VoIP, and ordinary alert payload rules.

Review checklist

• Notification path and sibling-skill boundary are explicit.
• Visible authorization is requested in context and current settings are respected.
• APNs registration is not incorrectly gated by visible authorization.
• Token is treated as opaque and uploaded on every registration callback.
• Provider push type, priority, topic, expiration, and payload match the path.
• Delegate and categories are installed during launch.
• Foreground presentation, taps, dismissals, and custom actions follow product policy.
• Background or extension work is bounded and completes through every path.
• Payload identifiers are validated before navigation or mutation.
• Local requests have stable ownership, update, and cancellation semantics.
• Simulator limitations and physical-device verification are distinguished.
• Delivery evidence covers the actual provider/device/app boundary that changed.

Official references

• UserNotifications
• Registering your app with APNs
• Generating a remote notification
• UNUserNotificationCenterDelegate