push-receiver-v2

A library to subscribe to GCM/FCM and receive notifications within a node process. v2 is compatible with the latest FCM registration endpoints.

The original push-receiver FCM registration endpoint has been deprecated and removed as of June 20, 2024.

When should I use push-receiver-v2 ?

• I want to receive push notifications sent using Firebase Cloud Messaging in a NodeJS application.
• I want to communicate with a node process/server using Firebase Cloud Messaging infrastructure.

When should I not use push-receiver-v2 ?

• I want to send push notifications (use the firebase SDK instead)
• My application is running on a FCM supported platform (Android, iOS, Web).

Install

npm i -S push-receiver-v2

Requirements

• Node v24.18.0
• Firebase apiKey, appID, and projectID to receive notification

Usage

const { register, listen } = require('push-receiver-v2');

// Firebase config
const config = {
  firebase: {
    apiKey: "XXxxXxX0x0x-Xxxx0-X0Xxxxx_0xxXx_XX0xXxX",
    appID: "1:000000000000:android:xxx0xxxx0000x000xxx000",
    projectID: "the-app-name"
  },
  vapidKey: '' // optional
};

// First time
// Register to GCM and FCM
const credentials = await register(config); // You should call register only once and then store the credentials somewhere
storeCredentials(credentials) // Store credentials to use it later
const fcmToken = credentials.fcm.token; // Token to use to send notifications
sendTokenToBackendOrWhatever(fcmToken);

// Next times
const credentials = getSavedCredentials() // get your saved credentials from somewhere (file, db, etc...)
// persistentIds is the list of notification ids received to avoid receiving all already received notifications on start.
const persistentIds = getPersistentIds() || [] // get all previous persistentIds from somewhere (file, db, etc...)
await listen({ ...credentials, persistentIds}, onNotification);

// Called on new notification
function onNotification({ notification, persistentId }) {
  // Update list of persistentId in file/db/...
  updatePersistentIds([...persistentIds, persistentId]);
  // Do someting with the notification
  display(notification)
}

Test notification

To send a test notification through the FCM HTTP v1 API, pass an OAuth 2 access token, Firebase project ID, and FCM registration token to the provided script:

npm run send -- --accessToken="<FCM_ACCESS_TOKEN>" --projectID="<FIREBASE_PROJECT_ID>" --token="<FCM_TOKEN>"

Development

Use the pinned Node release and install dependencies from package-lock.json:

nvm use
npm ci
npm run lint
npm test

The default test suite is offline and does not require Firebase credentials.

The live notification integration suite uses the FCM HTTP v1 API. Set FIREBASE_CONFIG to a JSON object containing firebase.apiKey, firebase.appID, and firebase.projectID, and provide an OAuth 2 access token:

FIREBASE_CONFIG='{"firebase":{"apiKey":"...","appID":"...","projectID":"..."},"vapidKey":"..."}' \
FCM_ACCESS_TOKEN="..." \
npm run test:integration

Without both environment variables, the integration tests are reported as skipped.

Acknowledgements

• push-receiver for the original implementation.
• Aracna FCM for the latest FCM registration endpoints.