Design a Push Notification System

A notification message contains a notification JSON payload. When the app is in the background or killed, FCM displays it automatically using Android's system tray — onMessageReceived() is NOT called. You lose control over channel, image, and custom logic. A data message contains only a data payload. FCM always calls onMessageReceived(), even in background/killed state (using a high-priority wakelock). You have full control to build the notification with the correct channel, load images, or trigger a silent data sync without any visible notification. For production apps: always use pure data messages with a type field to dispatch logic in your service.

Two cases. (1) When the message has a notification payload and the app is in background or killed — FCM intercepts and displays it automatically without calling your code. (2) When the device has data saver enabled and the message is not high-priority — FCM may throttle delivery. To guarantee onMessageReceived() is always called: (a) use pure data messages only, (b) set priority: "high" on the FCM send request. For breaking-news style content, high priority is essential. Normal priority messages can be batched and delayed by the OS.

Since Android 8.0 (API 26), every notification must be assigned to a NotificationChannel. Channels let users control each notification category independently — they can mute Promotions without affecting Chat. You create channels via NotificationManager.createNotificationChannel(channel). Crucially, this is idempotent — calling it with the same channel ID multiple times is a no-op, so it's safe to call from Application.onCreate() on every launch. Once created, the user controls importance — your app cannot downgrade a channel the user has elevated, and vice versa. Create all channels on first launch, before posting any notification.

Android 13 introduced android.permission.POST_NOTIFICATIONS as a runtime permission. Without it, notifications are silently blocked. Request it using ActivityResultContracts.RequestPermission(). Best practice: don't request immediately on launch — show the permission rationale in context first (e.g., "Enable notifications to receive chat messages"). If the user denies: gracefully degrade without crashing, offer to enable it later via Settings. Check Build.VERSION.SDK_INT >= 33 before requesting — on older versions it's granted automatically. Target 33+ in your manifest to trigger the runtime request.

Token sync is called on every app launch and every onNewToken(). Without idempotency, you'd hit the backend API on every cold start — wasteful and potentially rate-limited. The fix: cache the last successfully synced token in DataStore. On each launch, compare the FCM-provided token against the cached value. Only call the backend if they differ. Crucially: only write the new token to DataStore after the server returns 200 OK — if you cache first and the network call fails, the token appears synced but isn't, and future launches won't retry.

When a user taps a notification from the killed state, the app cold-starts directly into the destination screen. Without careful setup, pressing Back would exit the app instead of going to Home — a broken UX. NavDeepLinkBuilder from Navigation Component solves this by constructing a synthetic back stack matching the nav graph hierarchy. You call .setGraph(R.navigation.nav_graph).setDestination(R.id.chatFragment).setArguments(bundle). The PendingIntent it creates inflates the full back stack, so Back from ChatFragment correctly goes to HomeFragment. This is the recommended approach over manual Intent construction.

On Android 8+, the notification is silently dropped — it doesn't appear anywhere, no error is thrown. This is a common bug where notifications work on Android 7 but silently fail on 8+. The fix: always call ChannelRegistry.createAll() in Application.onCreate() before any notification is posted. Since channel creation is idempotent, there's no cost to calling it on every launch. The notification must also reference the exact channel ID string — a typo means the notification is posted to a non-existent channel and dropped.

Use Android's notification grouping API. (1) Assign each notification a setGroup(groupKey) — same key groups them together. (2) Post a mandatory summary notification with setGroupSummary(true) and the same group key — without this, Android won't visually collapse the group. Use InboxStyle on the summary to show a preview of all messages. The summary appears on Android 7+ where multiple notifications collapse into one expandable bundle. On Android <7, individual notifications appear separately. Always post the summary last, after all child notifications.

onMessageReceived() runs on a background thread, so synchronous image loading is acceptable. Use Coil's imageLoader.executeBlocking() or Glide's Glide.with(context).asBitmap().load(url).submit().get() — both block until the image is downloaded. Convert the result to a Bitmap and pass to NotificationCompat.BigPictureStyle().bigPicture(bitmap). Cap total time: onMessageReceived() has about 10 seconds to complete before FCM kills it. Use a short timeout on the image request (2–3 s) and fall back to BigTextStyle if the download times out. Never load images on the main thread.

FCM gives onMessageReceived() approximately 10 seconds to complete all work. If it exceeds this, the service is killed and the message may be lost or shown incompletely. For work that exceeds 10 seconds (e.g., heavy sync, large image download): use onMessageReceived() only to enqueue an expedited OneTimeWorkRequest — .setExpedited(OutOfQuotaPolicy.RUN_AS_NON_EXPEDITED_WORK_REQUEST). The worker runs with expedited priority (similar to foreground service) and has no time limit. The notification can either be shown inside the worker or pre-shown in onMessageReceived() with a "Loading…" placeholder.

The server includes a stable notif_id in the data payload (e.g., "notif_id": "msg_12345"). On the client: use notif_id.hashCode() as the Android notification ID passed to NotificationManagerCompat.notify(id, notification). Calling notify() with an already-active ID replaces the existing notification silently — the user sees at most one notification per logical event. This handles the case where FCM delivers the same message twice (rare but possible). If the server retries with a different ID, you'll get a duplicate — so the ID must be stable and message-specific, not time-based.

