Naar console

向后台应用发送测试消息

如需着手使用 FCM,可构建最简单的使用场景:当应用在某位用户的设备后台运行时,向该设备发送一条通知消息。本页面列出了完成上述目标所需的从设置到验证的所有步骤。如果您已针对 FCM 设置了 JavaScript 客户端应用,以下的一些步骤您可能已经完成了。

设置 SDK

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

请求接收通知的权限

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 服务器端 API 来获取有关订阅的信息

发送测试通知消息

  1. 在目标设备上安装并运行该应用。

  2. 确保应用在设备的后台中运行。

  3. 打开通知编辑器,然后选择新建通知

  4. 输入消息内容。

  5. 选择发送测试消息

  6. 在标签为添加 FCM 注册令牌的字段中,输入您在本指南上一部分获得的注册令牌。

  7. 点击测试

在您点击测试后,目标客户端设备(在后台中运行应用)应该会在浏览器中接收到通知。

将 Web 推送属性添加到通知负载

借助 HTTP v1 API,您可以将其他通知选项指定为包含 Web Notification API 中任何有效属性的 JSON 对象。此对象中的 titlebody 字段(如果存在)会替换等效的 google.firebase.fcm.v1.Notification.titlegoogle.firebase.fcm.v1.Notification.body 字段。

HTTP POST 请求

POST https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1

Content-Type: application/json
Authorization: Bearer ya29.ElqKBGN2Ri_Uz...PbJ_uNasm

{
  "message": {
    "token" : <token of destination app>,
    "notification": {
      "title": "FCM Message",
      "body": "This is a message from FCM"
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      },
      "notification": {
        "body": "This is a message from FCM to web",
        "requireInteraction": "true",
        "badge": "/badge-icon.png"
      }
    }
  }
}

通过此请求,目标 Web 客户端(包括在 Android 上运行的受支持的浏览器)将收到高优先级的通知消息,并在用户与其互动之前一直保持有效状态。它包含以下字段:

  • 标题:FCM 消息
  • 正文:从 FCM 发送至 Web 的消息
  • RequireInteraction:true
  • 标志:/badge-icon.png

Android 和 iOS 原生应用(Web 替换设置不适用于这些应用)将收到普通优先级的通知消息,其中包含以下字段:

  • 标题:FCM 消息
  • 正文:从 FCM 发送的消息

请注意,目前仅有部分浏览器支持 RequireInteraction。开发者应查看 Web Notification API 规范以验证平台和浏览器的支持情况。

cURL

curl -X POST -H "Authorization: Bearer ya29.ElqKBGN2Ri_Uz...PbJ_uNasm" -H "Content-Type: application/json" -d '{
  "message": {
    "notification": {
      "title": "FCM Message",
      "body": "This is a message from FCM"
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      },
      "notification": {
        "body": "This is a message from FCM to web",
        "requireInteraction": "true",
        "badge": "/badge-icon.png"
      }
    }
  },
  "token": "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
  }
}' "https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send"

HTTP 响应

{
    "name": "projects/myproject-b5ae1/messages/0:1500415314455276%31bd1c9631bd1c98"
}

请参阅构建应用服务器发送请求以详细了解 FCM 消息。

后续步骤

向前台应用发送消息

向在后台运行的应用成功发送通知消息后,您可参阅在 JavaScript 客户端中接收消息,尝试向前台应用发送消息。

除通知消息之外的其他功能

如果除了通知消息之外,您还要向应用添加其他更高级的行为,请参阅以下内容: