Push Notifications

A push notification is a short message your server asks a platform service to deliver to one device. Your code is not running when it arrives. The operating system receives it, decides whether to show it, and draws it — on the lock screen, in a banner, in a list the user may not look at for hours.

Three parties are involved and you control one of them. Your server sends to the platform's push service, the push service delivers to the device, and the device's operating system decides what the user sees. Every hop can delay, deduplicate or drop the message. So delivery is best-effort: not guaranteed, not instant, and not ordered. A notification is a prompt to look at your app, never the mechanism that carries a fact your app depends on.

For the field app that distinction is concrete. If a visit is reassigned, the server records it and the app fetches the change when it next syncs. The notification exists so an engineer hears about it before driving to the wrong site. If the notification never arrives, the app is still correct — the engineer finds out later than you hoped, which is a worse experience rather than a broken one.

{
  "display": {
    "title": "Visit reassigned",
    "body": "Your 14:00 visit has moved to Northgate Depot"
  },
  "routing": {
    "type": "visit.reassigned",
    "path": "/employees/482/notes",
    "visitId": "9f31"
  },
  "replaces": "visit.9f31",
  "urgency": "normal",
  "sentAt": 1712050200
}

• These field names are invented for this lesson. Every push service uses its own, and none of them look exactly like this. The shape is the transferable part: text for the system to display, separate data for your app to act on, and a small amount of metadata about the message itself.
• Splitting display from routing keeps the two audiences apart. A person reads the first; your code reads the second. Mixing them produces a body string that some screen has to parse, which breaks the first time someone edits the wording.
• The path is a deep link, and it arrives from outside your app. Validate it on the way in, exactly as the navigation lesson's resolver does, and resolve it to a stack rather than a single screen so back has somewhere to go.
• Nothing in this payload is confidential. A depot name and a time are visible on a lock screen to anybody holding the device, which is the correct standard for a notification. Had the message needed to mention a medical detail, a disciplinary matter or a salary, the body would say that there is something to read and the app would show it after the user is past the lock screen.
• The replaces key asks the system to supersede an earlier notification about the same visit instead of stacking a new one beside it. A device that has been out of signal for three hours can otherwise deliver nine notifications at once, of which eight are already wrong.
• Urgency is a request, not an instruction. The normal class lets the platform batch delivery to save battery, which can mean minutes of delay. Both platforms offer a more immediate class and both limit how much of it you may use, so reserve it for what genuinely cannot wait and expect to justify it.
• sentAt lets the app tell how old a message is. Because delivery is best-effort, a notification tapped at 16:00 may have been sent at 11:00, and a screen that renders it as current is misleading.

Permission is the part most teams get wrong, and it is worth understanding as a budget rather than a checkbox. You get one system prompt. If the user declines it, you do not get another; the setting moves into a device settings screen almost nobody visits. And anyone who later finds your notifications irrelevant turns them off there, permanently, without telling you. So the budget is spent once and it can only shrink.

That argues for asking at a moment when the value is obvious, not on first launch. On first launch the user has seen one screen and has no idea what you would send them, so the honest answer to the prompt is no. Ask instead at the point where the notification is clearly useful: the first time a visit is assigned to the engineer by someone else. Show your own short explanation first — one sentence about what you will send and roughly how often — and request the system prompt only after they agree to it. A decline on your own screen costs you nothing, because the system prompt is still unspent and you can ask again next week.

After permission, relevance and timing are what keep it. Every notification spends a little of the user's patience, and an irrelevant one spends a lot. A notification at 03:00 about a visit that starts at 14:00 costs you the permission, and along with it every future notification that would have mattered. Decide per notification type whether it can wait for working hours, and hold the ones that can. The server is the right place for that decision, because it knows the recipient's shift pattern and the device does not. Batch what is routine, send immediately only what changes what the user is about to do, and give people per-category control inside your app so they can decline one kind rather than all of them.

Then land them in the right place. A notification about visit 9f31 that opens the home screen has made the user do the work its own wording described, and the second time that happens they stop tapping. Deep-link to the screen the notification is about, with a sensible parent beneath it, and load fresh data on arrival — the payload told you what changed, not what the current state is.

type PermissionState = "notAsked" | "granted" | "denied";

interface AskContext {
  permission: PermissionState;
  /** True once a visit has been assigned to this engineer by someone else. */
  hasAssignedVisit: boolean;
  /** Set when the user declined our own explanation screen. */
  deferredUntil: number | null;
  softDeclines: number;
}

const DEFER_MS = 1000 * 60 * 60 * 24 * 7;
const MAX_SOFT_DECLINES = 2;

/**
 * Whether to show our own explanation. The system prompt is requested only
 * after the user agrees here, because the system prompt is one-time.
 */
export function shouldExplainNotifications(ctx: AskContext, now: number): boolean {
  if (ctx.permission !== "notAsked") return false;
  if (!ctx.hasAssignedVisit) return false;
  if (ctx.softDeclines >= MAX_SOFT_DECLINES) return false;
  if (ctx.deferredUntil !== null && now < ctx.deferredUntil) return false;
  return true;
}

export function afterSoftDecline(ctx: AskContext, now: number): AskContext {
  return { ...ctx, softDeclines: ctx.softDeclines + 1, deferredUntil: now + DEFER_MS };
}

• As everywhere in this course, the shape is the transferable part. Requesting permission and reading its current state are platform calls that look nothing like this, and the toolkit you use will have its own names for them.
• The two-step ask is the whole design. Your own screen is repeatable and costs nothing when refused. The system prompt is one-time and a refusal there is effectively permanent, so it is requested only when the user has already said yes to the idea.
• hasAssignedVisit is the condition that makes the value obvious, written as a rule rather than a hope. It means the prompt cannot appear on first launch, because on first launch nothing has been assigned. Putting that in code is what stops the requirement quietly eroding when someone adds an onboarding screen later.
• deferredUntil separates not now from no. Someone who declines your explanation while standing in the rain has not made a decision about notifications, and a week later is a reasonable time to mention it again.
• MAX_SOFT_DECLINES stops that becoming nagging. Two refusals of your own screen is an answer, and continuing to ask is the behaviour that makes people uninstall an app. The trade-off is real: a lower limit respects the user more and loses some people who would have said yes on a better day.
• The function is pure, so the rule is testable without a device. Assert that a fresh install is never asked, that a deferred user is quiet for a week, and that a granted user is never shown the screen again.