Skip to main content
Firebase Cloud Messaging (FCM) delivers to devices, not to people. To send a notification to one specific user, your backend needs to know which devices that user is signed in on. This guide explains how to link registration tokens to your user accounts, keep that link accurate through sign-in, sign-out, and token rotation, and send to a single user or a segment.

How FCM targeting works

Each installation of your app receives a unique registration token from Firebase. The token identifies one app install on one device. It carries no information about who is using the app, and Firebase has no concept of a user account or a sign-in call. That makes the user-to-device mapping your responsibility:
  1. Your web app reads the token through the Median JavaScript Bridge.
  2. Your backend stores it against the signed-in user.
  3. When you want to reach that user, your backend looks up their tokens and sends to each one.
A user with a phone and a tablet has two tokens. A user who reinstalls the app gets a new one.

What a push provider would normally handle for you

Customer engagement platforms built on top of FCM and APNS hide this work behind a user model. You call a sign-in function with your user ID, and the platform’s SDK collects the device token in the background. From then on, you send to “user 123,” and the platform resolves that to the right devices, notices when tokens change, and discards the ones that stop working. FCM is the transport layer underneath those platforms. Using it directly gives you full control of the pipeline and no per-user platform costs, but the bookkeeping moves to your backend: The rest of this guide covers each of these responsibilities. None of them is complicated on its own, but all of them need to be in place before per-user targeting is reliable. Once the user has signed in, read the device’s token and post it to your backend together with your own user ID.
Replace /api/push/devices with your own endpoint. On the server, take the user ID from the authenticated session instead of trusting the value in the request body, so one user can’t register a device under another user’s account. If Automatic Registration is turned off in your plugin settings, no token exists until you request one. Request permission first, then register:
When to link the deviceLink the device on every app launch where the user is signed in, not only on your sign-in page. Tokens can change without notice, and a returning user who is already signed in never goes through your sign-in flow.

Store tokens on your backend

Store tokens in their own table instead of a single column on the user record, since one user can have several devices. For example: Make the insert an upsert keyed on fcm_token. If a token arrives that’s already stored for a different user, reassign it to the new user. That happens when two people share a device, and reassigning the token stops the first user’s notifications from reaching the second. When a user signs out, remove the link in both places: delete the token from your backend, then delete it on the device.
Read the token before you delete it, because your backend needs the value to find the row.
Delete the token on shared devicesRemoving the row from your backend stops your own targeted sends. Calling deleteToken() as well makes sure Firebase rejects anything still addressed to the old token. After deleteToken(), call register() the next time a user signs in to get a new token.

Manage the token lifecycle

A registration token stays the same for long periods, but it isn’t permanent, and Firebase doesn’t tell your server when one changes. Your token table drifts out of date unless both the app and the backend keep it current. Plan for these events: Two patterns in this table matter most:
  • Your backend only learns about a new token when the app reports it, so the app has to report its token regularly.
  • Your backend only learns that an old token is invalid when a send to it fails, so your sending code has to clean up after itself.

Report the token on every launch

Run the same link call whenever the app starts with a signed-in user. If the token hasn’t changed, your backend only updates updated_at. If it has changed, the new token is stored, and the old one is pruned the next time a send to it fails.

Remove tokens that Firebase rejects

When you send to a token that’s no longer valid, the FCM API returns an error instead of a message ID:
Error response
Check the response of every send and act on the error code:

Expire tokens you haven’t seen in a while

A device that never opens your app again never reports a new token, and you may not send to it often enough to see it fail. Firebase considers a token stale after 270 days of inactivity and starts rejecting it. Use the updated_at column to delete tokens older than a window that suits your app. Reporting on every launch keeps active devices well inside that window.

A token isn’t the same as permission

A device can have a valid token while the user has notifications turned off. Firebase accepts the message, but the device doesn’t display it. If you need to know who can actually see your notifications, call checkPermission() when you report the token and store the result with it:

Send to a specific user

Send from your server with the FCM HTTP v1 API. Look up the user’s tokens in your database and send one request per token. Each request is authorized with a short-lived OAuth 2.0 access token. Get it from a service account in your Firebase project, with the https://www.googleapis.com/auth/firebase.messaging scope. Access tokens last one hour, so cache and reuse them instead of requesting a new one for each send.
Send to one device
A successful send returns the message ID:
Success response
The HTTP v1 API accepts one target per request, so a user with three devices needs three requests. Handle each response separately. One device may succeed while another returns UNREGISTERED. In that case, remove only that token, as described in Manage the token lifecycle.
Test a single-device send firstBefore writing server code, confirm delivery with the Test Sender:
  1. Open the demo page in your app, tap Get Token, then tap Copy Token.
  2. On your computer, open the Test Sender, set Send to to A single device (registration token), and paste the token.
The Payload panel shows the exact JSON the Test Sender sends, including fields for target URL, image, channel ID, and badge. Use Copy JSON as a starting point for your server payload.
Keep service account keys off the clientA service account key can send to every user of your Firebase project. Only use it on your server. Never include it in your website or app, and only load a test project’s key into the Test Sender.

When to use each target

For most apps, use tokens for personal notifications and topics for broadcasts.
Don’t use topics for private messagesA topic such as user_123 can look like a shortcut for reaching one user on all their devices without storing tokens. But topic subscriptions are requested by the app, so any app install can subscribe to any topic name. Only use topics for content you’d be comfortable with any user receiving.

Segment users with topics

Topics let you group users into segments for broadcasts, such as users who follow sports, users on the free plan, or users in a certain region. A device can subscribe to as many topics as you like, and subscriptions are stored per device. Build the subscription controls in your web UI and connect them to the Median JavaScript Bridge.
Topic names can only contain letters, numbers, and the characters -_.~%.

Keep topics in sync with the user’s account

Subscriptions belong to the device, so they stay when a user signs out, and they don’t carry over to a second device. For segments based on account data, such as plan or region, sync subscriptions when you link and unlink the device:

Send to a topic

Replace token with topic in the message. In the Test Sender, set Send to to A topic and enter the topic name.
Topic message
Last modified on November 20, 2026