设备组消息传递允许您将多个设备添加到一个组中。这类似于主题消息传递,但包括身份验证以确保组成员资格仅由您的服务器管理。例如,如果你想向不同的手机型号发送不同的消息,你的服务器可以添加/删除对适当组的注册,并向每个组发送适当的消息。设备组消息传递不同于主题消息传递,因为它涉及从您的服务器而不是直接在您的应用程序中管理设备组。
您可以在应用服务器上通过旧版XMPP或HTTP协议使用设备组消息传递。用于 Node.js 的旧版 Firebase Admin SDK基于旧协议,还提供设备组消息传递功能。通知密钥允许的最大成员数为 20。
管理设备组
在向设备组发送消息之前,您必须:
为要添加到组中的每个设备获取注册令牌。
创建
notification_key
,它通过将特定组(通常是用户)映射到该组的所有关联注册令牌来标识设备组。您可以在应用服务器上创建通知键。
设备组的基本管理——创建和删除组,以及添加或删除设备——是通过应用服务器执行的。有关受支持密钥的列表,请参阅旧版HTTP 协议参考。
管理应用服务器上的设备组
创建设备组
要创建设备组,请发送一个 POST 请求,其中提供组的名称以及设备的注册令牌列表。 FCM 返回代表设备组的新notification_key
。
HTTP POST 请求
向https://fcm.googleapis.com/fcm/notification
发送如下请求:
https://fcm.googleapis.com/fcm/notification Content-Type:application/json Authorization:key=API_KEY project_id:SENDER_ID { "operation": "create", "notification_key_name": "appUser-Chris", "registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "cR1rjyj4_Kc:APA91bGusqbypSuMdsh7jSNrW4nzsM...", ... ]
notification_key_name
是给定组唯一的名称或标识符(例如,它可以是用户名)。 notification_key_name
和notification_key
对于一组注册令牌是唯一的。如果同一个发送者 ID有多个客户端应用程序,则每个客户端应用程序的notification_key_name
是唯一的很重要。这可确保消息仅发送到预期的目标应用程序。
响应格式
成功的请求会返回一个notification_key
,如下所示:
{ "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ" }
保存notification_key
和对应的notification_key_name
,以供后续操作使用。
检索通知密钥
如果您需要检索现有的通知密钥,请在 GET 请求中使用notification_key_name
,如下所示:
https://fcm.googleapis.com/fcm/notification?notification_key_name=appUser-Chris Content-Type:application/json Authorization:key=API_KEY project_id:SENDER_ID {}
对于给定通知键名称的每个 GET 请求,服务器返回一个唯一的编码字符串。虽然每个字符串可能看起来是不同的键,但它实际上是一个有效的“notification_key”值。
在设备组中添加和删除设备
要从现有组中添加或删除设备,请发送operation
参数设置为add
或remove
的 POST 请求,并提供用于添加或删除的注册令牌。
HTTP POST 请求
例如,要将具有注册令牌bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...
的设备添加到appUser-Chris
,您可以发送此请求:
{
"operation": "add",
"notification_key_name": "appUser-Chris",
"notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ",
"registration_ids": ["bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."]
}
响应格式
添加或删除设备的成功请求会返回如下所示的notification_key
:
{ "notification_key": "APA91bGHXQBB...9QgnYOEURwm0I3lmyqzk2TXQ" }
向设备组发送下游消息
向设备组发送消息与向单个设备发送消息非常相似。将to
参数设置为设备组的唯一通知密钥。有关负载支持的详细信息,请参阅消息类型。本页中的示例展示了如何使用旧版 HTTP 和 XMPP 协议向设备组发送数据消息。
设备组 HTTP POST 请求
https://fcm.googleapis.com/fcm/send Content-Type:application/json Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA { "to": "aUniqueKey", "data": { "hello": "This is a Firebase Cloud Messaging Device Group Message!", } }
设备组 HTTP 响应
下面是一个“成功”的例子notification_key
有 2 个与之关联的注册令牌,消息已成功发送给它们:
{ "success": 2, "failure": 0 }
这是“部分成功”的示例 — notification_key
有 3 个与之关联的注册令牌。消息仅成功发送到其中一个注册令牌。响应消息列出了未能收到消息的注册令牌 ( registration_ids
):
{ "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
当消息未能传递到与notification_key
关联的一个或多个注册令牌时,应用服务器应在重试之间进行退避重试。
如果服务器尝试向没有成员的设备组发送消息,则响应如下所示,0 次成功,0 次失败:
{ "success": 0, "failure": 0 }
设备组 XMPP 消息
<message id=""> <gcm xmlns="google:mobile:data"> { "to": "aUniqueKey", "message_id": "m-1366082849205" , "data": { "hello":"This is a Firebase Cloud Messaging Device Group Message!" } } </gcm> </message>
设备组 XMPP 响应
当消息成功发送到组中的任何一个设备时,XMPP 连接服务器以 ACK 响应。如果发送到组中所有设备的所有消息均失败,则 XMPP 连接服务器将以 NACK 进行响应。
下面是一个“成功”的例子notification_key
有 3 个与之关联的注册令牌,消息已成功发送给所有这些令牌:
{ "from": "aUniqueKey", "message_type": "ack", "success": 3, "failure": 0, "message_id": "m-1366082849205" }
这是“部分成功”的示例 — notification_key
有 3 个与之关联的注册令牌。消息仅成功发送到其中一个注册令牌。响应消息列出了未能接收消息的注册令牌:
{ "from": "aUniqueKey", "message_type": "ack", "success":1, "failure":2, "failed_registration_ids":[ "regId1", "regId2" ] }
当 FCM 连接服务器无法传送到组中的所有设备时。应用服务器将收到一个 nack 响应。
有关消息选项的完整列表,请参阅您选择的连接服务器协议HTTP或XMPP的参考信息。