/push-notifications

name: push-notifications
description: Generate push notification infrastructure with APNs registration, handling, and rich notifications. Use when adding push notifications, configuring APNs, notification categories/actions, or rich notifications with images and custom UI.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27

Push Notifications Generator

Generate push notification infrastructure with APNs registration, handling, and rich notifications.

When This Skill Activates

• User wants to add push notifications to their app
• User mentions APNs (Apple Push Notification service)
• User asks about notification categories or actions
• User wants rich notifications with images or custom UI

Pre-Generation Checks

Before generating, verify:

1. **Existing Notification Code**

   # Check for existing notification handling
   grep -r "UNUserNotificationCenter\|registerForRemoteNotifications" --include="*.swift" | head -5

2. **Entitlements**

   # Check for push notification entitlement
   find . -name "*.entitlements" -exec grep -l "aps-environment" {} \;

3. **App Delegate or SwiftUI App**

   # Determine app structure
   grep -r "@main\|UIApplicationDelegate" --include="*.swift" | head -5

Configuration Questions

1. Notification Types

• **Basic** - Simple alerts with title/body
• **Rich** - Include images, custom UI (requires Notification Service Extension)
• **Both** - Full notification support

2. Notification Actions

• **None** - Just display notifications
• **Simple Actions** - Quick action buttons
• **Custom Categories** - Multiple action categories

3. Silent Notifications

• **Yes** - Background data updates
• **No** - User-visible only

Generated Files

Core Infrastructure

Sources/Notifications/
├── NotificationManager.swift      # Central notification management
├── NotificationDelegate.swift     # UNUserNotificationCenterDelegate
├── NotificationCategories.swift   # Action categories definition
└── NotificationPayload.swift      # Type-safe payload parsing

Rich Notifications (Optional)

NotificationServiceExtension/
├── NotificationService.swift      # Modify notifications before display
└── Info.plist                     # Extension configuration

Content Extension (Optional)

NotificationContentExtension/
├── NotificationViewController.swift  # Custom notification UI
├── MainInterface.storyboard
└── Info.plist

Key Features

Registration Flow

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

    func requestAuthorization() async throws -> Bool {
        let center = UNUserNotificationCenter.current()
        let options: UNAuthorizationOptions = [.alert, .badge, .sound]
        return try await center.requestAuthorization(options: options)
    }

    func registerForRemoteNotifications() {
        UIApplication.shared.registerForRemoteNotifications()
    }
}

Handling Notifications

// Foreground notification
func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    willPresent notification: UNNotification
) async -> UNNotificationPresentationOptions {
    return [.banner, .sound, .badge]
}

// Notification tap/action
func userNotificationCenter(
    _ center: UNUserNotificationCenter,
    didReceive response: UNNotificationResponse
) async {
    let userInfo = response.notification.request.content.userInfo
    await handleNotificationAction(response.actionIdentifier, userInfo: userInfo)
}

Action Categories

enum NotificationCategory: String {
    case message = "MESSAGE_CATEGORY"
    case reminder = "REMINDER_CATEGORY"

    var actions: [UNNotificationAction] {
        switch self {
        case .message:
            return [
                UNNotificationAction(identifier: "REPLY", title: "Reply", options: []),
                UNNotificationAction(identifier: "MARK_READ", title: "Mark as Read", options: [])
            ]
        case .reminder:
            return [
                UNNotificationAction(identifier: "COMPLETE", title: "Complete", options: []),
                UNNotificationAction(identifier: "SNOOZE", title: "Snooze", options: [])
            ]
        }
    }
}

Notification Design (WWDC18)

"Interrupting people is a real privilege… a trust relationship." Design the strategy before the infrastructure:

| Decision | Rule | |----------|------| | Authorization | Use **provisional authorization** (add `.provisional` to the options — delivered quietly to Notification Center, no prompt) for passive content like likes and comments; reserve the explicit prompt for **time-critical** content | | When to prompt | **Never at first launch.** Explain the value first, then ask at a contextually meaningful moment — right after the order is placed, not before the user has ordered | | Content bar | Every notification carries a **specific message or a completable task** — never an empty "open the app" nudge | | Timing | Deliver at relevant times; use time- and location-based delivery where it fits | | Settings | Offer **granular per-topic toggles in-app**, and add `.providesAppNotificationSettings` so "Manage" in system settings deep-links to your page | | Grouping | App-level grouping is the default; set `threadIdentifier` **only for meaningfully different streams** (conversations, distinct sources) — over-threading recreates the clutter grouping was meant to fix | | Rich content | A rich notification is a **self-contained package**: image/video plus actions that complete the task without launching the app | | Fatigue | **Pause notification types a user repeatedly ignores** (the Duolingo pattern) — silence beats an uninstall |

Required Capabilities

In Xcode

1. Select project target 2. Signing & Capabilities tab 3. Add "Push Notifications"