Firebase Cloud Messaging HTTP 协议

注意：使用 FCM XMPP 和 HTTP 旧版 API 发送消息（包括上行消息）已于 2023 年 6 月 20 日弃用，并且将从 2024 年 6 月起移除。如果您使用的是旧版 FCM 发送 API，我们强烈建议您迁移到 HTTP v1 API 或考虑使用 Admin SDK 构建发送请求。

本文档提供了通过 Firebase Cloud Messaging 从您的应用服务器向客户端应用传递消息时所用 HTTP 语法的参考信息。

如果应用使用的是 FCM 旧版 HTTP API，您应该考虑迁移到 HTTP v1 API。如需详细了解 v1 API 的优势以及了解迁移说明，请参阅迁移指南。

使用旧版 HTTP 协议时，您的应用服务器必须将所有 HTTP 请求定向到以下端点：

https://fcm.googleapis.com/fcm/send

可用的参数和选项分为以下几个大类：

• 下行消息语法
• 下行消息错误响应代码

下行消息语法

本部分将介绍发送下行消息和解读来自 Firebase Cloud Messaging 的 HTTP 响应所使用的语法。

下行 HTTP 消息 (JSON)

下表列出了 HTTP JSON 消息的目标、选项和载荷。

表 1：下行 HTTP 消息 (JSON) 的目标、选项和载荷。

参数	用法	说明
目标
to	可选，字符串	此参数用于指定消息的接收者。 值可以是设备的注册令牌、设备组的通知键或单个主题（前缀为 /topics/）。如需发送到多个主题，请使用 condition 参数。
registration_ids	可选，字符串数组	此参数用于指定多播消息（发送到多个注册令牌的消息）的接收者。 值应该是向其发送多播消息的目标注册令牌数组。该数组必须包含 1 到 1000 个注册令牌。如需向单一设备发送消息，请使用 to 参数。 仅允许使用 HTTP JSON 格式的多播消息。
condition	可选，字符串	此参数指定用于确定消息目标的逻辑条件表达式。 支持的条件：主题，格式为“'yourTopic' in topics”。此值不区分大小写。 支持的运算符：&&、||。每个主题消息最多支持两个运算符。
notification_key 已弃用	可选，字符串	此参数已被弃用。目前，应使用 to 来指定消息接收者。如需详细了解如何向多个设备发送消息，请参阅适用于您所用平台的文档。
选项
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 周。 如需了解详情，请参阅设置消息的有效期。
restricted_package_ name（仅适用于 Android）	可选，字符串	此参数用于指定应用的软件包名称，其注册令牌必须匹配才能接收消息。
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 发送。

通知载荷支持

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

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

参数	用法	说明
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。

下行 HTTP 消息（纯文本）

下表列出了纯文本下行 HTTP 消息的目标、选项和载荷使用的语法。

表 3：下行纯文本 HTTP 消息的目标、选项和载荷。

参数	用法	说明
目标
registration_id	必需，字符串	此参数用于指定接收消息的客户端应用（注册令牌）。 仅允许使用 HTTP JSON 格式进行多播消息传递（发送至一个以上注册令牌）。
选项
collapse_key	可选，字符串	请参阅表 1 了解详情。
time_to_live	可选，数字	请参阅表 1 了解详情。
restricted_package_name	可选，字符串	请参阅表 1 了解详情。
dry_run	可选，布尔值	请参阅表 1 了解详情。
载荷
data.<key>	可选，字符串	此参数用于指定消息载荷的键值对。 键值对参数没有数量限制，但是消息总大小不得超过 4096 字节。 例如，在 Android 中，"data.score"."3x1" 会导致生成一个名为 score、字符串值为 3x1 的 intent 附加信息 (extra)。 键不能采用保留的字词（“from”、“message_type”或任何以“google”或“gcm”开头的字词）。请勿使用此表中定义的任何字词（例如 collapse_key）。

解读下行消息响应

