Skip to content

Push notifications

How a server reaches a device when the app is closed: a token store, a queue of per-device sends, a platform push service with limited storage, and the priority, expiration and collapse settings on each send.

On this page

What it is

A push notification is a small message a server hands to a platform push service, which forwards it to a device. Your server does not talk to the phone. On Apple devices the service is APNs and the address is a device token; on Android, Firebase Cloud Messaging (FCM) is one such service with a registration token, and FCM's guidance is for the app to read its current token and send it to your server for storage, with a timestamp. On the web, a page with an active service worker subscribes through the Push API and receives a subscription with an endpoint URL and an encryption key; your server posts to that endpoint, and the browser starts the service worker when a message arrives, whether or not the page is in the foreground.

Delivery has limits the design must absorb. Apple engineers on the developer forums describe APNs storage for an offline device as one notification per bundle ID per device: when several are sent, one is kept, not reliably the latest, and a later one replaces what was stored. A stored notification is discarded once the time in its apns-expiration header passes. On Android and the web, FCM stores a message for the lifespan you set, from 0 to 2,419,200 seconds (28 days), and four weeks when you set nothing; on iOS it defers to the APNs expiration. With a collapse key, FCM keeps just the last message under that key while the device is disconnected, and a registration token may have at most four collapse keys in use at a time; without one, an Android app instance can have 100 non-collapsible messages pending, and when that limit is reached FCM discards the stored messages. The Web Push protocol (RFC 8030) has the same shape: a TTL header in seconds says how long the push service may hold the message, and a Topic header lets a new message replace a pending one.

SettingAPNs (HTTP/2 provider API)FCMWeb Push (RFC 8030)

Urgency

apns-priority: 10 asks for immediate delivery and must show an alert, sound or badge; 5 lets the device weigh power and may batch

Priority high or normal; normal may be delayed for a backgrounded app, high is attempted at once even in Doze

Urgency header: very-low, low, normal, high

How long to hold it

apns-expiration: a UNIX time; 0 means don't store it, try once and drop it

Lifespan from 0 to 28 days, four weeks when unset (Android and web)

TTL header in seconds

Merge with an older one

apns-collapse-id, up to 64 bytes; matching ids show as one notification

Collapse key; at most four in use per token at a time

Topic header replaces a pending message with the same topic

Dead address

HTTP 410: the token is no longer active for the topic

UNREGISTERED (HTTP 404)

Depends on the push service's response

A regular APNs notification payload tops out at 4 KB (4096 bytes), with a little more room for VoIP pushes, so the notification carries what the user reads on the lock screen plus an identifier, not the full record. On open, the app fetches the record from your API. That pattern, push a hint and pull the data, also absorbs the delivery gaps above: a user who missed four of five notifications still sees all five messages because the inbox lives on the server.

In a design round the pipeline has four parts. A token store maps a user to their devices, each with a platform, a token and a timestamp your server updates whenever the app checks in; FCM's own guidance is to refresh that timestamp regularly, treat a registration that has been silent for more than a month as stale, and expect Android registrations idle for 270 days to be rejected. A notification service turns an event into zero or more sends after checking the user's preferences, quiet hours and per-user rate limits. A queue holds one job per device so a hot event (a group post to thousands of followers) doesn't block the request that caused it. Sender workers call the provider, and the provider's answer feeds back: delete the token on a dead-address response, retry with backoff on 429 and 5xx, and record the outcome for metrics.

When to use it

Reach for push when the user is not in the app and the event matters to them soon: a direct message, a delivery at the door, a sign-in from a new device, a payment that failed. The app is closed, so a socket the app would hold is not an option. On the web, the browser starts the service worker to handle the message, so the same rule holds for users who opted in.

