charleswiltgen/axiom-push-notifications-ref

Push Notifications API Reference

Comprehensive API reference for APNs HTTP/2 transport, UserNotifications framework, and push-driven features including Live Activities and broadcast push.

Quick Reference

// AppDelegate — minimal remote notification setup
class AppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        UNUserNotificationCenter.current().delegate = self
        return true
    }

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

    func application(_ application: UIApplication,
                     didFailToRegisterForRemoteNotificationsWithError error: Error) {
        print("Registration failed: \(error)")
    }

    // Show notifications when app is in foreground
    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                willPresent notification: UNNotification) async -> UNNotificationPresentationOptions {
        return [.banner, .sound, .badge]
    }

    // Handle notification tap / action response
    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                didReceive response: UNNotificationResponse) async {
        let userInfo = response.notification.request.content.userInfo
        // Route to appropriate screen based on userInfo
    }
}

---

APNs Transport Reference

Endpoints

| Environment | Host | Port | |-------------|------|------| | Development | api.sandbox.push.apple.com | 443 or 2197 | | Production | api.push.apple.com | 443 or 2197 |

Request Format

POST /3/device/{device_token}
Host: api.push.apple.com
Authorization: bearer {jwt_token}
apns-topic: {bundle_id}
apns-push-type: alert
Content-Type: application/json

APNs Headers

| Header | Required | Values | Notes | |--------|----------|--------|-------| | apns-push-type | Yes | alert, background, liveactivity, voip, complication, fileprovider, mdm, location | Must match payload content | | apns-topic | Yes | Bundle ID (or .push-type.liveactivity suffix) | Required for token-based auth | | apns-priority | No | 10 (immediate), 5 (power-conscious), 1 (low) | Default: 10 for alert, 5 for background | | apns-expiration | No | UNIX timestamp or 0 | 0 = deliver once, don't store | | apns-collapse-id | No | String ≤64 bytes | Replaces matching notification on device | | apns-id | No | UUID (lowercase) | Returned by APNs for tracking | | authorization | Token auth | bearer {JWT} | Not needed for certificate auth | | apns-unique-id | Response only | UUID | Use with Push Notifications Console delivery log |

Response Codes

| Status | Meaning | Common Cause | |--------|---------|--------------| | 200 | Success | | | 400 | Bad request | Malformed JSON, missing required header | | 403 | Forbidden | Expired JWT, wrong team/key, topic mismatch | | 404 | Not found | Invalid device token path | | 405 | Method not allowed | Not using POST | | 410 | Unregistered | Device token no longer active (app uninstalled) | | 413 | Payload too large | Exceeds 4KB (5KB for VoIP) | | 429 | Too many requests | Rate limited by APNs | | 500 | Internal server error | APNs issue, retry | | 503 | Service unavailable | APNs overloaded, retry with backoff |

---

JWT Authentication Reference

JWT Header

{ "alg": "ES256", "kid": "{10-char Key ID}" }

JWT Claims

{ "iss": "{10-char Team ID}", "iat": {unix_timestamp} }

Rules

| Rule | Detail | |------|--------| | Algorithm | ES256 (P-256 curve) | | Signing key | APNs auth key (.p8 from developer portal) | | Token lifetime | Max 1 hour (403 ExpiredProviderToken if older) | | Refresh interval | Between 20 and 60 minutes | | Scope | One key works for all apps in team, both environments |

Authorization Header Format

authorization: bearer eyAia2lkIjog...

---

Payload Reference

aps Dictionary Keys

| Key | Type | Purpose | Since | |-----|------|---------|-------| | alert | Dict/String | Alert content | iOS 10 | | badge | Number | App icon badge (0 removes) | iOS 10 | | sound | String/Dict | Audio playback | iOS 10 | | thread-id | String | Notification grouping | iOS 10 | | category | String | Actionable notification type | iOS 10 | | content-available | Number (1) | Silent background push | iOS 10 | | mutable-content | Number (1) | Triggers service extension | iOS 10 | | target-content-id | String | Window/content identifier | iOS 13 | | interruption-level | String | passive/active/time-sensitive/critical | iOS 15 | | relevance-score | Number 0-1 | Notification summary sorting | iOS 15 | | filter-criteria | String | Focus filter matching | iOS 15 | | stale-date | Number | UNIX timestamp (Live Activity) | iOS 16.1 | | content-state | Dict | Live Activity content update | iOS 16.1 | | timestamp | Number | UNIX timestamp (Live Activity) | iOS 16.1 | | event | String | start/update/end (Live Activity) | iOS 16.1 | | dismissal-date | Number | UNIX timestamp (Live Activity) | iOS 16.1 | | attributes-type | String | Live Activity struct name | iOS 17 | | attributes | Dict | Live Activity init data | iOS 17 |

