消息的行为取决于页面是位于前台(焦点所在)、后台、隐藏在其他标签页后,还是完全关闭。无论哪种情况,页面都必须处理 onMessage
回调;当页面位于后台时,您可能还需要处理 onBackgroundMessage
或配置显示通知 (display notification),以便用户将您的 Web 应用调到前台。
应用状态 | 通知 | 数据 | 两者 |
---|---|---|---|
前台 | onMessage |
onMessage |
onMessage |
后台 (Service Worker) | onBackgroundMessage (自动出现显示通知) |
onBackgroundMessage |
onBackgroundMessage (自动出现显示通知) |
JavaScript 快速入门示例演示了接收消息所需的所有代码。
在 Web 应用位于前台时处理消息
为接收 onMessage
事件,您的应用必须在 firebase-messaging-sw.js
中定义 Firebase 消息传递的 Service Worker。或者,您可以通过 getToken(): Promise<string>
向 SDK 提供现有的 Service Worker。
Web
import { initializeApp } from "firebase/app"; import { getMessaging } from "firebase/messaging/sw"; // Initialize the Firebase app in the service worker by passing in // your app's Firebase config object. // https://firebase.google.com/docs/web/setup#config-object const firebaseApp = initializeApp({ apiKey: 'api-key', authDomain: 'project-id.firebaseapp.com', databaseURL: 'https://project-id.firebaseio.com', projectId: 'project-id', storageBucket: 'project-id.appspot.com', messagingSenderId: 'sender-id', appId: 'app-id', measurementId: 'G-measurement-id', }); // Retrieve an instance of Firebase Messaging so that it can handle background // messages. const messaging = getMessaging(firebaseApp);
Web
// 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. // Replace 10.13.2 with latest version of the Firebase JS SDK. importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js'); importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.js'); // Initialize the Firebase app in the service worker by passing in // your app's Firebase config object. // https://firebase.google.com/docs/web/setup#config-object firebase.initializeApp({ apiKey: 'api-key', authDomain: 'project-id.firebaseapp.com', databaseURL: 'https://project-id.firebaseio.com', projectId: 'project-id', storageBucket: 'project-id.appspot.com', messagingSenderId: 'sender-id', appId: 'app-id', measurementId: 'G-measurement-id', }); // Retrieve an instance of Firebase Messaging so that it can handle background // messages. const messaging = firebase.messaging();
当您的应用位于前台时(用户当前正在查看您的网页),您可以直接在页面中接收数据和通知载荷。
Web
// Handle incoming messages. Called when: // - a message is received while the app has focus // - the user clicks on an app notification created by a service worker // `messaging.onBackgroundMessage` handler. import { getMessaging, onMessage } from "firebase/messaging"; const messaging = getMessaging(); onMessage(messaging, (payload) => { console.log('Message received. ', payload); // ... });
Web
// Handle incoming messages. Called when: // - a message is received while the app has focus // - the user clicks on an app notification created by a service worker // `messaging.onBackgroundMessage` handler. messaging.onMessage((payload) => { console.log('Message received. ', payload); // ... });
在 Web 应用位于后台时处理消息
当应用位于后台时,收到的所有消息都会触发浏览器中的显示通知。您可以在来自应用服务器的发送请求 (send request) 中指定用于此通知的选项(如标题或点击操作),也可以使用客户端上的 Service Worker 逻辑来指定。
在发送请求中设置通知选项
对于从应用服务器发送的通知消息,FCM JavaScript API 支持 fcm_options.link
键。通常情况下,此键会被设置在网页应用的某一页面中:
https://fcm.googleapis.com//v1/projects/<YOUR-PROJECT-ID>/messages:send
Content-Type: application/json
Authorization: bearer <YOUR-ACCESS-TOKEN>
{
"message": {
"token": "eEz-Q2sG8nQ:APA91bHJQRT0JJ...",
"notification": {
"title": "Background Message Title",
"body": "Background message body"
},
"webpush": {
"fcm_options": {
"link": "https://dummypage.com"
}
}
}
}
如果链接值指向已在某个浏览器标签页中打开的页面,那么当用户点击通知时,系统会将该标签页调到前台。 如果相应页面尚未打开,那么当用户点击通知时,系统会在一个新标签页中打开该页面。
由于数据消息不支持 fcm_options.link
,因此我们建议您在所有数据消息中都添加通知载荷。或者,您也可以使用 Service Worker 处理通知。
如需详细了解通知消息与数据消息之间的区别,请参阅消息类型。
在 Service Worker 中设置通知选项
对于数据消息,您可以在 Service Worker 中设置通知选项。 首先,在 Service Worker 中初始化您的应用:
Web
import { initializeApp } from "firebase/app"; import { getMessaging } from "firebase/messaging/sw"; // Initialize the Firebase app in the service worker by passing in // your app's Firebase config object. // https://firebase.google.com/docs/web/setup#config-object const firebaseApp = initializeApp({ apiKey: 'api-key', authDomain: 'project-id.firebaseapp.com', databaseURL: 'https://project-id.firebaseio.com', projectId: 'project-id', storageBucket: 'project-id.appspot.com', messagingSenderId: 'sender-id', appId: 'app-id', measurementId: 'G-measurement-id', }); // Retrieve an instance of Firebase Messaging so that it can handle background // messages. const messaging = getMessaging(firebaseApp);
Web
// 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. // Replace 10.13.2 with latest version of the Firebase JS SDK. importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js'); importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.js'); // Initialize the Firebase app in the service worker by passing in // your app's Firebase config object. // https://firebase.google.com/docs/web/setup#config-object firebase.initializeApp({ apiKey: 'api-key', authDomain: 'project-id.firebaseapp.com', databaseURL: 'https://project-id.firebaseio.com', projectId: 'project-id', storageBucket: 'project-id.appspot.com', messagingSenderId: 'sender-id', appId: 'app-id', measurementId: 'G-measurement-id', }); // Retrieve an instance of Firebase Messaging so that it can handle background // messages. const messaging = firebase.messaging();
如需设置选项,请在 firebase-messaging-sw.js
中调用 onBackgroundMessage
。在本示例中,我们将创建一个包含标题、正文和图标字段的通知。
Web
import { getMessaging } from "firebase/messaging/sw"; import { onBackgroundMessage } from "firebase/messaging/sw"; const messaging = getMessaging(); onBackgroundMessage(messaging, (payload) => { 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' }; self.registration.showNotification(notificationTitle, notificationOptions); });
Web
messaging.onBackgroundMessage((payload) => { 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' }; self.registration.showNotification(notificationTitle, notificationOptions); });
通知的最佳做法
如果您熟悉 Web 推送消息传递,那么您可能已阅读了有关优秀通知需要具备的要素的一般准则。如果开发者通过 Web 版 FCM 发送通知,那么精确率和相关性就是最重要的因素。这里是一些具体建议,可帮助您确保通知的准确性和相关性:
- 使用图标字段发送有意义的图片。在许多使用情形中,这类图片应该是用户能立即辨认的公司徽标或应用徽标。对于聊天应用,可以考虑使用发送消息的用户的个人资料图片。
- 使用标题字段表达消息的确切性质。例如,使用“吉米回复了”比使用“新消息”所传达的信息更准确。不要让您的公司名称或应用名称占用这个宝贵位置,如果需要,请使用图标。
- 不要使用通知标题或正文来显示您的网站名称或网域,通知已包含您的域名。
- 添加
fcm_options.link
,这通常用于将用户链接回您的 Web 应用,并将应用调到前台(成为浏览器中的焦点)。在极少数情况下,您需要传达的所有信息都可以放在通知中,此时可能就不需要链接了。