@anh.votuan/fcm-http-v1
Receive Firebase Cloud Messaging (FCM) push notifications in a Node.js or
Electron process, the way Chrome does: the process registers as a Web Push
receiver, keeps a connection to mtalk.google.com and decrypts every message.
Uses the current Firebase Installations / FCM Registrations endpoints (the
legacy fcm/send + server key flow was shut down by Google in June 2024).
- Node.js >= 10 (Electron >= 4)
- Web Push payloads in
aesgcmandaes128gcm(RFC 8291) - No HTTP library: Node built-ins only; honours
HTTPS_PROXY/HTTP_PROXY/NO_PROXYfor the registration requests
Install
npm install @anh.votuan/fcm-http-v1
Usage
const { register, listen } = require('@anh.votuan/fcm-http-v1');
const config = {
firebase: {
apiKey: '<web api key>',
appID: '<web app id>',
projectID: '<project id>',
},
vapidKey: '', // optional
};
async function start(storage) {
// Register once and keep the credentials: registering again creates a new
// FCM token, and the server only knows the token you sent it.
let credentials = await storage.get('credentials');
if (!credentials) {
credentials = await register(config);
await storage.set('credentials', credentials);
}
sendTokenToYourBackend(credentials.fcm.token);
// Pass the ids already received, or they are delivered again on connect.
const persistentIds = (await storage.get('persistentIds')) || [];
const client = await listen(
Object.assign({}, credentials, { persistentIds }),
({ notification, persistentId }) => {
persistentIds.push(persistentId);
storage.set('persistentIds', persistentIds);
console.log(notification.notification, notification.data);
}
);
client.on('connect', () => console.log('connected'));
client.on('disconnect', () => console.log('disconnected, reconnecting'));
return client; // client.destroy() to stop
}
API
register(config) → Promise<credentials>
Checks in with Google as a new Chrome instance, creates a Firebase installation
and registers it with FCM. credentials.fcm.token is the token your server
sends to. Persist the whole object.
listen(credentials, onNotification) → Promise<Client>
Validates the credentials, connects in the background and reconnects on its
own. onNotification({ notification, persistentId }) receives the decrypted
FCM message (notification.notification, notification.data, ...).
Client
EventEmitter returned by listen().
| Event | Payload |
|---|---|
EVENTS.NOTIFICATION_RECEIVED ('ON_NOTIFICATION_RECEIVED') |
{ notification, persistentId } |
EVENTS.CONNECT ('connect') |
— |
EVENTS.DISCONNECT ('disconnect') |
— |
client.destroy() closes the connection and stops reconnecting.
A message that cannot be decrypted is dropped with a warning; the following ones are still delivered.
Electron packaging
protobufjs cannot read .proto files from inside app.asar. In a packaged app
the library looks for them in resources/app.asar.unpacked/dist/ first, then
next to its sources. Copy them there at build time, e.g. with
copy-webpack-plugin:
new CopyWebpackPlugin([
{ from: 'node_modules/@anh.votuan/fcm-http-v1/src/mcs.proto', to: 'mcs.proto' },
{
from: 'node_modules/@anh.votuan/fcm-http-v1/src/gcm/checkin.proto',
to: 'checkin.proto',
},
{
from: 'node_modules/@anh.votuan/fcm-http-v1/src/gcm/android_checkin.proto',
to: 'android_checkin.proto',
},
]);
and unpack them ("asarUnpack": ["dist/*.proto"] with electron-builder).
Debugging
DEBUG=fcm-http-v1 node app.js
prints proto loading, socket errors and the MCS wire protocol.
Try it
npm run register -- --apiKey=<key> --appID=<app id> --projectID=<project id>
npm run listen
register saves the credentials to storage.json (git-ignored); listen uses
them and records the received persistent ids.
Development
npm install
npm run check # eslint + prettier --check + jest
src must stay compatible with Node 10 and webpack 3 (acorn 5): ESLint parses it
as ES2017 (no object spread, ?., ??), and
http_ece is pinned to 1.1.x (1.2 needs Node >= 15.7 for base64url).
Documentation
- docs/USAGE.md — usage guide (Vietnamese)
- docs/CHANGES_1.2.0.md — 1.2.0: built-in HTTP client instead of
request - docs/CHANGES_1.1.0.md — 1.1.0: refactor, behaviour compatibility
- docs/KNOWN_ISSUES.md — known issues and technical debt
- docs/PUBLISHING.md — release and publishing security checklist
- CHANGELOG.md
License
MIT