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:- Your web app reads the token through the Median JavaScript Bridge.
- Your backend stores it against the signed-in user.
- When you want to reach that user, your backend looks up their tokens and sends to each 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.
Link a device to a user at sign-in
Once the user has signed in, read the device’s token and post it to your backend together with your own user ID./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.
Unlink a device at sign-out
When a user signs out, remove the link in both places: delete the token from your backend, then delete it on the device.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 updatesupdated_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
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 theupdated_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, callcheckPermission() 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 thehttps://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
Success response
UNREGISTERED. In that case, remove only that token, as described in Manage the token lifecycle.
When to use each target
For most apps, use tokens for personal notifications and topics for broadcasts.
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.-_.~%.
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
Replacetoken with topic in the message. In the Test Sender, set Send to to A topic and enter the topic name.
Topic message