Firebase Cloud Messaging (FCM) can deliver push notifications to web and mobile users, but reliable delivery depends on more than calling a send API. This guide provides a repeatable implementation workflow for permissions, service workers, registration tokens, topics, message types, foreground handling, and server-side delivery debugging. It also includes a platform comparison, token-maintenance checklist, estimation method, worked examples, and clear triggers for revisiting your design.
Overview
FCM is best understood as a message-routing system between your backend and an app installation. Your application requests notification permission where required, obtains an FCM registration token, sends that token to a trusted backend, and uses the backend to send targeted messages. The client then decides how to display or process the message based on its platform, app state, and message payload.
A reliable Firebase push notification implementation has four separate concerns:
- Permission and capability: determine whether the user has granted notifications and whether the browser or operating system supports the required APIs.
- Token lifecycle: obtain, securely associate, refresh, deactivate, and remove registration tokens.
- Message behavior: choose between notification, data, or combined messages and define what happens in foreground, background, and terminated states.
- Delivery operations: send through a trusted server, record outcomes, handle invalid tokens, and investigate failures without exposing server credentials.
Do not treat an FCM token as a permanent user identifier. A user may have several active tokens across phones, browsers, profiles, or app installations, and a token can become invalid after an app or device lifecycle event. Store tokens as installation-level records, not as a single immutable field on the user profile.
How to estimate
Before implementing or troubleshooting Firebase push notifications, estimate the number of deliverable installations rather than only the number of registered users. A useful planning model is:
Deliverable installations = eligible users × opt-in rate × token registration rate × active-token rate
These are planning inputs, not guaranteed delivery percentages. Define each input using data from your own application:
- Eligible users: users for whom a notification is relevant and who use a supported platform.
- Opt-in rate: the share of eligible users who grant notification permission. The permission flow differs between web, Android, and iOS, so measure platforms separately.
- Token registration rate: the share of permitted installations that successfully obtain and upload an FCM token.
- Active-token rate: the share of stored tokens that remain usable when a message is sent.
For campaign planning, also estimate the number of messages generated by the event:
Messages attempted = recipients × messages per recipient
Keep this separate from delivered, displayed, opened, and acted-on notifications. A successful server response means the request was accepted for processing; it should not be presented as proof that a person saw or interacted with the notification. Add application-level events such as notification_opened or deep_link_completed when you need outcome measurement.
Platform comparison
| Platform | Implementation focus | Common validation points |
|---|---|---|
| Web | Firebase web configuration, browser permission, a service worker, and a web push key configuration | Secure context, correct service-worker scope, supported browser APIs, and permission state |
| Android | Firebase app configuration, SDK integration, runtime notification permission where applicable, and notification channels | Application package identity, channel behavior, app state, and device power-management settings |
| iOS | Firebase configuration, Apple push-notification setup, user permission, and background capability configuration | Bundle identity, signing and push credentials, authorization state, and foreground presentation behavior |
Platform APIs and permission rules change over time. Before release, verify the current Firebase and platform documentation rather than copying an older initialization snippet unchanged.
Inputs and assumptions
Use a small token record that can support cleanup and diagnostics. A practical record may include:
- user ID, when the token belongs to an authenticated user;
- the FCM registration token, stored with appropriate access controls;
- platform and app version;
- installation or browser identifier generated by your application;
- created-at and last-seen timestamps;
- last successful send and last known error;
- environment, such as development, staging, or production.
Upload a token only through an authenticated or otherwise protected endpoint. Validate ownership on the server, avoid putting tokens in public URLs or logs, and do not let an untrusted client send arbitrary FCM messages. Server-side sends should use the Firebase Admin SDK or the current approved server API, with credentials kept outside client code.
Choose the payload based on the desired behavior:
- Notification messages are useful when the platform should handle standard display behavior. Confirm how they behave in foreground and background states before relying on them for application logic.
- Data messages are useful when the application must interpret fields and decide what to do. They require careful handling of background execution limits and platform-specific restrictions.
- Combined messages can provide display fields and application data, but test every app state because handling can differ by platform.
Use topics for broad, non-sensitive subscriptions such as product categories or general announcements. Do not place confidential information in topic names or message payloads. For private, user-specific, or authorization-sensitive notifications, target maintained registration tokens from your backend instead.
Worked examples
Estimating an audience
Suppose a release announcement is relevant to 20,000 installations. Your measurements show that 65% have granted permission, 92% of permitted installations have successfully registered a token, and 90% of stored tokens are currently active. The planning estimate is:
20,000 × 0.65 × 0.92 × 0.90 = 10,764 estimated deliverable installations
This estimate gives the team a defensible audience range and highlights where improvement is possible. If the result is lower than expected, inspect permission timing, token-upload errors, and stale-token cleanup separately rather than assuming the FCM send operation is the only problem.
Token-maintenance checklist
- Request permission at a useful product moment, not automatically on the first page or screen unless the notification need is obvious.
- Retrieve the token after permission and configuration are ready.
- Send the token to your backend over a protected request.
- Update the record when the client reports a token change.
- Record the last-seen time whenever the installation checks in.
- Remove or deactivate tokens when the send service reports them as invalid or unregistered.
- Deduplicate records for the same installation without deleting valid tokens belonging to other devices.
- Test reinstall, sign-out, account switching, app update, browser-profile changes, and permission revocation.
Delivery-failure troubleshooting matrix
| Symptom | Likely area | Next check |
|---|---|---|
| No token is created | Permission, configuration, or client initialization | Inspect client logs, permission state, project configuration, and platform prerequisites. |
| Web token exists but no notification appears | Service worker, browser permission, payload, or scope | Confirm the worker is registered for the intended scope and test foreground and background behavior separately. |
| Some devices work and others do not | Stale tokens, platform configuration, or app-version differences | Group results by platform, version, token age, and error code. |
| Server rejects the request | Credential, project, payload, or target problem | Check the server response, project association, target format, and current API requirements. |
| Messages are accepted but users report missing alerts | Display behavior, permission, device settings, or app state | Log client receipt and display events; do not infer visibility from server acceptance alone. |
| Old records accumulate | Missing token cleanup | Process invalid-token responses and run a periodic review based on last-seen data. |
For a web implementation, test the service worker independently from your application UI. For mobile implementations, test foreground, background, and terminated states on representative OS versions. Use the Firebase Emulator Suite for surrounding application logic where supported, but validate real push delivery on the actual platforms because device and browser notification behavior is not fully reproduced by local emulation.
When to recalculate
Revisit your FCM implementation and delivery estimate whenever an input changes. The most important triggers are a new app release, a permission-flow redesign, a migration between messaging APIs, a change to service-worker code, a new platform or browser target, or a noticeable change in token age and invalidation rates.
Set a regular operational review for token health. Compare registration rate, active-token rate, send errors, client receipt events, notification opens, and downstream actions by platform and app version. A sudden decline in one stage identifies a narrower investigation than a single “delivery rate” metric.
Before each notification campaign, confirm the audience query, topic membership, payload behavior, deep links, rate and message limits in the current official documentation, and the rollback or suppression plan. Send a controlled test to internal accounts first. Afterward, remove invalid tokens, review failures, and update the planning inputs used for the next estimate.
For related implementation work, see the Flutter and Firebase guide, the Firebase Authentication architecture guide, and the Firebase cost optimization guide. Keeping notification delivery connected to authentication, deployment, and monitoring practices makes FCM easier to operate as the application grows.
