Перейти к консоли

Firebase 云消息传递 XMPP 协议

本文档提供了用于在应用服务器、客户端应用和 Firebase 云消息传递 (FCM) 之间传递消息的 XMPP 语法的参考信息。 您的应用服务器必须连接到这些端点:

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

可用的参数和选项分为以下几个类别:

下行消息语法

本部分将介绍发送下行消息所使用的语法。

下行 XMPP 消息 (JSON)

下表列出了 XMPP JSON 消息的目标、选项和有效负载。

表 1 下行 XMPP 消息 (JSON) 的目标、选项和有效负载。

参数 用法 说明
目标
to 可选,字符串

此参数用于指定消息的接收者。

值可以是设备的注册令牌、设备组的通知键或单个主题(前缀为 /topics/)。要发送到多个主题,可使用 condition 参数。

condition 可选,字符串

此参数指定用于确定消息目标的逻辑条件表达式。

支持的条件:主题,格式为“'yourTopic' in topics”。此值不区分大小写。

支持的运算符:&&||。每个主题消息最多支持两个运算符。

选项
message_id 必选,字符串

此参数可唯一标识 XMPP 连接中的消息。

collapse_key 可选,字符串

此参数用于指定一组可折叠的消息(例如含有 collapse_key: "Updates Available"),以便当恢复传送时只发送最后一条消息。这是为了避免当设备重新上线或退出打盹模式时重复发送过多相同的消息。

消息发送顺序并不固定。

注意:在任意给定时间最多允许 4 个不同的折叠键。这意味着 FCM 可以为每个客户端应用同时存储 4 条不同的消息。如果超出此数量,FCM 将无法保证会保留哪 4 个折叠键。

priority 可选,字符串

设置消息的优先级。有效值包括“normal”(普通)和“high”(高)。在 iOS 中,这些值相当于 APNs 优先级中的 5 级和 10 级。

默认情况下,通知消息以高优先级发送,数据消息以普通优先级发送。普通优先级可减轻客户端应用的电池消耗,除非需要立即传送,否则应使用普通优先级。对于普通优先级消息,应用可能会收到未指定延迟时间的消息。

当以高优先级发送消息时,消息会立即发送,应用可能会显示通知。

content_available 可选,布尔值

在 iOS 中,使用此字段表示 APNs 有效负载中的 content-available。如果发送通知或消息时此字段设为 true,将会唤醒处于非活动状态的客户端应用,且消息将作为静默通知通过 APNs 发送,而不是通过 FCM 连接服务器发送。请注意,APNs 中的静默通知不保证能传送,并且可能受多种因素影响(比如用户开启低电量模式、强制退出应用等)。在 Android 系统上,数据消息默认唤醒应用。Chrome 中目前不支持此功能。

mutable_content 可选,JSON 布尔值

目前仅适用于运行 iOS 10 及更高版本的设备。在 iOS 中,使用此字段表示 APNs 有效负载中的 mutable-content。如果发送通知时此字段设为 true,则可以使用通知服务附加应用信息功能在通知显示之前修改通知的内容。Android 应用和网页应用将忽略此参数。

time_to_live 可选,数字

此参数指定在设备离线的情况下将消息在 FCM 存储中保存多长时间(以秒为单位)。受支持的最长生存时间为 4 周,默认值为 4 周。 如需了解详情,请参阅设置消息的有效期

delivery_receipt_
requested
可选,布尔值

此参数让应用服务器能够请求消息传递的确认。

如果此参数设置为 true,则当设备确认已收到某条特定消息时,FCM 将发送一个送达回执。

注意:发送至 iOS 设备的消息不支持此参数。默认值为 false

dry_run 可选,布尔值

此参数设置为 true 时,开发者可在不实际发送消息的情况下对请求进行测试。

默认值为 false

有效负载
data 可选,对象

此参数用于指定消息有效负载的键值对。

例如,使用 data:{"score":"3x1"}:

在 iOS 中,如果通过 APNs 传递消息,则该参数代表自定义数据字段。如果通过 FCM 传递消息,则该参数将以 AppDelegate application:didReceiveRemoteNotification: 中的键值字典的形式来表示。

在 Android 中,这会导致生成一个名为 score、字符串值为 3x1 的 intent 附加信息 (extra)。

键不能采用保留的字词(“from”或任何以“google”或“gcm”开头的字词)。请勿使用此表中定义的任何字词(例如 collapse_key)。

推荐使用字符串类型的值。您必须将对象中的值或其他非字符串数据类型(例如整数或布尔值)转换成字符串。

