Firebase Cloud Messaging (FCM) 提供了众多消息传递选项和功能。本页中的内容旨在帮助您了解不同类型的 FCM 消息以及您可以将其用于哪些目的。
包含可选数据载荷的通知消息
无论是通过编程方式还是通过 Firebase 控制台发送通知消息，您都可以在消息中包含由自定义键值对组成的可选载荷。在 Notifications Composer 中，使用高级选项中的自定义数据字段。
接收同时包含通知载荷和数据载荷的消息时，应用的行为取决于应用是在后台还是前台运行，特别是在接收时应用是否处于活跃状态。
- 在后台运行时，应用会在通知面板中接收通知载荷，且仅在用户点按通知时处理数据载荷。
- 在前台运行时，您的应用将会接收一个提供两种载荷的消息对象。
以下是包含 notification 键和 data 键的 JSON 格式的消息：
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"title":"Portugal vs. Denmark",
"body":"great match!"
},
"data" : {
"Nick" : "Mario",
"Room" : "PortugalVSDenmark"
}
}
}递送选项
FCM 为发送到 Android 设备的消息提供了一组特定的递送选项，并允许在 Apple 平台和 Web 上使用类似的选项。例如，Android 通过 FCM 的 collapse_key 来支持“可折叠”消息行为，而 Apple 通过 apns-collapse-id，JavaScript/Web 通过 Topic 来支持该行为。如需了解详情，请参阅本节和相关参考文档中的说明。
设置消息的优先级
下行消息传递优先级有两种：普通优先级和高优先级。普通优先级和高优先级的消息传递方式如下（具体行为在不同的平台中略有差异）：
普通优先级。 应用在前台运行时，普通优先级消息会被立即传递。当应用在后台运行时，消息传递可能会延迟。如果是对时间不太敏感的消息（例如新电子邮件通知、使界面保持同步或在后台同步应用数据），建议您选择普通传递优先级。
高优先级。即使设备处于低电耗模式，FCM 也会立即尝试传递高优先级消息。 高优先级消息适用于对时间敏感的用户可见内容。
以下是一条普通优先级消息的示例，该消息通过 FCM HTTP v1 协议发送，用于通知杂志订阅者有新内容可以下载：
{
"message":{
"topic":"subscriber-updates",
"notification":{
"body" : "This week's edition is now available.",
"title" : "NewsMagazine.com",
},
"data" : {
"volume" : "3.21.15",
"contents" : "http://www.news-magazine.com/world-week/21659772"
},
"android":{
"priority":"normal"
},
"apns":{
"headers":{
"apns-priority":"5"
}
},
"webpush": {
"headers": {
"Urgency": "high"
}
}
}
}如需了解有关设置消息优先级的针对具体平台的详细信息，请参阅以下文章：
- APNs 文档
- 设置和管理消息优先级 (Android)
- Web 推送消息的紧急程度
生命攸关的应用场景
FCM API 并非专为紧急警报或其他高风险活动而设计，在这类活动中，这些 API 的使用或故障可能会导致死亡、人身伤害或环境破坏（例如核设施运营、空中交通管制或生命维持系统）。《服务条款》的第 4 条 a.7 款明确禁止这类使用。您需要自行负责管理应用是否遵守这些条款，并对因违反这些条款而造成的任何损害负责。Google“按原样”提供 API，并保留以任何理由随时停止提供 API 或其任何部分或功能，或是停止您对其的访问权限的权利，而不对您或您的用户承担任何责任或其他义务。
设置消息的有效期
FCM 通常会在消息发出之后马上进行传递。但是，也有一些例外情况。例如，如果在 Android 平台上，设备有可能处于关闭、离线或不可用状态。 FCM 可能会有意地延迟消息传递，以防止应用消耗过多资源和对电池续航时间产生不良影响。
在这种情况下，FCM 会存储消息，等到可行时立即发送。尽管大多数情况下这样做都没什么问题，但有些应用可能永远不会传递延迟消息。举例来说，如果消息是来电或视频聊天通知，则它仅在通话终止之前的这段较短时间内有意义。或者，如果消息是活动邀请，那么如果在活动结束后才收到消息，它将毫无用处。
在 Android 和 Web/JavaScript 上，您可以指定消息的最长有效期。此值必须是介于 0 至 2,419,200 秒（28 天）之间的一段持续时间，其对应于 FCM 存储并尝试传递消息的最长时间期限。不含此字段的请求默认为最长期限（四周）。
以下是此功能的一些可能用途：
- 视频聊天来电
- 即将到期的邀请事件
- 日历活动
指定消息有效期的另一个好处是 FCM 不会对存留时间值为 0 秒的消息应用可折叠消息节流功能。FCM 会尽力处理必须现在传递、过时无效的消息。请留意，time_to_live 值为 0 表示不能立即递送的邮件会被舍弃。不过，由于此类消息不会被存储，因此可以为发送通知消息提供最佳延时。
以下是包含 TTL 的请求示例：
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"data":{
"Nick" : "Mario",
"body" : "great match!",
"Room" : "PortugalVSDenmark"
},
"apns":{
"headers":{
"apns-expiration":"1604750400"
}
},
"android":{
"ttl":"4500s"
},
"webpush":{
"headers":{
"TTL":"4500"
}
}
}
}消息的有效期
当应用服务器向 FCM 发布消息并收到返回的消息 ID 时，并不意味着消息已传递至设备，而是表示其获准传递。消息在获准传递后的行为取决于很多因素。
在理想状态下，如果设备已连接至 FCM，屏幕处于开启状态且没有节流限制，那么消息将被立即传递。
如果设备已连接但是处于低电耗模式，则 FCM 将存储低优先级的消息，直到设备不再处于低电耗模式为止。这是 collapse_key 标志发挥作用的时候：如果已存储有一条含有相同折叠键（和注册令牌）的消息，且该消息正等待传递，则旧消息将被舍弃，新消息将取代其位置（即，旧消息将被新消息折叠起来）。但是，如果未设置折叠键，则新消息和旧消息都将被存储下来供以后传递。
如果设备未连接至 FCM，则消息将被存储，直至建立连接（再次遵循折叠键规则）。建立连接后，FCM 会将所有待处理消息传递到设备。如果设备不再建立连接（例如使用了恢复出厂设置），则消息最终会超时，且将被从 FCM 存储中舍弃。除非设置了 time_to_live 标志，否则默认的超时时间为四个星期。
如需更深入地了解消息的传递情况：
如需详细了解 Android 或 Apple 平台上的消息传递，请参阅 FCM 报告信息中心，其中记录了在 Apple 和 Android 设备上发送和打开的消息数量，以及 Android 应用的“展示次数”（用户看到的通知条数）数据。
对于启用了直接通道消息传递的 Android 设备，如果设备已有一个多月未连接到 FCM，FCM 仍然会接受消息，但会立即将其舍弃。如果设备在您向其发送最后一条数据消息后的四个星期内建立连接，您的客户端会收到 onDeletedMessages() 回调。之后，应用可以正常处理该状况，一般情况下会请求与应用服务器进行一次完全同步。
最后，当 FCM 尝试向设备传递消息，而应用已被卸载时，FCM 将立刻舍弃该消息并废弃注册令牌。其后尝试向该设备发送消息将导致 NotRegistered 错误。
凭据
根据要实现的 FCM 功能的不同，您可能需要下列来自 Firebase 项目的凭据：
| 项目 ID | 您的 Firebase 项目的唯一标识符，用于向 FCM v1 HTTP 端点发出请求。您可以在 Firebase 控制台设置窗格中找到该值。 |
| 注册令牌 | 用于标识每个客户端应用实例的唯一令牌字符串。 单一设备消息传递和设备组消息传递需要注册令牌。请注意，注册令牌必须保密。 |
| 发送者 ID | 您在创建 Firebase 项目时系统创建的唯一数字值，可在 Firebase 控制台设置窗格的“Cloud Messaging”标签页找到。发送者 ID 用于标识可以向客户端应用发送消息的每个发送者。 |
| 访问令牌 | 一个只在短时间内有效的 OAuth 2.0 令牌，用于对发送到 HTTP v1 API 的请求进行授权。此令牌与属于您的 Firebase 项目的服务账号相关联。如需创建和轮替访问令牌，请按照向发送请求提供授权中所述的步骤操作。 |