Set up a JavaScript Firebase Cloud Messaging client app

The FCM JavaScript API lets you receive notification messages in web apps running in browsers that support the Push API. This includes the browser versions listed in this support matrix and Chrome extensions via the Push API.

The FCM SDK is supported only in pages served over HTTPS. This is due to its use of service workers, which are available only on HTTPS sites. If you need a provider, Firebase Hosting is recommended for free HTTPS hosting on your own domain.

To get started with the FCM JavaScript API, you'll need to add Firebase to your web app and add logic to access registration tokens.

Add Firebase to your JavaScript project

If you haven't already, add Firebase to your JavaScript project.

If you are currently using FCM for web and want to upgrade to SDK 6.7.0 or later, you must enable the FCM Registration API for your project in the Google Cloud Console. When you enable the API, make sure you are logged in to Cloud Console with the same Google account you use for Firebase, and make sure to select the correct project. New projects adding the FCM SDK have this API enabled by default.

Configure Web Credentials with FCM

The FCM Web interface uses Web credentials called "Voluntary Application Server Identification," or "VAPID" keys, to authorize send requests to supported web push services. To subscribe your app to push notifications, you need to associate a pair of keys with your Firebase project. You can either generate a new key pair or import your existing key pair through the Firebase Console.

Generate a new key pair

  1. Open the Cloud Messaging tab of the Firebase console Settings pane and scroll to the Web configuration section.
  2. In the Web Push certificates tab, click Generate Key Pair. The console displays a notice that the key pair was generated, and displays the public key string and date added.

Import an existing key pair

If you have an existing key pair you are already using with your web app, you can import it to FCM so that you can reach your existing web app instances through FCM APIs. To import keys, you must have owner-level access to the Firebase project. Import your existing public and private key in base64 URL safe encoded form:

  1. Open the Cloud Messaging tab of the Firebase console Settings pane and scroll to the Web configuration section.
  2. In the Web Push certificates tab, find and select the link text, "import an existing key pair."
  3. In the Import a key pair dialog, provide your public and private keys in the corresponding fields and click Import. The console displays the public key string and date added.

For instructions on how to add the key to your app, see Configure Web credentials in your app. For more information about the format of the keys and how to generate them, see Application server keys.

Retrieve a messaging object

// Retrieve Firebase Messaging object.
const messaging = firebase.messaging();
index.html

Configure Web credentials in your app

The method usePublicVapidKey allows FCM to use the VAPID key credential when sending message requests to different push services. Using the key you generated or imported according to the instructions in Configure Web Credentials with FCM, add it in your code after the messaging object is retrieved:

// Add the public key generated from the console here.
messaging.usePublicVapidKey("BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");

Request permission to receive notifications

The method Notification.requestPermission() from Web Notifications API displays a consent dialog to let users grant your app permission to receive notifications in the browser. If permission is denied, FCM registration token requests result in an error.

Notification.requestPermission().then((permission) => {
  if (permission === 'granted') {
    console.log('Notification permission granted.');
    // TODO(developer): Retrieve an Instance ID token for use with FCM.
    // ...
  } else {
    console.log('Unable to get permission to notify.');
  }
});
index.html

Access the registration token

This section describes how to retrieve the registration token for an app instance, and how to monitor token refresh events. Because the token could be rotated after initial startup, you should monitor token refresh and always retrieve the latest updated registration token.

The registration token may change when:

  • The web app deletes the registration token.
  • The user clears browser data. In this case, call getToken to retrieve the new token.

Retrieve the current registration token

When you need to retrieve the current token, call getToken. This method returns null when permission has not been granted. Otherwise, it returns a token or rejects the promise due to an error.

The messaging service requires a firebase-messaging-sw.js file. Unless you already have a firebase-messaging-sw.js file, create an empty file with that name and place it in the root of your domain before retrieving a token. You can add meaningful content to the file later in the client setup process.

To retrieve the current token:

// Get Instance ID token. Initially this makes a network call, once retrieved
// subsequent calls to getToken will return from cache.
messaging.getToken().then((currentToken) => {
  if (currentToken) {
    sendTokenToServer(currentToken);
    updateUIForPushEnabled(currentToken);
  } else {
    // Show permission request.
    console.log('No Instance ID token available. Request permission to generate one.');
    // Show permission UI.
    updateUIForPushPermissionRequired();
    setTokenSentToServer(false);
  }
}).catch((err) => {
  console.log('An error occurred while retrieving token. ', err);
  showToken('Error retrieving Instance ID token. ', err);
  setTokenSentToServer(false);
});
index.html

Monitor token refresh

The onTokenRefreshcallback fires whenever a new token is generated, so calling getToken in its context ensures that you are accessing a current, available registration token.

// Callback fired if Instance ID token is updated.
messaging.onTokenRefresh(() => {
  messaging.getToken().then((refreshedToken) => {
    console.log('Token refreshed.');
    // Indicate that the new Instance ID token has not yet been sent to the
    // app server.
    setTokenSentToServer(false);
    // Send Instance ID token to app server.
    sendTokenToServer(refreshedToken);
    // ...
  }).catch((err) => {
    console.log('Unable to retrieve refreshed token ', err);
    showToken('Unable to retrieve refreshed token ', err);
  });
});
index.html

After you've obtained the token, send it to your app server and store it using your preferred method. You can use the Instance ID server API to get information about subscriptions

Next steps

After you have completed the setup steps, here are few options for moving forward with FCM for Web (JavaScript):