A silent push is a data message where onMessageReceived() triggers a data sync without showing any notification to the user. Use cases: refreshing a feed in the background when new content is published, syncing chat message list before the user opens the app, invalidating a cached screen. Implementation: inside onMessageReceived(), check type == "silent_sync" and enqueue an expedited WorkManager job. The job syncs Room from the API. When the user opens the app, fresh data is ready. No NotificationManagerCompat.notify() call is made. Works even when the app is killed (high-priority data message).

FCM rotates tokens for security (when the app is reinstalled, the user clears app data, or Google Play Services decides to refresh). onNewToken(token) is called with the new token. You must sync it to your backend immediately — the old token is now invalid and server pushes will fail silently. Call tokenManager.onTokenRefreshed(token) which launches a coroutine to call api.registerToken(newToken) and updates DataStore. Also sync on every launch via FirebaseMessaging.getInstance().token.await() as a belt-and-suspenders check — onNewToken delivery is not guaranteed if the device was offline when the rotation happened.

Two steps on logout. (1) Client: call FirebaseMessaging.getInstance().deleteToken().await() — this invalidates the current token so FCM can no longer deliver to this device. Clear the cached token from DataStore. (2) Server: call your backend api.unregisterToken() so it removes the token from the user's device list. If you skip the server step, the backend will try to push to a deleted token, FCM will return a 404/InvalidRegistration error, and the backend should handle that by removing the stale token. If you skip the client step, a new token is generated on next launch — but until then, someone else logging in could receive the previous user's notifications.

MessagingStyle is purpose-built for person-to-person messaging. It displays a conversation thread with sender names, avatars via Person.Builder(), and supports multiple messages in one notification. It also integrates with smart reply suggestions on Android 10+ and the Bubbles API. BigTextStyle is for long text content from a single source — news articles, emails. Use MessagingStyle whenever you're showing chat messages. It gets preferential treatment by the OS (Conversation Space on Android 11+), appears higher in the notification shade, and supports direct reply without opening the app. Do NOT use it for non-conversation content.

Use RemoteInput to capture typed text inline. Build it with RemoteInput.Builder("reply_key").setLabel("Reply…").build(). Create a PendingIntent pointing to a BroadcastReceiver or Service that handles the reply. Attach both to a NotificationCompat.Action with setAllowGeneratedReplies(true). In your receiver/service: call RemoteInput.getResultsFromIntent(intent) to extract the typed text. Send the reply to your API, then update the notification's MessagingStyle to add the sent message — otherwise the notification spinner keeps spinning. Cancel the old notification and re-post with the sent message included so the user sees their reply.

IMPORTANCE_MAX: full-screen intent (for incoming calls) or heads-up with sound + vibration. IMPORTANCE_HIGH: heads-up notification + sound — pops up over the current screen. IMPORTANCE_DEFAULT: sound, shows in shade but no heads-up pop. IMPORTANCE_LOW: silent, in shade only, no badge. IMPORTANCE_MIN: silent, collapsed at bottom of shade, no badge. The user can adjust this in System Settings per channel — your code cannot override user changes to importance after channel creation. This is by design: users have full control. Choose the right importance at channel creation — you cannot change it later in code.

FCM supports topic subscriptions. Call FirebaseMessaging.getInstance().subscribeToTopic("sports_cricket") — FCM registers the device for that topic on its servers. Your backend can then send one message addressed to /topics/sports_cricket and FCM fans it out to all subscribed devices. The client doesn't need to manage individual tokens for broadcast scenarios. Unsubscribe with unsubscribeFromTopic(). Limitations: topic messages are always low-priority by default; you can't target a specific segment of topic subscribers with personalized data; and FCM throttles bulk topic sends. For user-specific data (e.g., "your order shipped"), use individual token addressing.

FLAG_IMMUTABLE: once created, the PendingIntent cannot have its extras modified by the receiving component. Required for notification actions and deep links from Android 12+ (mandatory; your app will crash without it on API 31+). FLAG_MUTABLE: the receiving component can modify the Intent extras — required for specific cases like AlarmManager exact alarms and media session callbacks that need to inject data. For notification PendingIntents, always use FLAG_IMMUTABLE or FLAG_UPDATE_CURRENT. The FLAG_UPDATE_CURRENT ensures that if a PendingIntent with the same request code already exists, its extras are updated — important when the same screen can be opened with different data.

FirebaseMessagingService runs in the main app process by default. If your app uses multiple processes (e.g., a separate :push process), ensure the service and its Hilt/Dagger injections are initialised correctly in that process — Application.onCreate() is called once per process, so multi-process apps need to guard initialisation with ProcessPhoenix or explicit process name checks. For Room: multi-process Room requires WAL mode and careful connection pooling. Simpler alternative: always run the MessagingService in the main process (the default) by not specifying android:process in the manifest. Dispatch heavy work to WorkManager, which handles cross-process coordination safely.