notification 可选,对象 此参数用于指定预定义的且用户可见的通知有效负载键值对。如需了解详情,请参阅“通知有效负载支持”。如需详细了解通知消息和数据消息选项,请参阅消息类型。如果为发送到 iOS 设备的消息提供了通知有效负载或者将 content_available 选项设为 true,则消息将通过 APNs 发送,否则消息会通过 FCM 连接服务器发送。

通知有效负载支持

下方各表列出了 iOS 和 Android 中可用于构建通知消息的预定义键。

表 2a. iOS - 通知消息对应的键

参数 用法 说明
title 可选,字符串

通知的标题。

此字段不会在 iOS 手机和平板电脑上显示。

body 可选,字符串

通知的正文。

sound 可选,字符串或字典

设备收到通知时要播放的声音。

用于指定声音文件的字符串,该文件可以位于客户端应用的主软件包中,也可位于应用的数据容器的 Library/Sounds 文件夹中。如需了解详情,请参阅 iOS 开发者库

对于重要通知,请使用包含关键提醒的声音信息的字典。要了解必需的键,请参阅 iOS 开发者库。对于常规通知,请改用声音字符串。

badge 可选,字符串

主屏幕应用图标上的标志值。

如果未指定该值,则标志不会发生更改。

如果该值设为 0,则会移除该标志。

click_action 可选,字符串

与用户点击通知相关的操作。

对应于 APNs 有效负载中的 category

subtitle 可选,字符串

通知的副标题。

body_loc_key 可选,字符串

应用的字符串资源中正文字符串的键,用于将正文文字本地化为用户当前的本地化设置语言。

对应于 APNs 有效负载中的 loc-key

如需了解详情,请参阅有效负载键参考将远程通知的内容本地化

body_loc_args 可选,字符串形式的 JSON 数组

将用于替换 body_loc_key(用来将正文文字本地化为用户当前的本地化设置语言)中的格式说明符的变量字符串值。

对应于 APNs 有效负载中的 loc-args

如需了解详情,请参阅有效负载键参考将远程通知的内容本地化

title_loc_key 可选,字符串

应用的字符串资源中标题字符串的键,用于将标题文字本地化为用户当前的本地化设置语言。

对应于 APNs 有效负载中的 title-loc-key

如需了解详情,请参阅有效负载键参考将远程通知的内容本地化

title_loc_args 可选,字符串形式的 JSON 数组

将用于替换 title_loc_key(用来将标题文字本地化为用户当前的本地化设置语言)中的格式说明符的变量字符串值。

对应于 APNs 有效负载中的 title-loc-args

如需了解详情,请参阅有效负载键参考将远程通知的内容本地化

表 2b. Android - 通知消息对应的键

参数 用法 说明
title 可选,字符串

通知的标题。

body 可选,字符串

通知的正文。

android_channel_id 可选,字符串

通知的渠道 ID(Android O 中的新功能)。

应用必须使用此 ID 创建一个渠道,然后才能收到所有含有此渠道 ID 的通知。

如果您不在请求中发送此渠道 ID,或者如果应用尚未创建所提供的渠道 ID,则 FCM 将使用应用清单文件中指定的渠道 ID。

icon 可选,字符串

通知的图标。

将可绘制资源 myicon 的通知图标设置为 myicon。如果您不在请求中发送此键,则 FCM 将会显示您的应用清单文件中指定的启动器图标。

sound 可选,字符串

设备收到通知时要播放的声音。

可以使用 "default" 或应用中包含的声音资源的文件名。声音文件必须位于 /res/raw/ 中。

tag 可选,字符串

用于替换抽屉式通知栏中现有通知的标识符。

如果未指定此参数,每次请求时将创建一条新的通知。

如果已指定此参数,且已显示带有相同标记的通知,则新通知将替换抽屉式通知栏中的现有通知。

color 可选,字符串

通知的图标颜色,以 #rrggbb 格式来表示。

click_action 可选,字符串

与用户点击通知相关的操作。

如果已指定此参数,则当用户点击通知时,将会启动带有匹配 intent 过滤器的 Activity。

body_loc_key 可选,字符串

应用的字符串资源中正文字符串的键,用于将正文文字本地化为用户当前的本地化设置语言。

如需了解详情,请参阅字符串资源

body_loc_args 可选,字符串形式的 JSON 数组

将用于替换 body_loc_key(用来将正文文字本地化为用户当前的本地化设置语言)中的格式说明符的变量字符串值。

如需了解详情,请参阅格式和样式设置

title_loc_key 可选,字符串

应用的字符串资源中标题字符串的键,用于将标题文字本地化为用户当前的本地化设置语言。

如需了解详情,请参阅字符串资源