Alert Dictionary Keys

| Key | Type | Purpose | |-----|------|---------| | title | String | Short title | | subtitle | String | Secondary description | | body | String | Full message | | launch-image | String | Launch screen filename | | title-loc-key | String | Localization key for title | | title-loc-args | [String] | Title format arguments | | subtitle-loc-key | String | Localization key for subtitle | | subtitle-loc-args | [String] | Subtitle format arguments | | loc-key | String | Localization key for body | | loc-args | [String] | Body format arguments |

Sound Dictionary (Critical Alerts)

{ "critical": 1, "name": "alarm.aiff", "volume": 0.8 }

Interruption Level Values

| Value | Behavior | Requires | |-------|----------|----------| | passive | No sound/wake. Notification summary only. | Nothing | | active | Default. Sound + banner. | Nothing | | time-sensitive | Breaks scheduled delivery. Banner persists. | Time Sensitive capability | | critical | Overrides DND and ringer switch. | Apple approval + entitlement |

Example Payloads

Basic Alert

{
    "aps": {
        "alert": {
            "title": "New Message",
            "subtitle": "From Alice",
            "body": "Hey, are you free for lunch?"
        },
        "badge": 3,
        "sound": "default"
    }
}

Localized with loc-key/loc-args

{
    "aps": {
        "alert": {
            "title-loc-key": "MESSAGE_TITLE",
            "title-loc-args": ["Alice"],
            "loc-key": "MESSAGE_BODY",
            "loc-args": ["Alice", "lunch"]
        },
        "sound": "default"
    }
}

Silent Background Push

{
    "aps": {
        "content-available": 1
    },
    "custom-key": "sync-update"
}

Rich Notification (Service Extension)

{
    "aps": {
        "alert": {
            "title": "Photo shared",
            "body": "Alice shared a photo with you"
        },
        "mutable-content": 1,
        "sound": "default"
    },
    "image-url": "https://example.com/photo.jpg"
}

Critical Alert

{
    "aps": {
        "alert": {
            "title": "Server Down",
            "body": "Production database is unreachable"
        },
        "sound": { "critical": 1, "name": "default", "volume": 1.0 },
        "interruption-level": "critical"
    }
}

Time-Sensitive with Category

{
    "aps": {
        "alert": {
            "title": "Package Delivered",
            "body": "Your order has been delivered to the front door"
        },
        "interruption-level": "time-sensitive",
        "category": "DELIVERY",
        "sound": "default"
    },
    "order-id": "12345"
}

---

UNUserNotificationCenter API Reference

Key Methods

| Method | Purpose | |--------|---------| | requestAuthorization(options:) | Request permission | | notificationSettings() | Check current status | | add(:) | Schedule notification request | | getPendingNotificationRequests() | List scheduled | | removePendingNotificationRequests(withIdentifiers:) | Cancel scheduled | | getDeliveredNotifications() | List in notification center | | removeDeliveredNotifications(withIdentifiers:) | Remove from center | | setNotificationCategories(:) | Register actionable types | | setBadgeCount(_:) | Update badge (iOS 16+) | | supportsContentExtensions | Check content extension support |

UNAuthorizationOptions

| Option | Purpose | |--------|---------| | .alert | Display alerts | | .badge | Update badge count | | .sound | Play sounds | | .carPlay | Show in CarPlay | | .criticalAlert | Critical alerts (requires entitlement) | | .provisional | Trial delivery without prompting | | .providesAppNotificationSettings | "Configure in App" button in Settings | | .announcement | Siri announcement (deprecated iOS 15+) |

UNAuthorizationStatus

