FCM Identifying & Targeting Users

Firebase Cloud Messaging 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 covers how to link registration tokens to your user accounts, keep that link accurate through login, logout, 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 login 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.

flowchart TD
    A[User signs in on Phone A] --> B[getToken returns token A]
    B --> C[Your backend stores token A for user 123]
    D[Same user signs in on Tablet B] --> E[getToken returns token B]
    E --> F[Your backend stores token B for user 123]
    C --> G[Server looks up tokens for user 123]
    F --> G
    G --> H[Send one FCM message per token]
    H --> I[Delivered to Phone A and Tablet B]

What a push provider would normally handle for you

Customer engagement platforms that sit on top of FCM and APNs hide this work behind a user model. You call a login function with your user ID, the platform's SDK collects the device token in the background, and from then on you send to "user 123" while the platform resolves that to the right devices, notices when tokens change, and discards the ones that stop working.

Firebase Cloud Messaging is the transport layer underneath those platforms, and using it directly means there is no such layer in between. You get full control of the pipeline and no per-user platform costs, and in exchange the bookkeeping moves to your backend:

The rest of this guide walks through 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.

Linking a device to a user at login

Once the user has authenticated, read the device's token and post it to your backend together with your own user ID.

function linkDeviceToUser(userId) {
  median.firebaseMessaging.getToken({
    callback: function (result) {
      if (!result.token) return; // not registered yet, see below

      fetch("/api/push/devices", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        credentials: "include",
        body: JSON.stringify({
          userId: userId,
          fcmToken: result.token
        })
      });
    }
  });
}

Use your own endpoint in place of /api/push/devices. On the server, take the user ID from the authenticated session rather than 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 ask for one. Request permission first, then register:

median.firebaseMessaging.requestPermission({
  callback: function (permission) {
    if (!permission.granted) return;

    median.firebaseMessaging.register({
      callback: function (result) {
        console.log("Registered, token:", result.token);
        // post result.token to your backend as shown above
      }
    });
  }
});

Storing tokens on your backend

Store tokens in their own table rather than as a single column on the user record, since one user can have several devices. An example table could look as follows:

Make the insert an upsert keyed on fcm_token. If a token arrives that is already stored for a different user, reassign it to the new user. That is what happens when two people share a device, and it stops the first user's notifications from reaching the second.

Unlinking a device at logout

When a user signs out, remove the link in both places: delete the token from your backend, then delete it on the device.

function unlinkDeviceFromUser() {
  median.firebaseMessaging.getToken({
    callback: function (result) {
      // 1. Tell your backend to forget this token
      fetch("/api/push/devices", {
        method: "DELETE",
        headers: { "Content-Type": "application/json" },
        credentials: "include",
        body: JSON.stringify({ fcmToken: result.token })
      }).finally(function () {
        // 2. Invalidate the token on the device
        median.firebaseMessaging.deleteToken({
          callback: function (deleted) {
            console.log("Token deleted:", deleted.success);
          }
        });
      });
    }
  });
}

Read the token before you delete it, because your backend needs the value to find the row.

Managing the token lifecycle

A registration token is stable for long periods but not permanent, and Firebase does not tell your server when one changes. Your token table drifts out of date unless the app and the backend both keep it in step. These are the events to plan for:

Two patterns in this table matter most. First, your backend only learns about a new token when the app tells it, so the app has to report its token regularly. Second, your backend only learns that an old token is dead when a send to it fails, so the send path 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 value is unchanged, your backend only refreshes updated_at. If it has changed, the new token is stored and the old one will be pruned the next time a send to it fails.

function median_library_ready() {
  // This example uses the function previously defined. It is not part of the standard JavaScript bridge implmentation as you have to configure it for your backend.
  if (window.currentUserId) {
    linkDeviceToUser(window.currentUserId);
  }
}

Remove tokens that Firebase rejects

When you send to a token that is no longer valid, the FCM API returns an error instead of a message ID:

{
  "error": {
    "code": 404,
    "message": "Requested entity was not found.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.firebase.fcm.v1.FcmError",
        "errorCode": "UNREGISTERED"
      }
    ]
  }
}

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 will never report 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 will start rejecting it. Use the updated_at column to delete tokens older than a window that suits your app, and remember that reporting on every launch keeps active devices well inside it.

A token is not the same as permission

A device can hold a valid token while the user has notifications turned off. Firebase accepts the message and the device does not display it. If you need to know who can actually see your notifications, call checkPermission() when you report the token and store the result alongside it:

median.firebaseMessaging.checkPermission({
  callback: function (permission) {
    median.firebaseMessaging.getToken({
      callback: function (result) {
        // post result.token and permission.granted to your backend
      }
    });
  }
});

Sending to a specific user

Sending happens from your server through 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, obtained 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 rather than requesting one per send.

curl -X POST \
  "https://fcm.googleapis.com/v1/projects/YOUR_PROJECT_ID/messages:send" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "token": "DEVICE_REGISTRATION_TOKEN",
      "notification": {
        "title": "Your order has shipped",
        "body": "Tap to track your delivery."
      }
    }
  }'

A successful send returns the message ID:

{
  "name": "projects/YOUR_PROJECT_ID/messages/0:1700000000000000%abc123"
}

The HTTP v1 API accepts one target per request, so a user with three devices means three requests. Treat each response separately: one device may succeed while another returns UNREGISTERED, in which case you remove only that token as described in Managing the token lifecycle.

When to use each target

For most apps, tokens handle personal notifications and topics handle broadcasts.

Segmenting with topics

Topics let you group users into segments for broadcasts: "users who follow sports," "users on the free plan," "users in the Halifax 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 wire them to the Median JavaScript Bridge.

Subscribe to a topic

median.firebaseMessaging.subscribeToTopic({
  topic: "sports",
  callback: function (result) {
    console.log("Subscribed:", result.success);
  }
});

Unsubscribe from a topic

median.firebaseMessaging.unsubscribeFromTopic({
  topic: "sports",
  callback: function (result) {
    console.log("Unsubscribed:", result.success);
  }
});

List subscribed topics

Use this to set the initial state of the toggles on a preferences page.

median.firebaseMessaging.getSubscribedTopics({
  callback: function (result) {
    console.log("Subscribed topics:", result.topics); // e.g. ["sports"]
  }
});

Topics that follow the user's account

Because subscriptions belong to the device, they stay behind when a user signs out and don't appear on a second device automatically. For segments that depend on account data, such as plan or region, sync them at the same points where you link and unlink the device:

// After login: subscribe to the segments this account belongs to
function syncAccountTopics(user) {
  median.firebaseMessaging.subscribeToTopic({ topic: "plan_" + user.plan });
  median.firebaseMessaging.subscribeToTopic({ topic: "region_" + user.region });
}

// Before logout: remove every subscription from this device
function clearTopics() {
  median.firebaseMessaging.getSubscribedTopics({
    callback: function (result) {
      (result.topics || []).forEach(function (topic) {
        median.firebaseMessaging.unsubscribeFromTopic({ topic: topic });
      });
    }
  });
}

Topic names may contain only letters, numbers, and the characters -_.~%.

Sending 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.

{
  "message": {
    "topic": "sports",
    "notification": {
      "title": "Full time",
      "body": "Catch up on tonight's results."
    }
  }
}