Push notifications: from your server through APNs and FCM to the device

HOW IT FITS TOGETHER

KEY TERMS

Device token lifecycle

Tokens are issued per app per device and change after reinstall, backup restore or rotation. Re-register on every launch and upsert server-side; delete on 410/UNREGISTERED. FCM expires Android registrations inactive for 270 days and treats a month without a refresh as stale, so store a last-seen timestamp and prune. FCM is moving its registrations to Firebase Installation IDs; registration tokens remain fully supported.

Notification vs data messages

A notification (alert) payload is displayed by the OS even if your app is not running. A data (background) payload is delivered to your code, which must be woken to handle it, so it is subject to throttling and app state. FCM notification messages in the background go straight to the tray; your handler sees the data only when the user taps.

Priority and throttling

APNs priority 10 delivers immediately, 5 and 1 can be grouped into bursts based on power. Apple asks for no more than two or three background pushes an hour and drops held ones if the user force-quits the app. FCM high priority can wake a dozing device, but if your high-priority messages do not lead to visible notifications over about 7 days, FCM demotes them to normal.

Storage, expiry and collapsing

Push services are store-and-forward, best effort, and may reorder messages. APNs stores only one notification per app for an offline device; FCM keeps messages up to their TTL and replaces ones with the same collapse key. Set short expiries for stale-quickly content (a ride arriving) and collapse ids for counters and status.

iOS authorization and interruption levels

Provisional authorization grants quiet delivery to Notification Center without a prompt, with Keep and Turn Off buttons. Each notification has an interruption level: passive, active, time-sensitive (breaks through Focus and the summary; needs the Time Sensitive capability) or critical (needs an entitlement Apple grants on request).

Android channels and POST_NOTIFICATIONS

Since Android 8 every notification needs a channel, and after creation the user, not your app, controls its importance and sound. Since Android 13 (API 33) notifications are off for new installs until the user grants POST_NOTIFICATIONS; apps targeting 13+ decide when to ask, and a denied permission blocks all channels.

Expo push service

An HTTP API in front of APNs and FCM addressed by ExponentPushToken values. Sending returns tickets (Expo accepted it), and receipts fetched about 15 minutes later report what APNs or FCM said, including DeviceNotRegistered. Up to 100 messages per request; receipts are kept for 24 hours. You still configure APNs keys and FCM credentials in EAS.

IN YOUR STACK

import { connect } from "node:http2";
import { createPrivateKey, sign } from "node:crypto";
const { APNS_KEY_P8, KEY_ID, TEAM_ID, BUNDLE_ID } = process.env as Record<string, string>;
const key = createPrivateKey(APNS_KEY_P8);
let cached = { jwt: "", iat: 0 };
function providerToken(): string {
  const now = Math.floor(Date.now() / 1000);
  if (now - cached.iat < 40 * 60) return cached.jwt; // refresh every 20-60 min, never per request
  const b64 = (o: object) => Buffer.from(JSON.stringify(o)).toString("base64url");
  const input = `${b64({ alg: "ES256", kid: KEY_ID })}.${b64({ iss: TEAM_ID, iat: now })}`;
  const sig = sign("sha256", Buffer.from(input), { key, dsaEncoding: "ieee-p1363" }).toString("base64url");
  return (cached = { jwt: `${input}.${sig}`, iat: now }).jwt;
}

const apns = connect("https://api.push.apple.com"); // long-lived; many concurrent streams
apns.on("error", (err) => console.error("APNs session error", err)); // unhandled, it crashes the process
export function sendAlert(token: string, payload: object): Promise<{ status: number; body: string }> {
  return new Promise((resolve, reject) => {
    const req = apns.request({ ":method": "POST", ":path": `/3/device/${token}`, authorization: `bearer ${providerToken()}`,
      "apns-topic": BUNDLE_ID, "apns-push-type": "alert", "apns-priority": "10", "apns-expiration": String(Math.floor(Date.now() / 1000) + 3600) });
    let status = 0, body = "";
    req.on("response", (h) => (status = Number(h[":status"]))).on("data", (c) => (body += c));
    req.on("end", () => resolve({ status, body })).on("error", reject);
    req.end(JSON.stringify(payload)); // { aps: { alert: { title, body }, "interruption-level": "time-sensitive" } }
  });
}