title_loc_args 可选,字符串形式的 JSON 数组

将用于替换 title_loc_key(用来将标题文字本地化为用户当前的本地化设置语言)中的格式说明符的变量字符串值。

如需了解详情,请参阅格式和样式设置

表 2c. Web (JavaScript) - 通知消息对应的键

参数 用法 说明
title 可选,字符串

通知的标题。

body 可选,字符串

通知的正文。

icon 可选,字符串

通知图标所对应的网址。

click_action 可选,字符串

与用户点击通知相关的操作。

所有网址值都需要采用 HTTPS。

解读下行 XMPP 消息响应

下表列出了下行 XMPP 消息响应中出现的字段。

表 3 下行消息 XMPP 响应正文。

参数 用法 说明
from 必选,字符串

此参数用于指定此响应的发送者。

该值是客户端应用的注册令牌。

message_id 必选,字符串 此参数可唯一标识 XMPP 连接中的消息。该值是用于唯一标识相关消息的一个字符串。
message_type 必选,字符串

此参数用于指定从 FCM 发送到应用服务器的 acknack 消息。

如果该值设置为 nack,则应用服务器应该查看 errorerror_description 来获取故障信息。

error 可选,字符串 此参数用于指定与下行消息相关的错误。当 message_typenack 时就会设置此参数。如需了解详情,请参见表 4
error_description 可选,字符串 此参数用于提供有关错误的描述性信息。当 message_typenack 时就会设置此参数。

下行消息错误响应代码

下表列出了下行消息的错误响应代码。

表 4 下行消息错误响应代码。

错误 XMPP 代码 建议采取的操作
缺少注册令牌 INVALID_JSON 检查请求中是否包含一个注册令牌(对于纯文本消息,包含在 registration_id 中;对于 JSON 消息,包含在 toregistration_ids 字段中)。
注册令牌无效 BAD_REGISTRATION 检查您传送至服务器的注册令牌的格式。确保它与客户端应用在注册 FCM 时收到的注册令牌相匹配。请勿截断或添加其他字符。
未注册设备 DEVICE_UNREGISTERED 现有注册令牌在很多情况下可能会失效,包括:
  • 客户端应用取消 FCM 注册。
  • 客户端应用被自动取消注册(用户卸载应用时就可能会发生这种情况)。例如,在 iOS 上,APNs 报告称 APNs 令牌无效,可能就属于这种情况。
  • 注册令牌过期(例如 Google 可能决定更新注册令牌,或 iOS 设备的 APNs 令牌已过期)。
  • 客户端应用已更新,但新版本未配置为接收消息。
对于所有这些情况,请从应用服务器中移除此注册令牌,并停止用其发送消息。
发送者不匹配 SENDER_ID_MISMATCH 一个注册令牌与一组特定的发送者相关联。当客户端应用注册 FCM 时,它必须指定允许哪些发送者发送消息。在向客户端应用发送消息时,您应当使用这些发送者 ID 之一。如果您改用其他发送者,则现有的注册令牌将不起作用。
JSON 无效 INVALID_JSON 检查 JSON 消息是否格式正确并且包含有效字段(例如确保传入的数据类型正确无误)。
消息过大 INVALID_JSON 请确保消息中包含的有效负载数据的总大小不超过 FCM 的限制:大多数消息的上限是 4096 字节;如果是主题消息,则上限为 2048 字节。这包括键和值。
数据键无效 INVALID_JSON 检查有效负载数据是否未包含由 FCM 内部使用的键(例如 fromgcm 或任何以 google 为前缀的值)。请注意,FCM 使用的某些单词(例如 collapse_key)也允许在有效负载中使用,在这种情况下,FCM 值会覆盖有效负载值。
生存时间无效 INVALID_JSON 检查 time_to_live 中使用的值是否是表示时间长度(以秒为单位)的整数值,且介于 0 到 2419200(即 4 周)之间。
ACK 消息错误 BAD_ACK 检查 ack 消息是否格式正确,然后重试。如需了解详情,请参见表 6
超时 SERVICE_UNAVAILABLE

服务器无法及时处理请求。重试同一请求,但您必须:

  • 在您的重试机制中实现指数退避(例如,如果等待一秒钟后进行第一次重试,则至少要等待两秒钟再进行下一次重试,然后等待四秒钟,依此类推)。如果您要发送多条消息,请将每条消息分别延迟额外的随机时长,从而避免同时对所有消息发出新的请求。
  • 初始重试延迟应当设为一秒。

注意:导致出现问题的发送者有可能会被列入黑名单。