应用服务器应评估消息响应标头和正文以解读通过 FCM 发送的消息响应。下表介绍了可能的响应。

表 4：下行 HTTP 消息响应标头。

响应	说明
200	消息处理成功。响应正文包含有关消息状态的更多详细信息，但其格式取决于请求是 JSON 格式还是纯文本格式。请参阅表 5 了解详情。
400	仅适用于 JSON 请求。 表示请求不能作为 JSON 进行解析，或者其中包含无效字段（例如，传递预计会有数字的字符串）。响应中会描述出现问题的确切原因，应先解决问题，之后方可重试请求。
401	验证发送者账号身份时出错。
5xx	错误代码若在 500-599 范围之间（例如 500 或 503），表示在尝试处理请求时，FCM 后端发生内部错误，或服务器暂时不可用（例如，由于超时原因）。发送者必须接受响应中的任何 Retry-After 标头，稍后重试。应用服务器必须实现指数退避。

下表列出了下行消息响应正文 (JSON) 中的字段。

表 5.下行 HTTP 消息响应正文 (JSON)。

参数	用法	说明
multicast_id	必选，数字	用于识别多播消息的唯一 ID（数字）。
success	必选，数字	处理时未出错的消息数。
failure	必选，数字	无法处理的消息数。
results	必需，对象数组	代表已处理消息状态的对象数组。对象的排列顺序与请求相同（即对于请求中的每个注册 ID，其结果的列出顺序与响应中的索引顺序相同）。 message_id：字符串，用于指定每条成功处理的消息的唯一 ID。 error：字符串，用于指定处理收件人的消息时发生的错误。表 9 中列出了可能的值。

表 6.主题消息 HTTP 响应正文 (JSON)。

参数	用法	说明
message_id	可选，数字	当 FCM 成功接收到请求并尝试传递至所有已订阅设备时的主题消息 ID。
error	可选，字符串	处理消息时发生的错误。 表 9 中列出了可能的值。

表 7.下行 HTTP 消息响应正文（纯文本）的成功响应。

参数	用法	说明
id	必需，字符串	此参数用于指定 FCM 成功处理的唯一消息 ID。
registration_id	可选，字符串	此参数用于指定处理和接收消息的客户端应用的注册令牌。

表 8.下行 HTTP 消息响应正文（纯文本）的错误响应。

参数	用法	说明
Error	必需，字符串	此参数用于指定处理接收者消息时的错误值。 请参阅表 9 了解详情。

下行消息错误响应代码

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

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