import { GoogleAuth } from "google-auth-library";

const auth = new GoogleAuth({ scopes: ["https://www.googleapis.com/auth/firebase.messaging"] });
const PROJECT = process.env.FIREBASE_PROJECT_ID!;

export async function sendOrderShipped(token: string, orderId: string) {
  const accessToken = await auth.getAccessToken(); // short-lived, cached and refreshed by the library
  const res = await fetch(`https://fcm.googleapis.com/v1/projects/${PROJECT}/messages:send`, {
    method: "POST",
    headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      message: {
        token,
        notification: { title: "Order shipped", body: "Tap to track your parcel" },
        data: { orderId, type: "order_shipped" }, // string values only
        android: { priority: "high", ttl: "3600s", collapse_key: `order-${orderId}`, notification: { channel_id: "orders" } },
        apns: { headers: { "apns-priority": "10", "apns-collapse-id": `order-${orderId}` } },
      },
    }),
  });
  const json = await res.json();
  if (!res.ok) return { ok: false as const, status: res.status, error: json.error }; // see token cleanup tab
  return { ok: true as const, id: json.name as string }; // "projects/<id>/messages/<message-id>"
}

import * as Notifications from "expo-notifications";
import Constants from "expo-constants";
import { Platform } from "react-native";
Notifications.setNotificationHandler({ // presentation while the app is in the foreground
  handleNotification: async () => ({ shouldShowBanner: true, shouldShowList: true, shouldPlaySound: false, shouldSetBadge: false }),
});
export async function registerForPush(api: { post(path: string, body: object): Promise<unknown> }) {
  if (Platform.OS === "android") {
    await Notifications.setNotificationChannelAsync("orders", { name: "Order updates", importance: Notifications.AndroidImportance.HIGH });
  }
  let { status } = await Notifications.getPermissionsAsync();
  if (status !== "granted") ({ status } = await Notifications.requestPermissionsAsync());
  if (status !== "granted") return null;
  const projectId = Constants.expoConfig?.extra?.eas?.projectId ?? Constants.easConfig?.projectId;
  const { data: token } = await Notifications.getExpoPushTokenAsync({ projectId }); // "ExponentPushToken[...]"
  await api.post("/devices", { token, platform: Platform.OS });
  return token;
}