内部服务器错误 INTERNAL_SERVER_
ERROR
服务器在尝试处理请求时遇到了错误。您可按照“超时”(请参见上一行)中列出的要求重试同一请求。
超出设备消息投递率 DEVICE_MESSAGE_RATE
_EXCEEDED
针对特定设备的消息投递率过高。可减少发送到此设备的消息数,且不要立即重试向此设备发送消息。
超出主题消息投递率 TOPICS_MESSAGE_RATE
_EXCEEDED
针对某个特定主题的订阅者的消息投递率过高。可减少针对此主题发送的消息数,且不要立即重试发送。
连接排空 CONNECTION_DRAINING 因为正在排空连接,所以无法处理消息。之所以发生这种情况,是因为 FCM 需要定期关闭连接以执行负载平衡。可通过另一个 XMPP 连接重试发送此消息。
APNs 凭据无效 INVALID_APNS_CREDENTIAL 因为所需的 APNs 身份验证密钥尚未上传或已过期,所以无法向 iOS 设备发送消息。请检查您的开发环境凭据和正式环境凭据是否有效。

上行消息语法

上行消息是客户端应用发送至应用服务器的消息。目前只有 XMPP 支持上行消息传递。如需详细了解如何从客户端应用发送消息,请参阅您的平台的相关文档。

解读上行 XMPP 消息

FCM 在响应客户端应用发送的上行消息请求的过程中会生成 XMPP Stanza,下表介绍了这些 Stanza 中的字段。

表 5 上行 XMPP 消息。

参数 用法 说明
from 必选,字符串

此参数用于指定消息的发送者。

该值是客户端应用的注册令牌。

category 必选,字符串 此参数用于指定发送消息的客户端应用的应用包名称。
message_id 必选,字符串 此参数用于指定消息的唯一 ID。
data 可选,字符串 此参数用于指定消息有效负载的键值对。

发送 ACK 消息

在收到上行消息时,应用服务器应当向 FCM 发送 ACK 响应,下表中介绍了这些响应。

表 6 上行 XMPP 消息响应。

参数 用法 说明
to 必选,字符串

此参数用于指定某条响应消息的接收者。

该值必须是发送上行消息的客户端应用的注册令牌。

message_id 必选,字符串 此参数用于指定该响应所针对的消息。该值必须是相应的上行消息中的 message_id 值。
message_type 必选,字符串 此参数用于指定从应用服务器发送至 CCS 的 ack 消息。对于上行消息,应始终将其设置为 ack

FCM 服务器消息 (XMPP)

这是从 FCM 发送至应用服务器的消息。从 FCM 发送至应用服务器的主要消息类型有:

  • 送达回执:如果应用服务器在下行消息中加入了 delivery_receipt_requested,则 FCM 在收到关于设备已成功接收该消息的确认信息时,会发送一个送达回执。
  • 控制消息:这些由 CCS 生成的消息表明应用服务器需要执行某些操作。

下表介绍了从 CCS 发送至应用服务器的消息中包含的字段。

表 7 FCM 控制消息 (XMPP)。

参数 用法 说明
通用字段
message_type 必选,字符串

此参数用于指定消息的类型:送达回执还是控制消息。

当它设置为 receipt 时,消息将包含 frommessage_idcategorydata 字段以提供更多信息。

当它设置为 control 时,消息将包括 control_type 以指示控制消息的类型。

送达回执专用字段
from 必选,字符串 此参数设置为 gcm.googleapis.com,表示该消息是从 FCM 发出的。
message_id 必选,字符串 此参数用于指定回执所针对的原始消息 ID,其前缀为 dr2: 表示该消息是一个送达回执。应用服务器必须发送一条带有此消息 ID 的 ack 消息,以确认它已收到此送达回执。如需了解 ack 消息格式,请参见表 6
category 可选,字符串 此参数用于指定收到了此送达回执所报告消息的客户端应用的应用包名称。当 message_typereceipt 时可使用此参数。
data 可选,字符串 此参数用于指定送达回执消息的键值对。当消息类型为 receipt 时可使用此参数。
  • message_status:此参数用于指定回执消息的状态。当它设置为 MESSAGE_SENT_TO_DEVICE 时,表示设备已确认收到原始消息。
  • original_message_id:此参数用于指定从应用服务器发送至客户端应用的原始消息的 ID。
  • device_registration_id:此参数用于指定接收原始消息的客户端应用的注册令牌。
控制消息专用字段
control_type 可选,字符串

此参数用于指定从 FCM 发送的控制消息的类型。

目前只支持 CONNECTION_DRAINING。FCM 会在关闭连接以执行负载平衡之前发送此控制消息。排空连接时,不允许再向该连接发送任何消息,但流水线中现有的消息仍将被处理。