错误	HTTP 代码	建议执行的操作
缺少注册令牌	200 + error:MissingRegistration	检查请求中是否包含一个注册令牌（对于纯文本消息，包含在 registration_id 中；对于 JSON 消息，包含在 to 或 registration_ids 字段中）。
注册令牌无效	200 + error:InvalidRegistration	检查您传送至服务器的注册令牌格式。确保它与客户端应用在注册 Firebase 通知时获得的注册令牌匹配。不能截断或添加其他字符。
未注册设备	200 + error:NotRegistered	现有注册令牌在很多情况下都可能会失效，包括： 客户端应用取消 FCM 注册。 客户端应用自动撤消注册（用户卸载应用时可能发生此情况）。例如，在 iOS 中，APNs 反馈服务报告称 APNs 令牌无效。 注册令牌过期（例如 Google 可能决定更新注册令牌，或者 iOS 设备的 APNs 令牌已过期）。 客户端应用已更新，但新版本未配置为接收消息。 对于所有这些情况，请从应用服务器中移除此注册令牌，并停止用其发送消息。
无效的软件包名称	200 + error:InvalidPackageName	确保消息发送至软件包名称与请求中传递的值相匹配的注册令牌。
身份验证错误	401	无法对用于发送消息的发送者账号进行身份验证。可能的原因如下： 授权标头缺失或 HTTP 请求中使用了无效的语法。 指定的服务器密钥所属的 Firebase 项目不正确。 仅限旧版服务器密钥 - 从服务器发出的请求不在服务器密钥 IP 白名单中。 检查您在身份验证标头内部发送的令牌是不是与您的项目关联的正确的服务器密钥。请参阅检查服务器密钥的有效性了解详情。如果您使用的是旧版服务器密钥，建议您升级到没有 IP 限制的新密钥。 请参阅迁移旧版服务器密钥。
发送者不匹配	200 + error:MismatchSenderId	一个注册令牌与一组特定的发送者关联。当客户端应用注册 FCM 时，必须指定允许哪些发送者发送消息。在向客户端应用发送消息时，您应当使用这些发送者 ID 之一。如果您改用其他发送者，则现有的注册令牌将不起作用。
JSON 无效	400	检查 JSON 消息是否格式正确以及包含有效字段（例如确保传入正确的数据类型）。
参数无效	400 + error:InvalidParameters	确保提供的参数具有正确的名称和类型。
消息过大	200 + error:MessageTooBig	确保消息中包含的载荷数据的总大小不超过 FCM 的限制：大多数消息的上限是 4096 字节；如果是主题消息，则上限为 2048 字节。这包括键和值。
数据键无效	200 + error: InvalidDataKey	确保载荷数据未包含由 FCM 内部使用的键（例如 from、gcm 或任何以 google 为前缀的值）。请注意，FCM 使用的某些字词（例如 collapse_key）也允许在载荷中使用，在这种情况下，FCM 值会覆盖载荷值。
存留时间无效	200 + error:InvalidTtl	确保 time_to_live 中使用的值是表示时长（以秒为单位）的整数值，且介于 0 到 2419200（即 4 周）之间。
超时	5xx 或 200 + error:Unavailable	服务器无法及时处理请求。重试同一请求，但您必须： 如果 FCM 连接服务器发出的响应中包含 Retry-After 标头，则应在该标头指明的间隔后重试。 在您的重试机制中实现指数退避。（例如，如果等待一秒钟后进行第一次重试，则至少要等待两秒钟再进行下一次重试，然后等待四秒钟，依此类推）。如果您要发送多条消息，请分别将每条消息延迟额外的随机时长，从而避免同时为所有消息发出新的请求。 导致出现问题风险的发送者将被列入屏蔽名单。
内部服务器错误	500 或 200 + error:InternalServerError	服务器在尝试处理请求时遇到错误。您可按照“超时”中的要求重试同一请求（请参阅上一行）。如果错误仍然存在，请联系 Firebase 支持团队。
超出设备消息投递率	200 + error: DeviceMessageRate Exceeded	向特定设备发送消息的频率过高。如果 Apple 应用发送消息的速率超过 APNs 限制，就可能会收到此错误消息 请减少发送到此设备的消息数量，并使用指数退避重试发送。
超出主题消息投递率	200 + error: TopicsMessageRate Exceeded	针对特定主题订阅者的消息投递率过高。请减少针对此主题发送的消息数量，并使用指数退避重试发送。
APNs 凭据无效	200 + error: InvalidApnsCredential	因为所需的 APNs 身份验证密钥尚未上传或已过期，所以无法向 Apple 设备发送消息。请检查您的开发和生产环境凭据是否有效。

设备组管理

下表列出了用于创建设备组以及添加和移除成员的键。如需了解详情，请参阅适用于您所用平台（iOS+ 或 Android）的指南。

表 10.设备组管理对应的键。

参数	用法	说明
operation	必需，字符串	要执行的操作。有效值包括 create、add 和 remove。
notification_key_name	必需，字符串	用户定义的要创建或修改的设备组的名称。
notification_key	必需（create 操作除外），字符串	设备组的唯一标识符。成功 create 操作的响应中会返回此值，设备组的所有后续操作也需要此值。
registration_ids	必需，字符串数组	要添加或移除的设备令牌。如果您移除了某个设备组中的所有现有注册令牌，那么 FCM 会删除该设备组。