Use the per-send settings deliberately rather than defaulting them. Give a time-sensitive, user-visible alert high urgency; give a silent content refresh normal or low urgency so the device can batch it and save battery. Put the same collapse id on updates to one thing (an unread count, a live score, an order's status) so they show as one notification instead of stacking. Set the expiration to the moment the notification stops being useful: a few minutes for "your driver is arriving", a day or more for "you have a new message". And send one id, not the content, when the content is larger than the cap or could change before the user opens it.

When not to

Not when the app is open and updates are frequent. For a chat screen or a live dashboard, a connection the app holds while in the foreground usually reaches the screen sooner and skips the third party; see WebSockets, server-sent events and polling. A page can receive a push in the foreground too, but push matters most when the app is not running.

Not as the record of what happened. A device offline for a weekend gets at most one stored APNs notification per app, not reliably the latest, and FCM drops non-collapsible messages past its pending limit, so a design that reconstructs state from notifications loses items. Keep the list on the server and have the app sync on open; the notification's job is to prompt that sync. Our advice: if a design needs proof that a person saw something (a legal notice, a code that must be read), have the app acknowledge it to your API or use another channel, rather than resting on the push itself.

Not for high-frequency streams. A price that changes each second or a game that updates each move would send hundreds of notifications an hour, and Apple's documentation says notifications at the power-saving priority may be grouped and arrive in bursts. Collapse them into one that replaces itself, send a summary on a timer, or leave the stream to a connection the app opens.

Not before preferences. Our advice: check opt-outs, per-category settings and quiet hours before anything is enqueued, and cap how many notifications a user gets in an hour. Treat marketing sends as a separate, lower-priority lane with its own budget, so they can't crowd out a transactional alert.

Compared

DecisionOne optionThe otherPick the first whenPick the second when

What the payload carries

The full content

An id the app fetches

The text is short, must be readable with no network, and won't change

The record is bigger than the 4 KB cap on a regular APNs notification, is sensitive, or may change before the user opens it

Collapse or stack

Same collapse id, shown as one notification

Distinct notifications

Each one supersedes the last: a counter, a status, a score

Each one is a separate item the user must see, such as messages from different people

Urgency

High: ask for immediate delivery

Normal or low: the device may batch it

A person is waiting on it: a message, a call, a security alert

It is a background refresh or a digest, and battery matters more than a few minutes' delay

Expiration

Short, or zero so it is tried once and dropped

Long, up to the provider's maximum (28 days on FCM for Android and web)

The content goes stale fast and a late delivery would mislead

The content stays true for days and a late arrival still helps

Channel

Platform push

A connection the app holds, or pull on open

The app is closed and the event matters soon

The app is in the foreground, or completeness matters more than speed

In a picture

registeruploadToken storeYour APIPush serviceApp on device

Step 1 of 3

Register the device

The app reads its token from the platform's SDK and uploads it to your API, which stores it against the user with the platform and a timestamp.

How to say it in an interview

The common mistake

Quiz

A phone is off for a day. In that time your server sends five chat notifications through APNs with no collapse id. What reaches the phone when it comes back?
APNs answers a send with 410, and FCM answers another with UNREGISTERED. What should the worker do?
A ride app sends "your driver is two minutes away". Which setting matters most?
A sports app pushes a score update after each goal. How should the sends be configured?

Related

Sources

  1. Apple: Local and Remote Notification Programming Guide, Communicating with APNs
  2. Apple: Local and Remote Notification Programming Guide, Creating the Remote Notification Payload
  3. Apple Developer Forums, thread 775455: APNs stores one notification per bundle ID
  4. Apple Developer Forums, thread 765801: notification not delivered to an offline device
  5. Firebase Cloud Messaging: Set the priority of a message
  6. Firebase Cloud Messaging: Set the lifespan of a message
  7. Firebase Cloud Messaging: Non-collapsible and collapsible messages
  8. Firebase Cloud Messaging: Best practices for FCM registration management
  9. Firebase Cloud Messaging: Understanding message delivery
  10. RFC 8030: Generic Event Delivery Using HTTP Push
  11. MDN: Push API
Sign in to report a mistake