The notification pipeline

Most developers treat notify() as a function call that puts a row in the shade. It is closer to posting a letter: it returns before anything has happened, and several offices can refuse it along the way.

TL;DR#

• NotificationManager is a client proxy. The real work happens in NotificationManagerService inside system_server.
• The call is asynchronous from the app's point of view. notify() returning does not mean the notification was shown.
• Before anything is drawn, the service checks POST_NOTIFICATIONS, resolves the channel, applies Do Not Disturb and ranking, and notifies listeners.
• SystemUI inflates the notification's RemoteViews in its own process. Your code does not run there.
• Any app with a NotificationListenerService grant receives a copy of every notification. Never put secrets in one.

Mental model#

Think of submitting a press release to a newspaper.

You hand it to the front desk (the NotificationManager proxy), which logs it and passes it to the editorial office (NotificationManagerService). The editorial office checks whether you are allowed to publish at all (the permission), which section it belongs in (the channel), whether it is newsworthy enough to interrupt the reader (importance and DND), and where it should appear (ranking). Only then does the typesetter (SystemUI) lay it out.

Your copy is not what gets printed. The editorial office may shorten it, reorder it, or hold it.

Where the analogy breaks#

A newspaper has one edition. Android has a live shade that can re-rank notifications as new ones arrive, so a notification's position can change without anything being republished. Ranking is continuous, not a one-time editorial decision.

The big picture#

The step that surprises people is the permission check: on API 33+ a denied POST_NOTIFICATIONS makes the entire call a silent no-op. No exception, no log line the app sees, no indication that anything was dropped.

Deep dive#

notify() is a Binder call#

val manager = context.getSystemService(NotificationManager::class.java)
manager.notify(TAG, notificationId, notification)

NotificationManager is a thin wrapper over INotificationManager, an AIDL interface. The call marshals the Notification and crosses into system_server.¹

Two consequences:

• The Notification is Parcelable and size-limited. A notification carrying a full-resolution bitmap can fail the Binder transaction. setLargeIcon() with an un-scaled photo is a common cause of "the notification silently does not appear".
• The call is one-way. The service may not have processed the notification when notify() returns, which is why posting and immediately querying getActiveNotifications() can be racy.

The permission gate#

if (ContextCompat.checkSelfPermission(
        context,
        Manifest.permission.POST_NOTIFICATIONS,
    ) != PackageManager.PERMISSION_GRANTED
) {
    // notify() will not show anything. Ask the user first.
}

On API 33+, POST_NOTIFICATIONS is a runtime permission.² A denial means:

• notify() does not throw.
• Nothing appears in the shade.
• The foreground service notification is still shown, because it is part of the service contract.

That last exception is important and frequently misremembered. The foreground service notification is shown regardless; the app's own notifications are not.

Channel resolution#

Every notification names a channel:

val notification = NotificationCompat.Builder(context, CHANNEL_MESSAGES)
    .setSmallIcon(R.drawable.ic_message)
    .setContentTitle("Priya")
    .setContentText("Are we still on for 7?")
    .build()

If the channel does not exist, notify() throws on API 26+.³ This is a validation error at the builder, not a silent drop, and it is the single most common crash when adding channels to an existing app.

The channel's importance decides:

Once the user changes a channel's importance, the app cannot raise it back. This is deliberate: the user's decision outranks the app's preference.

Ranking, DND and policy#

Before SystemUI sees anything, the service applies policy:

• Do Not Disturb can suppress sound, or suppress the notification entirely, depending on the interruption filter and the channel's category.
• Conversation ranking promotes notifications that carry a valid Person and a conversation shortcut to a dedicated section.
• Bubbles may convert a notification into a floating window if the user has enabled them for the conversation.
• Full-screen intent policy decides whether a notification may take over the screen, which is restricted to calling and alarm apps on modern releases.

SystemUI renders a description, not your code#

The notification's content is a RemoteViews — a parcel of layout id and method calls — or a system-drawn layout chosen by the style. SystemUI inflates it in its own process with its own Context.

That is why:

• Custom layouts only support a small set of views (TextView, ImageView, Button, ProgressBar, Chronometer, and a few layout containers).
• The app's code does not run while the notification is displayed. Only a PendingIntent fires code, and it fires in the app's process.
• Custom views are being progressively restricted because they are the part of the system most exposed to a malicious app's layout.

Listeners see everything#

NotificationListenerService is a privileged capability granted by the user in Settings. A service with the grant receives onNotificationPosted and onNotificationRemoved for every notification, including other apps'.⁴

The security implication is direct: notification content is not private from a determined app the user has granted access to. Do not put tokens, one-time codes or personal data in a notification that does not need it.

The architectural implication is equally interesting: a notification listener can cancel or snooze notifications, which is how smartwatch apps and car head units mirror the shade.

What the pipeline explains about bugs#

Almost every "notification problem" maps to one stage of the pipeline, and knowing the stage tells you where to look.

That table is worth keeping. It turns a vague "notifications are broken" into a specific check, and in practice most reports land in the first two rows.

The post-and-forget model#

The pipeline's asynchrony has a design consequence that is easy to miss: you cannot use a notification as a synchronous signal. Posting one and immediately reading getActiveNotifications() is racy, and a notification posted during onPause may not be visible before the activity is gone.

The supported way to know what happened is getActiveNotifications() after a delay, or a listener for your own package in a test. In production, the only reliable feedback that a notification was shown is the user's reaction, which is a poor API but an honest one.

The id is the identity#

The pair of tag and id identifies a notification for its whole life. Posting again with the same pair updates it in place; posting with a different pair creates a second row. That sounds obvious and it is the source of two common bugs: using id 0 for everything (so a service cannot update one notification without replacing another), and generating a new id on every update (so the shade fills with duplicates).

The pattern that works is a stable id per logical thing — conversationId.hashCode(), or a small constant per notification category — and a tag when two categories share an id space.

How it evolved#

Under the hood#

• ‹›NotificationManager.java↗the client proxy and its Binder calls
• ‹›NotificationManagerService.java↗validation, permission checks and dispatch
• ‹›RankingHelper.java↗how notifications are ordered and promoted
• ‹›NotificationListenerService.java↗the listener API other apps use
• ‹›↗where the row views are inflated

Curiosity corner#

• notify() with an id of 0 is allowed, and many apps use it, which makes them impossible to update individually. Use distinct ids per conversation or per state.
• A notification's PendingIntent runs with the app's identity, not SystemUI's. That is why mutability flags became mandatory on API 31.
• The notification shade is a window like any other, which is why it can be screenshotted and why its contents appear in screen recordings unless the app sets FLAG_SECURE on its own window — which does not cover the shade.

Try it#

$ 
adb shell dumpsys notification | head -80

NotificationRecord{... pkg=com.example.app id=1 channel=messages importance=4}

$ 
adb shell dumpsys notification --noredact | grep -A6 com.example.app

NotificationRecord{... pkg=com.example.app}

$ 
adb shell settings get secure enabled_notification_listeners

enabled listeners:
  com.example.watch/.NotificationForwarder

Build it#

Post a notification with a large icon from a full-resolution photo and watch it fail to appear. Then scale the bitmap to a thumbnail and watch it work. The size limit is not documented as a number you can rely on; the failure mode is the lesson.

Check yourself#

Sources#