Skip to content

feat(messaging): migrate FCM Web quickstart to FID-based APIs #1080

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hozhng wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(messaging): migrate FCM Web quickstart to FID-based APIs #1080

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 86 additions & 60 deletions messaging/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,128 +1,154 @@
Firebase Cloud Messaging Quickstart
===================================
# Firebase Cloud Messaging Quickstart

The Firebase Cloud Messaging quickstart demonstrates how to:

- Request permission to send app notifications to the user.
- Receive FCM messages using the Firebase Cloud Messaging JavaScript SDK.

Introduction
------------
## Introduction

[Read more about Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/)

Getting Started
---------------
## Getting Started

1. Create your project in the Firebase Console by following [**Step 1: Create a Firebase Project**](https://firebase.google.com/docs/web/setup/#create-firebase-project)
2. Register a web app by following [**Step 2: Register your app with Firebase**](https://firebase.google.com/docs/web/setup/#create-firebase-project).
1. You don't need to add Hosting right now, and you can skip the "Add Firebase SDK" step in the console's "Add Firebase to your web app" flow.
2. Remember to click "Register App" or "Continue to console" at the bottom of the "Add Firebase to your web app" flow.
3. Copy your Firebase config object (from the "Add Firebase to your web app" dialog), and paste it in the `config.ts` file in the messaging directory.
1. You don't need to add Hosting right now, and you can skip the "Add Firebase SDK" step in the console's "Add Firebase to your web app" flow.
2. Remember to click "Register App" or "Continue to console" at the bottom of the "Add Firebase to your web app" flow.
3. Copy your Firebase config object (from the "Add Firebase to your web app" dialog), and paste it in the `config.ts` file in the messaging directory.
3. Open Project and go to **Project settings > Cloud Messaging** and there in the **Web configuration** section click **Generate key pair** button.
4. Copy public key and in the `config.ts` file replace `<YOUR_PUBLIC_VAPID_KEY_HERE>` with your key.
5. You must have the [Firebase CLI](https://firebase.google.com/docs/cli/) installed. If you don't have it install it with `npm install -g firebase-tools` and then configure it with `firebase login`.
6. On the command line run `firebase use --add` and select the Firebase project you have created.

To run the sample app locally during development:

1. Run `npm install` to install dependencies.
2. Run `firebase emulators:start` to start the local Firebase emulators. Note: phone authentication required ReCaptcha verification which does not work with the Firebase emulators. These examples skip connecting to the emulators.
Comment thread
hozhng marked this conversation as resolved.
3. Run `npm run dev` to serve the app locally using Vite
3. Run `npm run dev` to serve the app locally using Vite.
This will start a server locally that serves `index.html` on `http://localhost:5173/index.html`.
4. Click **REQUEST PERMISSION** button to request permission for the app to send notifications to the browser.
5. Use the generated Instance ID token (IID Token) to send an HTTP request to FCM that delivers the message to the web application, inserting appropriate values for [`YOUR-SERVER-KEY`](https://console.firebase.google.com/project/_/settings/cloudmessaging) and `YOUR-IID-TOKEN`.
4. Click **REQUEST PERMISSION** button to request permission for the app to send notifications to the browser and register.
5. Use the registered Firebase Installation ID (FID) to send an HTTP request to FCM HTTP v1 API that delivers the message to the web application, inserting appropriate values for `YOUR-PROJECT-ID`, `YOUR-ACCESS-TOKEN`, and `YOUR-FID`.

Running the app using the Firebase CLI:

1. Run `npm install` to install dependencies.
2. Run `npm run build` to build the app using Vite.
3. Run `firebase emulators:start` to start the local Firebase emulators. Note: phone authentication required ReCaptcha verification which does not work with the Firebase emulators. These examples skip connecting to the emulators.
4. In your terminal output, you will see the "Hosting" URL. By default, it will be `127.0.0.1:5002`, though it may be different for you.
5. Navigate in your browser to the URL output by the `firebase emulators:start` command.
6. Click **REQUEST PERMISSION** button to request permission for the app to send notifications to the browser.
7. Use the generated Instance ID token (IID Token) to send an HTTP request to FCM that delivers the message to the web application, inserting appropriate values for [`YOUR-SERVER-KEY`](https://console.firebase.google.com/project/_/settings/cloudmessaging) and `YOUR-IID-TOKEN`.
7. Use the registered Firebase Installation ID (FID) to send an HTTP request to FCM HTTP v1 API that delivers the message to the web application, inserting appropriate values for `YOUR-PROJECT-ID`, `YOUR-ACCESS-TOKEN`, and `YOUR-FID`.

To deploy the sample app to production:

1. Run `firebase deploy`.
This will deploy the sample app to `https://<project_id>.firebaseapp.com`.


NOTE: If your payload has a `notification` object, `setBackgroundMessageHandler` will not trigger. Read [here](https://firebase.google.com/docs/cloud-messaging/js/receive) for more information.
Comment thread
hozhng marked this conversation as resolved.
NOTE: If your payload has a `notification` object, `onBackgroundMessage` will not trigger. Read [here](https://firebase.google.com/docs/cloud-messaging/js/receive) for more information.

### HTTP

```
POST /fcm/send HTTP/1.1
POST /v1/projects/YOUR-PROJECT-ID/messages:send HTTP/1.1
Host: fcm.googleapis.com
Authorization: key=YOUR-SERVER-KEY
Content-Type: application/json
Authorization: Bearer YOUR-ACCESS-TOKEN
Content-Type: application/json; UTF-8

{
"notification": {
"title": "Portugal vs. Denmark",
"body": "5 to 1",
"icon": "firebase-logo.png",
"click_action": "http://localhost:8081"
},
"to": "YOUR-IID-TOKEN"
"message": {
"fid": "YOUR-FID",
"notification": {
"title": "Portugal vs. Denmark",
"body": "5 to 1"
},
"webpush": {
"notification": {
"icon": "/firebase-logo.png"
}
}
}
}
```

### Fetch

```js
var key = 'YOUR-SERVER-KEY';
var to = 'YOUR-IID-TOKEN';
var notification = {
'title': 'Portugal vs. Denmark',
'body': '5 to 1',
'icon': 'firebase-logo.png',
'click_action': 'http://localhost:8081'
var projectId = 'YOUR-PROJECT-ID';
var accessToken = 'YOUR-ACCESS-TOKEN';
var fid = 'YOUR-FID';
var message = {
fid: fid,
notification: {
title: 'Portugal vs. Denmark',
body: '5 to 1',
},
webpush: {
notification: {
icon: '/firebase-logo.png',
},
},
};

fetch('https://fcm.googleapis.com/fcm/send', {
'method': 'POST',
'headers': {
'Authorization': 'key=' + key,
'Content-Type': 'application/json'
fetch(
'https://fcm.googleapis.com/v1/projects/' + projectId + '/messages:send',
{
method: 'POST',
headers: {
Authorization: 'Bearer ' + accessToken,
'Content-Type': 'application/json; UTF-8',
},
body: JSON.stringify({
message: message,
}),
},
'body': JSON.stringify({
'notification': notification,
'to': to
)
.then(function (response) {
return response.json();
})
.then(function (data) {
console.log(data);
})
}).then(function(response) {
console.log(response);
}).catch(function(error) {
console.error(error);
})
.catch(function (error) {
console.error(error);
});
```

### cURL

```
curl -X POST -H "Authorization: key=YOUR-SERVER-KEY" -H "Content-Type: application/json" -d '{
"notification": {
"title": "Portugal vs. Denmark",
"body": "5 to 1",
"icon": "firebase-logo.png",
"click_action": "http://localhost:8081"
},
"to": "YOUR-IID-TOKEN"
}' "https://fcm.googleapis.com/fcm/send"
curl -X POST -H "Authorization: Bearer YOUR-ACCESS-TOKEN" -H "Content-Type: application/json; UTF-8" -d '{
"message": {
"fid": "YOUR-FID",
"notification": {
"title": "Portugal vs. Denmark",
"body": "5 to 1"
},
"webpush": {
"notification": {
"icon": "/firebase-logo.png"
}
}
}
}' "https://fcm.googleapis.com/v1/projects/YOUR-PROJECT-ID/messages:send"
```

### App focus

When the app has the browser focus, the received message is handled through
the `onMessage` callback in `index.html`. When the app does not have browser
focus then the `setBackgroundMessageHandler` callback in `firebase-messaging-sw.js`
the `onMessage` callback in `main.ts`. When the app does not have browser
focus then the `onBackgroundMessage` callback in `firebase-messaging-sw.js`
is where the received message is handled.

The browser gives your app focus when both:

1. Your app is running in the currently selected browser tab.
2. The browser tab's window currently has focus, as defined by the operating system.

Support
-------
## Support

https://firebase.google.com/support/

License
-------
## License

© Google, 2016. Licensed under an [Apache-2](../LICENSE) license.
27 changes: 14 additions & 13 deletions messaging/firebase-messaging-sw.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
// Import and configure the Firebase SDK
// These scripts are made available when the app is served or deployed on Firebase Hosting
// If you do not serve/host your project using Firebase Hosting see https://firebase.google.com/docs/web/setup
importScripts('/__/firebase/9.2.0/firebase-app-compat.js');
importScripts('/__/firebase/9.2.0/firebase-messaging-compat.js');
importScripts('/__/firebase/12.17.1/firebase-app-compat.js');
importScripts('/__/firebase/12.17.1/firebase-messaging-compat.js');
importScripts('/__/firebase/init.js');

const messaging = firebase.messaging();

/**
* Here is is the code snippet to initialize Firebase Messaging in the Service
* Here is the code snippet to initialize Firebase Messaging in the Service
* Worker when your app is not hosted on Firebase Hosting.

// Give the service worker access to Firebase Messaging.
// Note that you can only use Firebase Messaging here. Other Firebase libraries
// are not available in the service worker.
importScripts('https://www.gstatic.com/firebasejs/9.2.0/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/9.2.0/firebase-messaging-compat.js');
importScripts('https://www.gstatic.com/firebasejs/12.17.1/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/12.17.1/firebase-messaging-compat.js');

// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
Expand All @@ -36,23 +36,24 @@ const messaging = firebase.messaging();
const messaging = firebase.messaging();
**/


// If you would like to customize notifications that are received in the
// background (Web app is closed or not in browser focus) then you should
// implement this optional method.
// Keep in mind that FCM will still show notification messages automatically
// Keep in mind that FCM will still show notification messages automatically
// and you should use data messages for custom notifications.
// For more info see:
// For more info see:
// https://firebase.google.com/docs/cloud-messaging/concept-options
messaging.onBackgroundMessage(function(payload) {
console.log('[firebase-messaging-sw.js] Received background message ', payload);
messaging.onBackgroundMessage(function (payload) {

@Doris-Ge Doris-Ge Sep 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you help fix the current bug that a notification send would result in two notifications? To fix it, you could check if the payload has a notification body and return early if so.

Image

console.log(
'[firebase-messaging-sw.js] Received background message ',
payload,
);
// Customize notification here
const notificationTitle = 'Background Message Title';
const notificationOptions = {
body: 'Background Message body.',
icon: '/firebase-logo.png'
icon: '/firebase-logo.png',
};

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