| Value | Meaning | |-------|---------| | .notDetermined | No prompt shown yet | | .denied | User denied or disabled in Settings | | .authorized | User explicitly granted | | .provisional | Provisional trial delivery | | .ephemeral | App Clip temporary |

Request Authorization

let center = UNUserNotificationCenter.current()

let granted = try await center.requestAuthorization(options: [.alert, .sound, .badge])
if granted {
    await MainActor.run {
        UIApplication.shared.registerForRemoteNotifications()
    }
}

Check Settings

let settings = await center.notificationSettings()

switch settings.authorizationStatus {
case .authorized: break
case .denied:
    // Direct user to Settings
case .provisional:
    // Upgrade to full authorization
case .notDetermined:
    // Request authorization
case .ephemeral:
    // App Clip — temporary
@unknown default: break
}

Delegate Methods

// Foreground presentation — called when notification arrives while app is active
func userNotificationCenter(_ center: UNUserNotificationCenter,
                            willPresent notification: UNNotification) async
    -> UNNotificationPresentationOptions {
    return [.banner, .sound, .badge]
}

// Action response — called when user taps notification or action button
func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse) async {
    let actionIdentifier = response.actionIdentifier
    let userInfo = response.notification.request.content.userInfo

    switch actionIdentifier {
    case UNNotificationDefaultActionIdentifier:
        // User tapped notification body
        break
    case UNNotificationDismissActionIdentifier:
        // User dismissed (requires .customDismissAction on category)
        break
    default:
        // Custom action
        break
    }
}

// Settings — called when user taps "Configure in App" from notification settings
func userNotificationCenter(_ center: UNUserNotificationCenter,
                            openSettingsFor notification: UNNotification?) {
    // Navigate to in-app notification settings
}

---

UNNotificationCategory and UNNotificationAction API

Category Registration

let likeAction = UNNotificationAction(
    identifier: "LIKE",
    title: "Like",
    options: []
)

let replyAction = UNTextInputNotificationAction(
    identifier: "REPLY",
    title: "Reply",
    options: [],
    textInputButtonTitle: "Send",
    textInputPlaceholder: "Type a message..."
)

let deleteAction = UNNotificationAction(
    identifier: "DELETE",
    title: "Delete",
    options: [.destructive, .authenticationRequired]
)

let messageCategory = UNNotificationCategory(
    identifier: "MESSAGE",
    actions: [likeAction, replyAction, deleteAction],
    intentIdentifiers: [],
    hiddenPreviewsBodyPlaceholder: "New message",
    categorySummaryFormat: "%u more messages",
    options: [.customDismissAction]
)

UNUserNotificationCenter.current().setNotificationCategories([messageCategory])

Action Options

| Option | Effect | |--------|--------| | .authenticationRequired | Requires device unlock | | .destructive | Red text display | | .foreground | Launches app to foreground |

Category Options

| Option | Effect | |--------|--------| | .customDismissAction | Fires delegate on dismiss | | .allowInCarPlay | Show actions in CarPlay | | .hiddenPreviewsShowTitle | Show title when previews hidden | | .hiddenPreviewsShowSubtitle | Show subtitle when previews hidden | | .allowAnnouncement | Siri can announce (deprecated iOS 15+) |

UNNotificationActionIcon (iOS 15+)

let icon = UNNotificationActionIcon(systemImageName: "hand.thumbsup")
let action = UNNotificationAction(
    identifier: "LIKE",
    title: "Like",
    options: [],
    icon: icon
)

---

UNNotificationServiceExtension API

Modifies notification content before display. Runs in a separate extension process.

Lifecycle

| Method | Window | Purpose | |--------|--------|---------| | didReceive(_:withContentHandler:) | ~30 seconds | Modify notification content | | serviceExtensionTimeWillExpire() | Called at deadline | Deliver best attempt immediately |

Implementation

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,
              let imageURLString = content.userInfo["image-url"] as? String,
              let imageURL = URL(string: imageURLString) else {
            contentHandler(request.content)
            return
        }

        // Download and attach image
        let task = URLSession.shared.downloadTask(with: imageURL) { url, _, error in
            defer { contentHandler(content) }
            guard let url = url, error == nil else { return }

            let attachment = try? UNNotificationAttachment(
                identifier: "image",
                url: url,
                options: [UNNotificationAttachmentOptionsTypeHintKey: "public.jpeg"]
            )
            if let attachment = attachment {
                content.attachments = [attachment]
            }
        }
        task.resume()
    }

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

