Technical reference

Push Notifications Cheatsheet

Reliable mobile and web notification delivery

Must Know

Delivery Flow

app requests permission
app receives device token
backend stores token per installation
backend sends through APNs/FCM
app handles foreground/background tap

json

Payload

Keep payloads small and avoid sensitive data.

{
  "notification": { "title": "Update", "body": "Your report is ready" },
  "data": { "type": "report.ready", "reportId": "42" }
}

Important Patterns

Token Lifecycle

Device tokens rotate and become invalid.

upsert token on refresh
associate with installation + user
remove on logout when appropriate
deactivate invalid-provider responses

Deep Link

A notification is navigation input, not authorization.

validate route type
validate identifier
authorize after app opens
fallback to a safe screen

Useful Recipes

Preferences

Respect platform permission and in-app preferences.

transactional vs marketing
topic-level opt-ins
quiet hours
time zone
channel selection

Idempotent Send

Retries should not spam the user.

notification_key = event_id + user_id + channel
unique constraint prevents duplicate enqueue

Pitfalls & Production

Delivery Reality

The app must synchronize authoritative state after opening.

not guaranteed
may be delayed
may be collapsed
app may be terminated
user may disable permission

Measure the Funnel

Separate provider acceptance from actual delivery.

eligible -> queued -> provider accepted -> delivered when available -> opened -> action