Skip to Content
Platform.Ontology

APNs delivery: payload, priority, expiration, collapse

Apple's push channel: 4 KB payload (5 KB VoIP), priority 10 or 5, optional expiry and collapse id.

Works without askingNotifications and backgroundPushAndroid and iPhoneIn the background

In one line

Can send alerts to an iPhone through Apple, up to 4 KB of data per message

Apple's push channel: 4 KB payload (5 KB VoIP), priority 10 or 5, optional expiry and collapse id.

Apple holds only the latest push per collapse id and can drop or delay low priority ones. The company learns delivery only as best effort, so apps pair pushes with a fetch on open.

What it can and can't do

What the user does: You allow notifications when the app asks, or you sign in so it can reach your device

It can

  • Send an alert, banner, sound or badge update to your iPhone
  • Mark a message as urgent or low priority so it is delivered right away or later
  • Replace an older message with a newer one, and let a message expire if you were offline

It cannot

  • Send a visible alert if you said Don't Allow
  • Send more than about 4 KB per message, or 5 KB for call pushes
  • Make a message arrive faster than Apple allows; low priority pushes can wait
  • Use this on Android, which has its own system

How it differs between platforms: Apple's system is APNs. Android uses Google's FCM instead.

On Android and iPhone

AndroidiPhone
StatusNot supportedSupported
First versionNot availableiOS 3.0
Permission or entitlementNot listedaps-environment entitlement; apns-push-type header
Protection levelnoneentitlement
How access is grantednot-exposedentitlement
What the user seesNot listedAlert permission prompt for visible notifications
How long it lastsNot listedStored up to 30 days when apns-expiration is omitted; 0 means one delivery attempt; only the newest notification per collapse id is kept
How to take it backNot listedSettings > Notifications; uninstall
Store policyNone listedApp Review 4.5.4; APNs token auth key or certificate
APINot listedapi.push.apple.com:443 HTTP/2, UNUserNotificationCenter
NotesAndroid equivalent is FCM; see mob.notif.fcm-deliveryPayload 4096 bytes (5120 for VoIP), uncompressed JSON; apns-collapse-id max 64 bytes; apns-priority 10 immediate, 5 power considerate, 1 never wakes the device; keep HTTP/2 connections open for hours to days

Data you get

What comes back: APNs request
Shape: object
How often: Per push

FieldTypeUnitRangePrecision
payloadbinarybinary0 to 4096 (5120 VoIP)exact
apns-priorityenumNone10, 5, 1Not listed
apns-expirationintegerunix seconds0 or future1 s
apns-collapse-idstringbinaryup to 64Not listed

Technical limits

  • Delivery is best effort
  • Force quit by the user stops background content pushes until relaunch

The story

What it is

Apple's push system that carries small alerts from an app's server to your iPhone.

For you

You see the alert pop up. Behind the scenes, Apple holds the message, may delay low urgency ones, and keeps only the newest version of a repeated alert.

For makers

Makers use it for messages, delivery and news alerts. Because delivery is best effort, they never rely on one push alone and refetch the real data when the app opens.

Where you see it

TypeExampleApps
messagingA chat app sends a tiny alert so your friend's message shows instantly on the lock screen.iMessage, WhatsApp
deliveryA courier app sends your package is arriving with high priority.DoorDash
newsA news app sends breaking news and collapses older alerts so you only see the newest.NYT, BBC
gamesA game sends your base is under attack to your phone while the app is closed.Clash of Clans
bankingA bank sends a card was used alert, with a short expiry so it is not late.None named
adsA retailer sends a flash sale alert and counts who opened it as a measure of the campaign.None named
liveA sports app sends goal alerts to fans, with a one time key so duplicates are merged.ESPN

Risks

  • Opens can be tracked
  • Spam if overused

Android and iPhone in short

  • Android: Android uses FCM instead.
  • iPhone: Alerts need your permission. Messages are small, around 4 KB.

What the platform says

Good uses and abuse

Legitimate uses

  • Messaging
  • Delivery alerts

Known abuse

  • Spam; apps tracking opens via pushes

Scores

ScoreValueMeaning
Sensitivity2 of 5How revealing the data is
Utility5 of 5How useful it is to honest apps
Friction1 of 5How much the user has to do
Fingerprint bitsNot ratedRough identifying entropy, when known

A real example: LinkedIn

LinkedIn iOS app uses APNs for alerts

History

  • 2014-09, iPhone iOS 8: Payload limit raised from 256 bytes to 2 KB on the legacy channel
  • 2015-12, iPhone iOS 9 era: HTTP/2 APNs provider API announced with a 4 KB payload limit
  • 2019-09, iPhone iOS 13: apns-push-type header introduced (required for watchOS, recommended elsewhere)
  • 2021-03, iPhone APNs: Legacy binary provider interface switched off; HTTP/2 only

Same idea on the web

Sources

How well checked: Checked against real behavior.

On this page