Naar console

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

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

只有通过 HTTPS 提供的页面才支持 FCM SDK。这是由于该 SDK 使用 Service Worker,而 Service Worker 只能在 HTTPS 网站上使用。如果您需要一个提供程序,我们建议您使用 Firebase 托管在您自己的网域中免费托管 HTTPS 网站。

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

将 Firebase 添加到您的 JavaScript 项目

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

如果您目前使用的是 Web 版 FCM,并希望升级到 SDK 6.7.0 或更高版本,则必须在 Google Cloud Console 中为您的项目启用 FCM Registration API。启用 API 时,请务必使用您用于 Firebase 的同一 Google 帐号登录到 Cloud Console,并且务必选择正确的项目。默认情况下,添加 FCM SDK 的新项目会启用此 API。

为 FCM 配置 Web 凭据

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

生成新的密钥对

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

导入现有的密钥对

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

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

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

检索消息传递对象

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

在应用中配置 Web 凭据

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

// 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 来获取有关订阅的信息

后续步骤

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