Mastering Web Push Notifications with React and Firebase Cloud Messaging

Welcome to this comprehensive guide on using Firebase Cloud Messaging(FCM) to deliver push notifications in React applications.

Topics covered in this article

1. General overview of FCM, how it works, and its benefits.

2. Integrating FCM on the front-end side, particularly in React projects.

3. Concepts related to push notifications in the browser and FCM.

4. Common pitfalls and issues that occur while integrating FCM.

5. Tips that can help you save time and integrate FCM as you want in your project.

After completing this guide, you will have a great understanding of FCM and push notifications in general.

Introduction

Push notifications are a crucial feature of modern web apps, enabling users to receive important updates even when they are not using the application, either through application UI or system/browser notifications. These notifications can be sent instantly or scheduled, making them a great way to keep users informed about important updates.

Firebase Cloud Messaging(FCM)

Firebase Cloud Messaging (FCM) is a cross-platform messaging service by Google that allows developers to send notifications and data messages to users on web, mobile, and desktop apps. It enables reliable and efficient real-time communication between the server and client applications.

At a basic level, FCM works as middleware between your backend and frontend applications. On the front end, you need to generate a token called the FCM token using the Firebase package; it will act as a unique identifier for a user within the FCM ecosystem. You generally need to send this token to your backend along with user credentials like userId, etc. Your backend stores this token for the user and then triggers notifications via Firebase’s FCM API whenever an important event occurs. Firebase then identifies the target user, using the FCM token, and sends/pushes those notifications to the intended user.

You can also use FCM to run notification campaigns for all of your users or a subset of users.

Unlike many third-party services, FCM is completely free and has no limits on the number of messages you can send. It is well integrated with Firebase and other Google services and supports multiple platforms(Web, iOS, Android, etc). All these features make it a top choice for developers to implement push notifications.

Prerequisites

1. You must have some experience working with React & NPM (setting up a project & installing packages)

2. You must have a React project set up; if not, you can set up a new project using Vite.

3. A Firebase account, or you must be able to get the required Firebase credentials for your project.

Configuring Firebase In the Console

You need to have an account on Firebase with a project created and FCM enabled for it. If you haven’t, you can create your account on Firebase, create a project, and enable FCM for an application in the project. This whole process is pretty straightforward. Check this video on how to configure FCM in the Firebase console.

These are the required credentials you must have on hand before proceeding any further

/* You can get this entire firebaseConfig object directly from the firebase console */
const firebaseConfig = {
  apiKey: "AIzaSyDyN2WPpgWZAOhD17t9tLQ8s361MfSewaU",
  authDomain: "fcm-demo-bbc2e.firebaseapp.com",
  projectId: "fcm-demo-bbc2e",
  storageBucket: "fcm-demo-bbc2e.firebasestorage.app",
  messagingSenderId: "235530442918",
  appId: "1:235530442918:web:a46d64224f31d03bbffc67",
  measurementId: "G-SQTLY8YPF9"
};

/* You also need a Voluntary Application Server Identification (VAPID) key */
vapidKey : "BG73dq-cpSGRs1oAezHTae4ftxhC1Z87XZGxWS1oukzCs5aD28Wrogg3OXl-QvAz-2eHaIAhTe1bSDRm5DU5ILE"

Setting Up Firebase in React

NOTE: I use a React project setup using Vite for this demo.

1. Install the Firebase package in your project using npm install firebase

2. Create a firebaseConfig.js file in the src folder of your project

Paste this code in your firebaseConfig.js file

import { initializeApp } from "firebase/app";
import { getMessaging, getToken, onMessage } from "firebase/messaging";

const firebaseConfig = {
   apiKey: "AIzaSyDyN2WPpgWZAOhD17t9tLQ8s361MfSewaU",
   authDomain: "fcm-demo-bbc2e.firebaseapp.com",
   projectId: "fcm-demo-bbc2e",
   storageBucket: "fcm-demo-bbc2e.firebasestorage.app",
   messagingSenderId: "235530442918",
   appId: "1:235530442918:web:a46d64224f31d03bbffc67",
   measurementId: "G-SQTLY8YPF9",
};

const firebaseApp = initializeApp(firebaseConfig);
export const messaging = getMessaging(firebaseApp);

// request notification permission only if not already granted
const requestPermission = async () => {
   if (Notification.permission === "granted") return true;
   try {
      const permission = await Notification.requestPermission();
      return permission === "granted";
   } catch (error) {
      console.error("error requesting notification permission", error);
      return false;
   }
};

export const requestFcmToken = async () => {
   const hasPermission = await requestPermission();
   if (!hasPermission) return null;

   // notification permssion must be granted before getting FCM token
   try {
      const token = await getToken(messaging, {
         vapidKey:
            "BG73dq-cpSGRs1oAezHTae4ftxhC1Z87XZGxWS1oukzCs5aD28Wrogg3OXl-QvAz-2eHaIAhTe1bSDRm5DU5ILE",
      });

      if (!token) {
         console.error("No FCM token received");
         return null;
      }

      console.log("FCM Token", token);
      return token;
   } catch (error) {
      console.error("error getting FCM token", error);
      return null;
   }
};

