axiom-push-notifications-ref

Name: axiom-push-notifications-ref
Author: charleswiltgen

github.com/charleswiltgenDevelopment1.2k65 installsUpdated today

About axiom-push-notifications-ref

An API reference skill for developers implementing Apple push notifications. It brings together APNs transport, UserNotifications APIs, payload formats, Live Activities, and local notification references.

Key features

01APNs endpoints, headers, and responses
02JWT authentication reference
03Payload keys and examples
04UserNotifications API reference
05Live Activity push fields
06Local notification triggers

Use cases

01Building APNs requests
02Implementing notification authorization and actions
03Preparing Live Activity payloads
04Scheduling local notifications

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/charleswiltgen/axiom --skill axiom-push-notifications-ref

After installing, type/axiom-push-notifications-refin Claude Code to confirm it loaded.

Details

From the project README

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

Comments

Markdown supported

Details

Author: charleswiltgen
Repository: charleswiltgen/axiom
Category: Development
Installs: 65
GitHub stars: 1,231

Report

More skills

All skills

remotion-render

github.com/inference-sh

1.6M

Render videos from React/Remotion component code via inference.sh. Pass TSX code, get MP4. Supports all Remotion APIs: useCurrentFrame, useVideoConfig, spring, interpolate, AbsoluteFill, Sequence. Configurable resolution, FPS, duration, codec. Use for: programmatic video generation, animated graphics, motion design, data-driven videos, React animations to video. Triggers: remotion, render video from code, tsx to video, react video, programmatic video, remotion render, code to video, animated video, motion graphics code, react animation video

improve-codebase-architecture

github.com/mattpocock

1.2M

Scan a codebase for architecture improvement opportunities, present them as a visual HTML report, then dive deep into whichever one you pick.

design-mobile-apps

github.com/designed-by-ai

1.1M

Design mobile app screens with Sleek, edit Sleek projects, and implement their designs in React Native or HTML

vercel-react-best-practices

github.com/vercel-labs

848.6k

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

axiom-push-notifications-ref

About axiom-push-notifications-ref

Key features

Use cases

Install

Details

Push Notifications API Reference

Quick Reference

APNs Transport Reference

Endpoints

Request Format

APNs Headers

Response Codes

JWT Authentication Reference

JWT Header

JWT Claims

Rules

Authorization Header Format

Payload Reference

aps Dictionary Keys

Alert Dictionary Keys

Sound Dictionary (Critical Alerts)

Interruption Level Values

Example Payloads

Basic Alert

Localized with loc-key/loc-args

Silent Background Push

Rich Notification (Service Extension)

Critical Alert

Time-Sensitive with Category

UNUserNotificationCenter API Reference

Key Methods

UNAuthorizationOptions

UNAuthorizationStatus

Request Authorization

Check Settings

Delegate Methods

UNNotificationCategory and UNNotificationAction API

Category Registration

Action Options

Category Options

UNNotificationActionIcon (iOS 15+)

UNNotificationServiceExtension API

Lifecycle

Implementation

Supported Attachment Types

Payload Requirement

Local Notifications API

Trigger Types

Time Interval Trigger

Calendar Trigger

Location Trigger

Limitations

Live Activity Push Headers

Required Headers

Event Types

Update Payload

Start Payload (Push-to-Start Token)

Start Payload (Channel-Based)

End Payload

Push-to-Start Token

Activity Push Token

Broadcast Push API (iOS 18+)

Endpoint

Headers

Subscribe via Channel

Channel Storage Policies

Command-Line Testing

JWT Generation

Send Alert Push

Send Live Activity Push

Simulator Push

Simulator Payload File

Resources

Comments

`aps` Dictionary Keys