Firebase Cloud Messaging XMPP 协议

本文档提供了在应用服务器、客户端应用和 Firebase Cloud Messaging (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”（高）。在 Apple 平台中，这些值对应于 APNs 优先级中的 5 和 10。

默认情况下，通知消息以高优先级发送，数据消息以普通优先级发送。普通优先级可优化客户端应用的耗电量，因此除非需要立即传送，否则应使用普通优先级。对于普通优先级消息，应用可能会在一定延迟后收到消息。

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

content_available 可选，布尔值

在 Apple 平台上，使用此字段表示 APNs 载荷中的 content-available。如果发送通知或消息时此字段设为 true，则系统将会唤醒处于非活跃状态的客户端应用，且消息将作为静默通知通过 APNs 发送，而不是通过 FCM 发送。请注意，APNs 中的静默通知不保证能传送，并且可能受多种因素影响（比如用户开启低电量模式、强制退出应用等）。在 Android 系统上，数据消息默认会唤醒应用。Chrome 中目前不支持此功能。
mutable_content 可选，JSON 布尔值

在 Apple 平台上，使用此字段表示 APNs 载荷中的 mutable-content。如果发送通知时此字段设为 true，则可以使用 Notification Service 应用扩展程序在通知显示之前修改通知的内容。Android 应用和 Web 应用将忽略此参数。

time_to_live 可选，数字

此参数用于指定设备离线后消息在 FCM 存储空间中保留的时长（以秒为单位）。支持的最长存留时间为 4 周，默认值为 4 周。 如需了解详情，请参阅设置消息的有效期。
dry_run 可选，布尔值

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

默认值为 false。
载荷
data 可选，对象

此参数用于指定消息载荷的键值对。

例如，对于 data:{"score":"3x1"}:

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

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

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

推荐使用字符串类型的值。您必须将对象中的值或其他非字符串数据类型（例如整数或布尔值）转换成字符串。
notification 可选，对象 此参数用于指定用户可见的预定义通知载荷键值对。如需了解详情，请参阅“通知载荷支持”。如需详细了解通知消息和数据消息选项，请参阅消息类型。如果为发送到 Apple 设备的消息提供了通知载荷或者将 content_available 选项设为 true，则消息将通过 APNs 发送，否则消息会通过 FCM 发送。

通知载荷支持

下表列出了可用于为 Apple 平台和 Android 构建通知消息的预定义键。

表 2a：Apple - 用于通知消息的键

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

通知的标题。

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

body 可选，字符串

通知的正文文字。

sound 可选，字符串

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

用于指定声音文件的字符串，该文件可以位于客户端应用的主软件包中，也可位于应用的数据容器的 Library/Sounds 文件夹中。如需了解详情，请参阅 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 发送到应用服务器的消息是 ack 还是 nack。

如果该值设置为 nack，则应用服务器应该查看 error 和 error_description 来获取故障信息。
error 可选，字符串 此参数用于指定与下行消息相关的错误。当 message_type 为 nack 时，系统会设置此参数。请参阅表 4 了解详情。
error_description 可选，字符串 此参数用于提供有关错误的描述性信息。当 message_type 为 nack 时，系统会设置此参数。

下行消息错误响应代码

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

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

错误 XMPP 代码 建议采取的措施
缺少注册令牌 INVALID_JSON 检查请求中是否包含一个注册令牌（对于纯文本消息，包含在 registration_id 中；对于 JSON 消息，包含在 to 或 registration_ids 字段中）。
APNs 注册无效 INVALID_JSON 对于 iOS 注册，请检查来自客户端的注册请求是否包含有效的 APNs 令牌和应用 ID。
注册令牌无效 BAD_REGISTRATION 检查您传送至服务器的注册令牌格式。请确保它与客户端应用在注册 FCM 时获得的注册令牌相符。不能截断或添加其他字符。
未注册设备 DEVICE_UNREGISTERED 现有注册令牌在很多情况下都可能会失效，包括：
  • 客户端应用取消 FCM 注册。
  • 客户端应用自动撤消注册（用户卸载应用时可能发生此情况）。例如，在 iOS 上，APNs 报告称 APNs 令牌无效，可能会发生这种情况。
  • 注册令牌过期（例如 Google 可能决定更新注册令牌，或者设备的 APNs 令牌已过期）。
  • 客户端应用已更新，但新版本未配置为接收消息。
对于所有这些情况，请从应用服务器中移除此注册令牌，并停止用其发送消息。
发送者不匹配 SENDER_ID_MISMATCH 一个注册令牌与一组特定的发送者关联。当客户端应用注册 FCM 时，必须指定允许哪些发送者发送消息。在向客户端应用发送消息时，您应当使用这些发送者 ID 之一。如果您改用其他发送者，则现有的注册令牌将不起作用。
JSON 无效 INVALID_JSON 检查 JSON 消息是否格式正确以及包含有效字段（例如确保传入正确的数据类型）。
消息过大 INVALID_JSON 确保消息中包含的载荷数据的总大小不超过 FCM 的限制：大多数消息的上限是 4096 字节；如果是主题消息，则上限为 2048 字节。这包括键和值。
数据键无效 INVALID_JSON 确保载荷数据未包含由 FCM 内部使用的键（例如 from、gcm 或任何以 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 设备发送消息。请检查您的开发和生产环境凭据是否有效。
身份验证失败 AUTHENTICATION_FAILED 无法通过外部推送服务进行身份验证。检查您是否使用了正确的 Web 推送证书。

上行消息语法

上行消息是客户端应用发送至应用服务器的消息。 目前只有 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 发送至应用服务器的主要消息类型有：

  • 控制消息：这些由 CCS 生成的消息指示应用服务器需要执行某些操作。

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

表 7 FCM 控制消息 (XMPP)。

参数 用法 说明
通用字段
message_type 必需，字符串

此参数用于指定消息的类型：控制。

当它设置为 control 时，消息将包含 control_type 以指示控制消息的类型。
control_type 可选，字符串

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

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