// notification listener that shows an alert when notification is received
onMessage(messaging, (payload) => {
   console.log('foreground message received', payload);
    alert(payload.notification.body);
 });

Make sure to replace the firebaseConfig credentials with the credentials that you get from the Firebase console. Also, you should use environment variables instead of hardcoding the credentials and restrict the usage properly from the Firebase console if integrating in a production application.

Code Explanation

• We import the required functions to interact with Firebase.

• We initialize the firebaseApp instance using the Firebase credentials and creating a messaging utility.

• We have a requestPermission function that requests the required notification permissions from the user. The user must provide the notification permission for Firebase to send notifications.

• We have a requestFcmToken function that gets the FCM token from the firebase for the current user. It gets the token only if the notification permission is granted by the user.

• We also have an onMessage listener that shows the message in an alert. You can also display this message in your application UI, such as in a toast, etc.

Now, as a next step, create a service-worker firebase-messaging-sw.js file in the public directory of your project.

Paste this code in the firebase-messaging-sw.js file. Make sure to replace it with your credentials.

/*These importScripts are used to import Firebase's messaging libraries 
so that the service worker can handle push notifications in the background.*/

importScripts(
   "https://www.gstatic.com/firebasejs/10.7.2/firebase-app-compat.js"
);
importScripts(
   "https://www.gstatic.com/firebasejs/10.7.2/firebase-messaging-compat.js"
);

const config = {
   apiKey: "AIzaSyDyN2WPpgWZAOhD17t9tLQ8s361MfSewaU",
   authDomain: "fcm-demo-bbc2e.firebaseapp.com",
   projectId: "fcm-demo-bbc2e",
   storageBucket: "fcm-demo-bbc2e.firebasestorage.app",
   messagingSenderId: "235530442918",
   appId: "1:235530442918:web:a46d64224f31d03bbffc67",
   measurementId: "G-SQTLY8YPF9",
};

firebase.initializeApp(config);

const messaging = firebase.messaging();

messaging.onBackgroundMessage((payload) => {
   console.log("received background message", payload);
});

We just created a service worker. This file has code that runs in the background, even when your React app isn't open in the browser. The code in the service worker runs separately from the rest of your JavaScript code. That's why we set up Firebase separately in firebase-messaging-sw.js, because a service worker can't directly interact with your other JavaScript code and vice versa. A service worker firebase-messaging-sw.js is registered in the browser once your app loads. It stays active even if your app closes unless the user clears site data or manually unregisters it. You can check active service workers in the browser dev tools under the Application tab.

firebase-messaging-sw.js will show push notifications in the background even if your React application is not running as long as your browser is open. These notifications are shown via your system/browser notifications.

Now, as a next step, paste this code In your App.jsx file.

NOTE: If you are following along and integrating FCM in a production application, just read through the next step you don’t need to paste this code in your App.jsx file. You can retrieve and store the FCM token in a similar way.

import { useEffect, useState } from "react";
import { requestFcmToken } from "./firebaseConfig";

import "./App.css";

function App() {
   const [fcmToken, setFcmToken] = useState(null);
   const isPermissionGranted = Notification.permission === "granted"; // default, denied, granted

   useEffect(() => {
      const getToken = async () => {
         const token = await requestFcmToken();
         setFcmToken(token);
      };
      getToken();
   }, []);


   const handleClick = () => {
      // it will prompt user for notification permission if its not already denied or granted
      Notification.requestPermission();
   };

   return (
      <>
         <h1>FCM Demo</h1>
         <div className="card">
            {!isPermissionGranted ? (
               <button onClick={handleClick}>
                  Notification Permission Required
               </button>
            ) : (
               <p>{fcmToken}</p>
            )}
         </div>
      </>
   );
}

export default App;

Code explanation

• We have a pretty basic App component that shows a Notification Permission Required button when the user hasn’t granted notification permission; otherwise, it gets and shows the user's FCM token. Keep in mind that notification permission must be granted to even get the FCM token.

• When the Notification Permission Required button is clicked, it attempts to ask the user for notification permission. There are three possible states of notification permissions in the browser, namely default, granted and denied . If the user hasn’t denied or granted permission already, clicking the button will prompt the user for notification permissions in a dialog box typically shown on the top left of the browser search bar.

• 

  You can check notification permission programmatically using Notification.permission and show a similar button or warning to ask for permissions in your application UI.

• Once notification permission is allowed, the FCM token for the current user/client will be fetched, and Firebase will automatically cache it.

