Otwórz konsolę

设置 JavaScript Firebase 云消息传递客户端应用

借助 FCM JavaScript API,您可以在支持 Push API 的浏览器上运行的 Web 应用中接收通知消息。这包括此支持矩阵中列出的浏览器版本。

您可以使用 HTTP 和 XMPP 应用服务器协议向 JavaScript 客户端发送消息,具体如发送消息中所述。不支持从 Firebase 控制台发送消息。

要开始使用 FCM JavaScript API,您需要将 Firebase 添加到您的网页应用,并添加逻辑以访问注册令牌。

将 Firebase 添加到您的 JavaScript 项目

如果您尚未将 Firebase 添加到您的 JavaScript 项目,请先添加。

配置 FCM 网络凭据

FCM 网络界面使用名为“自主应用服务器标识”(即“VAPID”)密钥的网络凭据来授权向支持的网络推送服务发送请求。要为应用订阅推送通知,您需要将一对密钥与您的 Firebase 项目相关联。您可以生成新的密钥对,也可以通过 Firebase 控制台导入现有的密钥对。

生成新的密钥对

  1. 打开 Firebase 控制台设置窗格中的云消息传递标签页,然后滚动至 Web 配置部分。
  2. 网络推送证书标签中,点击生成密钥对。控制台会显示一则通知,说明已生成密钥对,并且会显示公钥字符串和添加日期。

导入现有的密钥对

如果您有已在网页应用中使用的现有密钥对,则可以将其导入 FCM 中,以便通过 FCM API 访问现有的网页应用实例。要导入密钥,您必须拥有对 Firebase 项目的所有者级访问权限。以 base64 URL 安全编码形式导入现有的公钥和私钥:

  1. 打开 Firebase 控制台设置窗格中的云消息传递标签页,然后滚动至 Web 配置部分。
  2. 网络推送证书标签中,找到并选择链接文本“导入现有密钥对”(import an existing key pair)。
  3. 导入一个密钥对对话框的相应字段中提供公钥和私钥,然后点击导入。控制台会显示公钥字符串和添加日期。

要了解如何将密钥添加到您的应用中,请参阅在应用中配置网络凭据。如需详细了解密钥格式以及如何生成密钥,请参阅应用服务器密钥

配置浏览器以接收消息

您需要添加一个 Web 应用清单,并在其中指定 gcm_sender_id(一个硬编码值,表示 FCM 有权向此应用发送消息)。如果您的应用已经有一个 manifest.json 配置文件,请务必完全如下所示添加浏览器发送者 ID(不要更改这个值):

{
  "gcm_sender_id": "103953800507"
}

检索消息对象

// Retrieve Firebase Messaging object.
const messaging = firebase.messaging();

在应用中配置网络凭据

usePublicVapidKey 方法允许 FCM 在向不同的推送服务发送消息请求时使用 VAPID 密钥凭据。使用根据配置 FCM 网络凭据中的说明生成或导入的密钥,在检索到消息对象后将其添加到代码中:

// Add the public key generated from the console here.
messaging.usePublicVapidKey("BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");

申请接收通知的权限

Web Notifications API 中的 Notification.requestPermission() 方法会显示一个征询用户同意的对话框,让用户向您的应用授予权限,以便在浏览器中接收通知。如果用户拒绝授予权限,FCM 注册令牌请求会导致错误。

Notification.requestPermission().then((permission) => {
  if (permission === 'granted') {
    console.log('Notification permission granted.');
    // TODO(developer): Retrieve an Instance ID token for use with FCM.
    // ...
  } else {
    console.log('Unable to get permission to notify.');
  }
});

获取注册令牌

本部分介绍如何检索应用实例的注册令牌以及如何监控令牌刷新事件。因为令牌可能会在初次启用后发生轮替,所以您应该监控令牌刷新并始终检索最近更新的注册令牌。

注册令牌可能会在发生下列情况时更改:

  • Web 应用删除注册令牌时。
  • 用户清除浏览器数据时。在这种情况下,调用 getToken 可检索新令牌。

检索当前注册令牌

如果需要检索当前令牌,请调用 getToken。当尚未获得授权时,此方法会返回 null。在其他情况下,它会返回一个令牌,或由于出现错误而拒绝该 Promise。

消息传递服务需要一个 firebase-messaging-sw.js 文件。除非您已经有 firebase-messaging-sw.js 文件,否则请创建一个使用该名称的空文件,并在检索令牌之前将该文件放在您网域的根目录中。您可以在后面的客户端设置流程中向该文件添加有意义的内容。

如需检索当前令牌,请参考以下代码:

// Get Instance ID token. Initially this makes a network call, once retrieved
// subsequent calls to getToken will return from cache.
messaging.getToken().then((currentToken) => {
  if (currentToken) {
    sendTokenToServer(currentToken);
    updateUIForPushEnabled(currentToken);
  } else {
    // Show permission request.
    console.log('No Instance ID token available. Request permission to generate one.');
    // Show permission UI.
    updateUIForPushPermissionRequired();
    setTokenSentToServer(false);
  }
}).catch((err) => {
  console.log('An error occurred while retrieving token. ', err);
  showToken('Error retrieving Instance ID token. ', err);
  setTokenSentToServer(false);
});

监控令牌刷新

每当生成新的令牌,系统都会触发 onTokenRefresh 回调函数,因此,在该回调函数的上下文中调用 getToken 可以确保您获取的是当前可用的注册令牌。

// Callback fired if Instance ID token is updated.
messaging.onTokenRefresh(() => {
  messaging.getToken().then((refreshedToken) => {
    console.log('Token refreshed.');
    // Indicate that the new Instance ID token has not yet been sent to the
    // app server.
    setTokenSentToServer(false);
    // Send Instance ID token to app server.
    sendTokenToServer(refreshedToken);
    // ...
  }).catch((err) => {
    console.log('Unable to retrieve refreshed token ', err);
    showToken('Unable to retrieve refreshed token ', err);
  });
});

获取令牌后,将其发送到您的应用服务器,并使用您首选的方法进行存储。您可以使用 Instance ID server API 来获取有关订阅的信息

后续步骤

完成设置步骤后,您可以通过以下几个选项继续了解适用于网页 (JavaScript) 的 FCM: