在 JavaScript 客户端中接收消息

消息的行为取决于相应页面的状态:页面位于前台(获得焦点)、位于后台、隐藏在其他标签页后,还是完全关闭。无论哪种情况,页面都必须处理 onMessage 回调函数;但当页面位于后台时,您可能还需要处理 setBackgroundMessageHandler 或进行配置以显示通知,让用户能够将您的网页应用放到前台。

应用状态 通知 数据 两者
前台 onMessage onMessage onMessage
后台 (Service Worker) SDK 显示的通知 setBackgroundMessageHandler SDK 显示的通知

JavaScript 快速入门示例演示了接收消息所需的所有代码。

在网页应用位于前台时处理消息

为接收 onMessage 事件,您的应用必须在 firebase-messaging-sw.js 中定义 Firebase 消息传递 Service Worker。或者,您也可以使用 useServiceWorker 指定一个现有的 Service Worker。

// 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/4.8.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in the
// messagingSenderId.
firebase.initializeApp({
  'messagingSenderId': 'YOUR-SENDER-ID'
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

当您的应用位于前台时(用户当前正在查看您的网页),您可以直接在页面中接收数据和通知有效负载。

// 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.setBackgroundMessageHandler` handler.
messaging.onMessage(function(payload) {
  console.log('Message received. ', payload);
  // ...
});

在网页应用位于后台时处理消息

当应用位于后台时,收到的所有消息都会导致在浏览器中显示通知。您可以在从应用服务器发送请求时指定用于此通知的选项(如标题或点击操作),也可以在客户端中使用 Service Worker 进行指定。

在发送请求中设置通知选项

对于从应用服务器发送的通知消息,FCM JavaScript API 支持 click_action 键。通常情况下,此键会被设置在网页应用的某一页面中,以便在用户点击通知时将应用带到前台。

https://fcm.googleapis.com/fcm/send
Content-Type: application/json
Authorization: key=AIzaSyC...akjgSX0e4

{ "notification": {
    "title": "Background Message Title",
    "body": "Background message body",
    "click_action" : "https://dummypage.com"
  },

  "to" : "eEz-Q2sG8nQ:APA91bHJQRT0JJ..."

}

由于数据消息不支持 click_action,因此我们建议您在所有数据消息中添加通知有效负载。或者,您也可以使用 Service Worker 处理通知。

如需详细了解通知消息与数据消息之间的区别,请参阅消息类型

在 Service Worker 中设置通知选项

不管是通知消息还是数据消息,您都可以在 Service Worker 中设置通知选项。首先,在 Service Worker 中初始化您的应用:

// 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/4.8.1/firebase-app.js');
importScripts('https://www.gstatic.com/firebasejs/4.8.1/firebase-messaging.js');

// Initialize the Firebase app in the service worker by passing in the
// messagingSenderId.
firebase.initializeApp({
  'messagingSenderId': 'YOUR-SENDER-ID'
});

// Retrieve an instance of Firebase Messaging so that it can handle background
// messages.
const messaging = firebase.messaging();

要设置选项,请调用 firebase-messaging-sw.js 中的 setBackgroundMessageHandler。在本示例中,我们设置了针对标题、正文、图标和点击操作的选项。

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

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

通知的最佳做法

如果您熟悉网页推送消息传递,那么您可能已阅读了有关好通知因素的宽泛准则。如果开发者通过 FCM 为网页应用发送通知,那么最重要的因素是准确性和相关性。我们提供了一些具体建议,以帮助您确保通知的准确性和相关性:

  • 使用图标字段发送有意义的图片。在许多使用情形中,该图片应该是用户能立即识别的公司徽标或应用徽标。对于聊天应用,它可能是发送消息的用户的个人资料图片。
  • 使用标题字段表达消息的确切性质。例如,“李明回复了”比“新消息”传达的信息更精确。不要让您的公司名称或应用名称占用这个宝贵空间,如果您需要提供公司名称或应用名称,请使用图标。
  • 不要使用通知标题或正文来显示您的网站名称或域名;通知已包含您的域名。
  • 添加 click_action,这一步通常用于将用户链接回您的网页应用,并将应用带到浏览器的焦点。在极少数情况下,您需要传达的所有信息都可以放在通知中,此时您可能就不需要再添加点击操作了。

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面