消息的行为会有所不同,具体取决于页面是在前台(有焦点),还是在后台,隐藏在其他选项卡后面,还是完全关闭。在所有情况下,页面都必须处理onMessage
回调,但在后台情况下,您可能还需要处理onBackgroundMessage
或配置显示通知以允许用户将您的 Web 应用程序带到前台。
应用状态 | 通知 | 数据 | 两个都 |
---|---|---|---|
前景 | onMessage | onMessage | onMessage |
背景(服务工作者) | onBackgroundMessage (显示通知自动显示) | onBackgroundMessage | onBackgroundMessage (显示通知自动显示) |
JavaScript快速入门示例演示了接收消息所需的所有代码。
当您的 Web 应用程序位于前台时处理消息
为了接收onMessage
事件,您的应用必须在firebase-messaging-sw.js
中定义 Firebase 消息传递服务工作者。或者,您可以通过getToken(): Promise<string>
向 SDK 提供现有的服务工作者。
Web version 9
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 version 8
// 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.js'); importScripts('https://www.gstatic.com/firebasejs/9.2.0/firebase-messaging.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 version 9
// 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 version 8
// 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); // ... });
当您的网络应用程序在后台时处理消息
应用程序在后台时收到的所有消息都会触发浏览器中的显示通知。您可以在来自您的应用程序服务器的发送请求中或使用客户端上的服务工作者逻辑为此通知指定选项,例如标题或点击操作。
在发送请求中设置通知选项
对于从应用服务器发送的通知消息,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 处理通知。
有关通知消息和数据消息之间差异的说明,请参阅消息类型。
在服务工作者中设置通知选项
对于数据消息,您可以在服务工作者中设置通知选项。首先,在服务工作者中初始化您的应用程序:
Web version 9
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 version 8
// 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.js'); importScripts('https://www.gstatic.com/firebasejs/9.2.0/firebase-messaging.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 firebase-messaging-sw.js
onBackgroundMessage
在此示例中,我们创建了一个带有标题、正文和图标字段的通知。
Web version 9
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 version 8
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 的推送消息,您可能已经阅读了关于什么是好的通知的广泛指南。对于通过 FCM for Web 发送通知的开发人员来说,最重要的考虑因素是准确性和相关性。以下是一些使您的通知准确且相关的具体建议:
- 使用图标字段发送有意义的图像。对于许多用例,这应该是您的用户可以立即识别的公司或应用程序徽标。或者,对于聊天应用程序,它可能是发送用户的个人资料图像。
- 使用标题字段来表达消息的准确性质。例如,“Jimmy replyed”比“New message”传达的信息更准确。不要将这个宝贵的空间用于您的公司或应用程序名称 - 为此目的使用图标。
- 不要使用通知标题或正文来显示您的网站名称或域名;通知已包含您的域名。
- 添加
fcm_options.link
,通常用于将用户链接回您的网络应用程序并将其置于浏览器中。在极少数情况下,您需要传达的所有信息都可以放入通知中,您可能不需要链接。