• In a production application, you generally send this FCM token along with current user credentials to the backend. The backend stores the FCM token for the user and whenever an important event occurs, constructs a notification payload/message and triggers a notification using the FCM token of the user via FCM API. Check out these docs for more on how to integrate FCM on the backend.

If you have followed so far you can run your application in the browser. When your application loads, it will prompt you for notification permission. If it’s not try resetting the notification permission for your application via browser site settings.

Now, we are all set to receive push notifications. Both in our application as well as background notifications via service-worker firebase-messaging-sw.js file. If you have a backend setup for FCM, you can test it by triggering notifications from your backend. For this demo application, we can send push notifications from the Firebase console itself. Check this video on how to send test notifications from the Firebase console.

Now, you must be able to receive background notifications like this that are shown via your system/browser notifications.

And if you were following along, you should be able to get foreground/in-app notifications like this or however you are displaying the in-app notifications.

Common reasons why you might not be getting the Notifications

NOTE: The issues covered below occur primarily on the front-end side. There can also be FCM integration issues on the backend if you are using a backend to trigger notifications.

1. Make sure your Firebase config credentials are correct, especially the VAPID key. Check this video on how to configure Firebase in the console and get your credentials.

2. To get push notifications, you need to allow notifications for the app in your browser and also enable notifications for the browser in your system settings for receiving background notifications. Without these permissions, you won't receive any notifications, and you won't see any error messages, either.

3. Another common error you might get is when you try to get the FCM token before your service worker is registered in the browser.

4. 

   To fix this error, you can update your code to manually register the service worker before trying to get the FCM token. In firebaseConfig.js file add a new function registerServiceWorker like this and use it in the requestFcmToken function, as shown below.

const registerServiceWorker = async () => {
   try {
      const existingRegistration =
         await navigator.serviceWorker.getRegistration();
      if (existingRegistration) {
         console.log("service worker already registered", existingRegistration);
         return existingRegistration;
      }

      // manually register service worker if not already registered
      const newRegistration = await navigator.serviceWorker.register(
         "/firebase-messaging-sw.js" // name of the firebase service worker file in your public directory
      );
      console.log("service worker registered", newRegistration);
      await navigator.serviceWorker.ready;
      return newRegistration;
   } catch (error) {
      console.error("error in service worker registration", error);
      return null;
   }
};

export const requestFcmToken = async () => {
   const hasPermission = await requestPermission();
   if (!hasPermission) return null;

   const registration = await registerServiceWorker();
   if (!registration) return null;

   // notification permission must be granted and service worker registered before getting FCM token
   try {  
      const token = await getToken(messaging, {
         vapidKey:
            "BG73dq-cpSGRs1oAezHTae4ftxhC1Z87XZGxWS1oukzCs5aD28Wrogg3OXl-QvAz-2eHaIAhTe1bSDRm5DU5ILE",
         serviceWorkerRegistration: registration,
      });

      if (!token) {
         console.error("No FCM token received");
         return null;
      }

      console.log("FCM Token", token);
      return token;
   } catch (error) {
      console.error("error getting FCM token", error);
      return null;
   }
};

Code Explanation

We just added registerServiceWorker function that checks if the service worker is registered. If it’s not, it manually registers firebase-messaging-sw.js and returns the registration instance, which is passed to the getToken function when getting FCM token.

Notification Types and Customizing Notifications

Firebase lets you send two types of messages

1. Notification Messages

2. Data Messages

Notification Messages are the type of messages we have received so far in this demo. Firebase can automatically show these types of notifications in the background. You don’t need to do any extra setup apart from setting up firebase credentials in the firebase-messaging-sw.js. In the foreground/in-app, you do need to manually handle it using an onMessage event listener. These types of notifications are best for simple notifications that don’t require processing before displaying.

Data Messages are used to send custom key-value data to the client without displaying a notification automatically. Although you can process the data message in firebase-messaging-sw.js and then show a push notification manually. In the foreground, you also need to handle it manually using an onMessage event listener. These types of notifications are best for sending structured data that needs further processing on the client before showing in a notification.

This is how you can handle Data Messages in onBackgroundMessage listener in the firebase-messaging-sw.js file.

// process and handle data messages in the background and show in a notification
    messaging.onBackgroundMessage((payload) => {
      console.log('received background message', payload);

      const notificationTitle = payload.data?.title || 'New Notification';
      const notificationOptions = {
        body: payload.data?.body || 'You have a new message.',
        icon: payload.data?.icon || '/favicon.ico',
      };

      self.registration.showNotification(notificationTitle, notificationOptions);
    });

Conclusion

💐Congratulations! You have completed this comprehensive guide about push notifications and integrating FCM in React applications. I have tried to cover all aspects of FCM integration and provide lots of context to help you develop a robust understanding of how FCM works. I hope this will be of some help to you.

Stay tuned for more similar articles on front-end development.

Resources - Github repo for the code of this demo application