FCM 消息简介

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"
      }
    }
  }
}

如需了解有关设置消息优先级的针对具体平台的详细信息，请参阅以下文章：

生命攸关的应用场景

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 错误。