在 JavaScript 客户端中接收消息

消息的行为取决于页面是位于前台（焦点所在）、后台、隐藏在其他标签页后，还是完全关闭。无论哪种情况，页面都必须处理 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);
messaging_init_in_sw.js

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();
service-worker.js

当您的应用位于前台时（用户当前正在查看您的网页），您可以直接在页面中接收数据和通知载荷。

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);
  // ...
});
messaging_receive_message.js

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);
  // ...
});
index.js

在 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);
messaging_init_in_sw.js

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();
service-worker.js

如需设置选项，请在 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);
});
messaging_on_background_message.js

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);
});
service-worker.js

通知的最佳做法

如果您熟悉 Web 推送消息传递，那么您可能已阅读了有关优秀通知需要具备的要素的一般准则。如果开发者通过 Web 版 FCM 发送通知，那么精确率和相关性就是最重要的因素。这里是一些具体建议，可帮助您确保通知的准确性和相关性：

  • 使用图标字段发送有意义的图片。在许多使用情形中，这类图片应该是用户能立即辨认的公司徽标或应用徽标。对于聊天应用，可以考虑使用发送消息的用户的个人资料图片。
  • 使用标题字段表达消息的确切性质。例如，使用“吉米回复了”比使用“新消息”所传达的信息更准确。不要让您的公司名称或应用名称占用这个宝贵位置，如果需要，请使用图标。
  • 不要使用通知标题或正文来显示您的网站名称或网域，通知已包含您的域名。
  • 添加 fcm_options.link，这通常用于将用户链接回您的 Web 应用，并将应用调到前台（成为浏览器中的焦点）。在极少数情况下，您需要传达的所有信息都可以放在通知中，此时可能就不需要链接了。