// Server: up to 100 messages per request; keep the ticket ids and fetch receipts later.
export const sendViaExpo = (to: string, accessToken: string) =>
  fetch("https://exp.host/--/api/v2/push/send", { method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${accessToken}` },
    body: JSON.stringify([{ to, title: "Order shipped", body: "Tap to track", channelId: "orders", priority: "high", data: { orderId: "o_123" } }]) });

object Channels {
    const val ORDERS = "orders"
    const val PROMOS = "promos"
    // Idempotent: recreating a channel with the same values is a no-op, so call it on every start.
    fun register(context: Context) {
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
        val nm = context.getSystemService(NotificationManager::class.java)
        nm.createNotificationChannels(listOf(
            NotificationChannel(ORDERS, context.getString(R.string.channel_orders), NotificationManager.IMPORTANCE_HIGH)
                .apply { description = context.getString(R.string.channel_orders_desc) },
            NotificationChannel(PROMOS, context.getString(R.string.channel_promos), NotificationManager.IMPORTANCE_LOW),
        ))
    }
}

// Ask in context on Android 13+ (API 33), e.g. from a "Notify me when it ships" button.
@Composable
fun NotifyMeButton(onResult: (Boolean) -> Unit) {
    val context = LocalContext.current
    val launcher = rememberLauncherForActivityResult(ActivityResultContracts.RequestPermission(), onResult)
    Button(onClick = {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) launcher.launch(Manifest.permission.POST_NOTIFICATIONS)
        else onResult(NotificationManagerCompat.from(context).areNotificationsEnabled())
    }) { Text("Notify me when it ships") }
}

import UIKit
import UserNotifications
@MainActor
func enableNotifications(quietTrial: Bool) async {
    let center = UNUserNotificationCenter.current()
    switch await center.notificationSettings().authorizationStatus {
    case .denied:
        return // no second prompt: offer a button that opens Settings instead
    case .notDetermined: // .provisional: no prompt now; delivered quietly to Notification Center
        var options: UNAuthorizationOptions = [.alert, .sound, .badge]
        if quietTrial { options.insert(.provisional) }
        guard (try? await center.requestAuthorization(options: options)) == true else { return }
    default: break // .authorized, .provisional, .ephemeral
    }
    UIApplication.shared.registerForRemoteNotifications() // token arrives in the app delegate
}
// AppDelegate
func application(_ app: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken token: Data) {
    let hex = token.map { String(format: "%02x", $0) }.joined()
    Task { try await api.upsertDevice(token: hex, environment: apsEnvironment) } // every launch
}
func application(_ app: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    logger.warning("APNs registration failed: \(error)") // no network or missing entitlement; retry later
}

type PushResult =
  | { provider: "apns"; status: number; reason?: string; timestamp?: number }
  | { provider: "fcm"; status: number; errorCode?: string }
  | { provider: "expo"; status: number; error?: string } // from the ticket or the receipt
  | { provider: "webpush"; status: number };
declare const db: { query(sql: string, args: unknown[]): Promise<unknown> };
declare const queue: { retryWithBackoff(deviceId: string, r: PushResult): Promise<void> };
// true only when the address is permanently dead.
function isDeadToken(r: PushResult): boolean {
  switch (r.provider) {
    case "apns": return r.status === 410; // 400 BadDeviceToken is usually a sandbox/production mix-up: alert, don't delete
    case "fcm": return r.errorCode === "UNREGISTERED"; // INVALID_ARGUMENT only once you're sure the payload is valid
    case "expo": return r.error === "DeviceNotRegistered";
    case "webpush": return r.status === 404 || r.status === 410;
  }
}
export async function handleResult(deviceId: string, r: PushResult, sentAt: Date) {
  if (isDeadToken(r)) {
    // APNs 410 carries the moment the token became invalid; keep it if the device re-registered later.
    const invalidSince = r.provider === "apns" && r.timestamp ? new Date(r.timestamp) : sentAt;
    await db.query("DELETE FROM devices WHERE id = $1 AND registered_at < $2", [deviceId, invalidSince]);
  } else if (r.status === 429 || r.status >= 500) {
    await queue.retryWithBackoff(deviceId, r); // exponential backoff with jitter; honour Retry-After
  }
}

WHEN TO REACH FOR WHAT

WHERE IT BITES

• Treating 200 from APNs or FCM (or an ok Expo ticket) as delivered. It only means accepted; delivery is best effort, can be delayed, collapsed or dropped, and has no receipt from the device.
• Putting secrets or full content in the payload. It passes through Apple, Google and possibly Expo and shows on the lock screen; send an ID and let the app fetch details over your authenticated API.
• Prompting for permission on first launch. iOS shows its prompt once and a denial is permanent until Settings; ask after a user action that explains the value, or start with provisional.
• Using silent or high-priority data pushes as a sync engine. iOS throttles them to a few per hour and ignores them for force-quit apps; FCM demotes high priority that never shows anything.
• Keeping tokens forever and attached to whoever signed in first. Dead tokens waste quota, and stale user links leak one user's notifications to another on a shared device.
• Sending a burst to millions of tokens with naive retries. Fan out through a queue with bounded concurrency and backoff, or 429s and 503s turn into a retry storm.

WHEN IT BREAKS IN PRODUCTION

• Push notifications never arrive for some users
• A feature stays broken after the user says no to a permission
• A third-party API starts returning 429
• A brief blip turns into a long outage

SOURCES

• Apple: Sending notification requests to APNs (opens in new tab)Checked 2026-11-06
• Apple: Establishing a token-based connection to APNs (opens in new tab)Checked 2026-11-06
• Firebase: Best practices for FCM registration token management (opens in new tab)Checked 2026-11-06
• Firebase: Android message priority (opens in new tab)Checked 2026-11-06
• Firebase: Migrate to AndroidConfigV2 (preview) (opens in new tab)Checked 2026-11-06
• Apple: Handling notification responses from APNs (opens in new tab)Checked 2026-11-06
• Android: Notification runtime permission (opens in new tab)Checked 2026-11-06
• Expo: Send notifications with the Expo Push Service (opens in new tab)Checked 2026-11-06