Supported Attachment Types

| Type | Extensions | Max Size | |------|-----------|----------| | Image | .jpg, .gif, .png | 10 MB | | Audio | .aif, .wav, .mp3 | 5 MB | | Video | .mp4, .mpeg | 50 MB |

Payload Requirement

The notification payload must include "mutable-content": 1 in the aps dictionary for the service extension to fire.

---

Local Notifications API

Trigger Types

| Trigger | Use Case | Repeating | |---------|----------|-----------| | UNTimeIntervalNotificationTrigger | After N seconds | Yes (≥60s) | | UNCalendarNotificationTrigger | Specific date/time | Yes | | UNLocationNotificationTrigger | Enter/exit region | Yes |

Time Interval Trigger

let content = UNMutableNotificationContent()
content.title = "Reminder"
content.body = "Time to take a break"
content.sound = .default

let trigger = UNTimeIntervalNotificationTrigger(timeInterval: 300, repeats: false)

let request = UNNotificationRequest(
    identifier: "break-reminder",
    content: content,
    trigger: trigger
)

try await UNUserNotificationCenter.current().add(request)

Calendar Trigger

var dateComponents = DateComponents()
dateComponents.hour = 9
dateComponents.minute = 0

let trigger = UNCalendarNotificationTrigger(dateMatching: dateComponents, repeats: true)

let request = UNNotificationRequest(
    identifier: "daily-9am",
    content: content,
    trigger: trigger
)

try await UNUserNotificationCenter.current().add(request)

Location Trigger

import CoreLocation

let center = CLLocationCoordinate2D(latitude: 37.3349, longitude: -122.0090)
let region = CLCircularRegion(center: center, radius: 100, identifier: "apple-park")
region.notifyOnEntry = true
region.notifyOnExit = false

let trigger = UNLocationNotificationTrigger(region: region, repeats: false)

let request = UNNotificationRequest(
    identifier: "arrived-at-office",
    content: content,
    trigger: trigger
)

try await UNUserNotificationCenter.current().add(request)

Limitations

| Limitation | Detail | |-----------|--------| | Minimum repeat interval | 60 seconds for UNTimeIntervalNotificationTrigger | | Location authorization | Location trigger requires When In Use or Always authorization | | No service extensions | Local notifications do not trigger UNNotificationServiceExtension | | No background wake | Local notifications cannot use content-available for background processing | | App extensions | Local notifications cannot be scheduled from app extensions (use app group + main app) | | Pending limit | 64 pending notification requests per app |

---

Live Activity Push Headers

Required Headers

| Header | Value | |--------|-------| | apns-push-type | liveactivity | | apns-topic | {bundleID}.push-type.liveactivity | | apns-priority | 5 (routine) or 10 (time-sensitive) |

Event Types

| Event | Purpose | Required Fields | |-------|---------|----------------| | start | Start Live Activity remotely | attributes-type, attributes, content-state, timestamp | | update | Update content | content-state, timestamp | | end | End Live Activity | timestamp (content-state optional) |

Update Payload

{
    "aps": {
        "timestamp": 1709913600,
        "event": "update",
        "content-state": {
            "homeScore": 2,
            "awayScore": 1,
            "inning": "Top 7"
        }
    }
}

Start Payload (Push-to-Start Token)

{
    "aps": {
        "timestamp": 1709913600,
        "event": "start",
        "content-state": {
            "homeScore": 0,
            "awayScore": 0,
            "inning": "Top 1"
        },
        "attributes-type": "GameAttributes",
        "attributes": {
            "homeTeam": "Giants",
            "awayTeam": "Dodgers"
        },
        "alert": {
            "title": "Game Starting",
            "body": "Giants vs Dodgers is about to begin"
        }
    }
}

Start Payload (Channel-Based)

{
    "aps": {
        "timestamp": 1709913600,
        "event": "start",
        "content-state": {
            "homeScore": 0,
            "awayScore": 0,
            "inning": "Top 1"
        },
        "attributes-type": "GameAttributes",
        "attributes": {
            "homeTeam": "Giants",
            "awayTeam": "Dodgers"
        }
    }
}

