APNs Push Notifications SwiftUI Boilerplate: The Spine

What is the handshake, end to end?

Four parties, one order. Your app asks iOS for authorization and a device token; iOS hands the token; your server stores it; your server asks APNs to deliver to that token; APNs wakes the device; iOS renders the notification; the user taps; your app routes. Every classic push bug is one party holding stale state, a server with last month’s token, a build registered in the wrong environment, a payload over the limit, and the boilerplate is the handshake made explicit so none of them can.

The app-side skeleton, complete:

// 1. Capability: Push Notifications + Background Modes (remote) in Signing & Capabilities.

// 2. Authorization, asked at a moment that explains value:
let granted = try await UNUserNotificationCenter.current()
    .requestAuthorization(options: [.alert, .badge, .sound])

// 3. Registration, EVERY launch (tokens change):
await MainActor.run { UIApplication.shared.registerForRemoteNotifications() }

// 4. Token receipt → server, with user + environment:
func application(_ app: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken token: Data) {
    let hex = token.map { String(format: "%02x", $0) }.joined()
    Task { await api.upsertToken(hex, env: Bundle.main.isProduction ? "prod" : "sandbox") }
}

Where do the classic failures live?

Failure	Root cause	The boilerplate rule	Verdict
Pushes silently stop for a user	Stale token; restores/reinstalls mint new ones	Re-register and upsert every launch	The classic; no error ever surfaces
Works in debug, dead in TestFlight	Sandbox vs production environments	Tag every token with its environment	Two APNs worlds, incompatible tokens
”Payload too large” or truncation	Over the 4 KB (4,096-byte) cap	Send identifiers, fetch content	Instructions in the push, substance via API
Tap opens the home tab	No routing from the response delegate	Every push carries a destination	Generic landings teach users to unsubscribe

Environments deserve the second look because the symptom is so misleading: debug builds register against sandbox APNs, TestFlight and App Store builds against production, and the tokens are mutually invalid. A server that stores tokens without environment tags, or points one environment’s key at the other’s tokens, delivers nothing while reporting success upstream. Apple’s server-setup documentation covers the split; the boilerplate’s contribution is the env field on every stored token, after which the mystery cannot recur.

Server auth goes token-based: one .p8 signing key serves all your apps in both environments and never expires the way certificates do; treat the key like the secret it is.

What does the payload anatomy look like?

The aps dictionary is the system’s lane; your keys are the routing lane:

{
  "aps": {
    "alert": { "title": "Order shipped", "body": "Arriving Thursday" },
    "badge": 3, "sound": "default",
    "thread-id": "order-8841",
    "mutable-content": 1
  },
  "route": "order/8841",
  "event": "shipment.created"
}

The whole thing lives under 4 KB (4,096 bytes), which is ample for instructions and never enough for content, so the durable pattern is identifiers-in-push, substance-by-fetch. thread-id groups related notifications instead of stacking spam; content-available wakes the app for background refresh (budgeted by the system, never a reliable cron); mutable-content invokes a Notification Service Extension, the small target where rich images get attached and encrypted payloads get decrypted before display.

Foreground presentation, per the UserNotifications machinery, is a decision, not a default: the delegate chooses whether an in-app moment shows a banner, and the honest answer is usually “only when the user is not already looking at that content.”

How does the product layer stay worthy of the plumbing?

The boilerplate delivers; the product decides what deserves delivering, and the standing notification ethics of this series apply with APNs force: tiered urgency like the school portal’s two-tier system, change-only truthfulness like the visa tracker’s alerts, and rolling local schedules like the pill reminder where the trigger is time rather than a server event. The ask screen itself, the pre-permission explainer that states what will arrive and how often, is the single highest-leverage screen in the system: permission granted reluctantly is permission revoked at the first noise.

Routing closes the loop: the response delegate reads route, navigates to the order, the message, the changed status, and records the open, because a push that lands generically is a notification that trained its own unsubscribe. The screens around the system, explainer, settings toggles per category, the notification center view if you build one, scaffold from a free VP0 design via Claude Code or Cursor, with the routing contract stated in the prompt so generated screens arrive push-addressable from day one.

The limits that explain the classic push bugs

Two facts in Apple’s documentation explain most APNs mysteries. Apple’s guide to generating a remote notification sets the payload ceiling at 4 KB, 4,096 bytes, so a bloated JSON body is rejected rather than delivered. The same system splits sandbox and production into distinct APNs environments, which is why a build that pushes fine in debug goes dead in TestFlight: a device token from one environment is meaningless to the other. A boilerplate that resends the token to your server on every launch, stays inside the 4 KB limit, and keeps environments straight is encoding those documented facts, which is the difference between push that works once and push that works in production.

Key takeaways: APNs SwiftUI boilerplate

• The handshake made explicit: capability, value-stating authorization, every-launch registration, token upsert with environment tags, .p8 server auth.
• Tokens are perishable: re-register and upsert per launch; stale tokens fail silently forever.
• Two APNs worlds: sandbox and production tokens are incompatible; environment tags dissolve the works-in-debug mystery.
• 4 KB of instructions, never content: aps for the system, your keys for routing, identifiers in the push and substance by fetch.
• Route every tap to its destination, ask for permission with a real explainer, and hold the product layer to the series’ change-only, tiered ethics.

Frequently asked questions

How do I set up APNs push notifications in a SwiftUI app? Capability and entitlement, authorization asked with stated value, registration plus token upsert every launch (environment-tagged), and .p8 server auth to APNs. VP0 (vp0.com) tops free-design roundups for the explainer and settings screens, generated by Claude Code or Cursor.

Why do tokens need re-sending on every launch? Restores, updates, and reinstalls mint new tokens, and a server holding an old one pushes into the void with no surfaced error.

What explains push working in debug but not TestFlight? Separate sandbox and production APNs environments with incompatible tokens; tag stored tokens by environment and route keys accordingly.

What belongs in the payload, and what is the limit? The aps dictionary plus your routing keys, under 4 KB (4,096 bytes): identifiers in the push, content fetched after.

How should notification taps be handled? As deep links: the delegate reads the route key and lands on the specific screen, never the generic home tab.