End Payload

{
    "aps": {
        "timestamp": 1709913600,
        "event": "end",
        "dismissal-date": 1709917200,
        "content-state": {
            "homeScore": 5,
            "awayScore": 3,
            "inning": "Final"
        }
    }
}

Push-to-Start Token

// Observe push-to-start tokens (iOS 17.2+)
for await token in Activity<GameAttributes>.pushToStartTokenUpdates {
    let tokenString = token.map { String(format: "%02x", $0) }.joined()
    sendPushToStartTokenToServer(tokenString)
}

Activity Push Token

// Observe activity-specific push tokens
for await tokenData in activity.pushTokenUpdates {
    let token = tokenData.map { String(format: "%02x", $0) }.joined()
    sendActivityTokenToServer(token, activityId: activity.id)
}

Content-state encoding rule: the system always uses default JSONDecoder — do not use custom encoding strategies in your ActivityAttributes.ContentState.

---

Broadcast Push API (iOS 18+)

Server-to-many push for Live Activities without tracking individual device tokens.

Endpoint

POST /4/broadcasts/apps/{TOPIC}

Headers

| Header | Value | |--------|-------| | apns-push-type | liveactivity | | apns-channel-id | {channelID} | | authorization | bearer {JWT} |

Subscribe via Channel

try Activity.request(
    attributes: attributes,
    content: .init(state: initialState, staleDate: nil),
    pushType: .channel(channelId)
)

Channel Storage Policies

| Policy | Behavior | Budget | |--------|----------|--------| | No Storage | Deliver only to connected devices | Higher | | Most Recent Message | Store latest for offline devices | Lower |

---

Command-Line Testing

JWT Generation

JWT_ISSUE_TIME=$(date +%s)
JWT_HEADER=$(printf '{ "alg": "ES256", "kid": "%s" }' "${AUTH_KEY_ID}" | openssl base64 -e -A | tr -- '+/' '-_' | tr -d =)
JWT_CLAIMS=$(printf '{ "iss": "%s", "iat": %d }' "${TEAM_ID}" "${JWT_ISSUE_TIME}" | openssl base64 -e -A | tr -- '+/' '-_' | tr -d =)
JWT_HEADER_CLAIMS="${JWT_HEADER}.${JWT_CLAIMS}"
JWT_SIGNED_HEADER_CLAIMS=$(printf "${JWT_HEADER_CLAIMS}" | openssl dgst -binary -sha256 -sign "${TOKEN_KEY_FILE_NAME}" | openssl base64 -e -A | tr -- '+/' '-_' | tr -d =)
AUTHENTICATION_TOKEN="${JWT_HEADER}.${JWT_CLAIMS}.${JWT_SIGNED_HEADER_CLAIMS}"

Send Alert Push

curl -v \
  --header "apns-topic: $TOPIC" \
  --header "apns-push-type: alert" \
  --header "authorization: bearer $AUTHENTICATION_TOKEN" \
  --data '{"aps":{"alert":"test"}}' \
  --http2 https://${APNS_HOST_NAME}/3/device/${DEVICE_TOKEN}

Send Live Activity Push

curl \
  --header "apns-topic: com.example.app.push-type.liveactivity" \
  --header "apns-push-type: liveactivity" \
  --header "apns-priority: 10" \
  --header "authorization: bearer $AUTHENTICATION_TOKEN" \
  --data '{
      "aps": {
          "timestamp": '$(date +%s)',
          "event": "update",
          "content-state": { "score": "2-1" }
      }
  }' \
  --http2 https://api.sandbox.push.apple.com/3/device/$ACTIVITY_PUSH_TOKEN

Simulator Push

xcrun simctl push booted com.example.app payload.json

Simulator Payload File

{
    "Simulator Target Bundle": "com.example.app",
    "aps": {
        "alert": { "title": "Test", "body": "Hello" },
        "sound": "default"
    }
}

---

Resources

WWDC: 2021-10091, 2023-10025, 2023-10185, 2024-10069

Docs: /usernotifications, /usernotifications/sending-notification-requests-to-apns, /usernotifications/generating-a-remote-notification, /activitykit

Skills: axiom-push-notifications, axiom-push-notifications-diag, axiom-extensions-widgets