获取我们在 Firebase 峰会上发布的所有信息,了解 Firebase 可如何帮助您加快应用开发速度并满怀信心地运行应用。了解详情

在 Unity 上向设备组发送消息

设备组消息允许您将多个设备添加到单个组。这类似于主题消息传递,但包括身份验证以确保组成员身份仅由您的服务器管理。例如,如果您想向不同的手机型号发送不同的消息,您的服务器可以将注册添加/删除到适当的组,并将适当的消息发送到每个组。设备组消息与主题消息的不同之处在于它涉及从您的服务器而不是直接在您的应用程序中管理设备组。

您可以通过应用服务器上的旧XMPPHTTP协议使用设备组消息传递。适用于 Node.js 的旧版 Firebase Admin SDK基于旧协议,还提供设备群组消息传递功能。通知键允许的最大成员数为 20。

管理设备组

在向设备组发送消息之前,您必须:

  1. 获取要添加到组的每个设备的注册令牌。

  2. 创建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_namenotification_key对于一组注册令牌是唯一的。如果您有多个客户端应用程序具有相同的发件人 IDnotification_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` 值。

在设备组中添加和删除设备

要从现有组中添加或删除设备,请发送 POST 请求,并将operation参数设置为addremove ,并提供注册令牌以进行添加或删除。

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 个与之关联的注册令牌。消息仅成功发送到 1 个注册令牌。响应消息列出了未能接收到消息的注册令牌 ( 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 个与之关联的注册令牌。消息仅成功发送到 1 个注册令牌。响应消息列出了未能收到消息的注册令牌:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

当 FCM 连接服务器无法传送到组中的所有设备时。应用服务器将收到一个 nack 响应。

有关消息选项的完整列表,请参阅您选择的连接服务器协议HTTPXMPP的参考信息。

向设备组发送上行消息

客户端应用程序可以通过将消息定位到to字段中的适当通知键,向上游发送消息到设备组。

以下对 FCM 的调用将上游消息发送到通知键。

Firebase.Messaging.Message message;
message.To = notification_key;
message.MessageId = a_unique_message_id;
message.Data["hello"] = "world";
Firebase.Messaging.FirebaseMessaging.Send(message);
,

设备组消息允许您将多个设备添加到单个组。这类似于主题消息传递,但包括身份验证以确保组成员身份仅由您的服务器管理。例如,如果您想向不同的手机型号发送不同的消息,您的服务器可以将注册添加/删除到适当的组,并将适当的消息发送到每个组。设备组消息与主题消息的不同之处在于它涉及从您的服务器而不是直接在您的应用程序中管理设备组。

您可以通过应用服务器上的旧XMPPHTTP协议使用设备组消息传递。适用于 Node.js 的旧版 Firebase Admin SDK基于旧协议,还提供设备群组消息传递功能。通知键允许的最大成员数为 20。

管理设备组

在向设备组发送消息之前,您必须:

  1. 获取要添加到组的每个设备的注册令牌。

  2. 创建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_namenotification_key对于一组注册令牌是唯一的。如果您有多个客户端应用程序具有相同的发件人 IDnotification_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` 值。

在设备组中添加和删除设备

要从现有组中添加或删除设备,请发送 POST 请求,并将operation参数设置为addremove ,并提供注册令牌以进行添加或删除。

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 个与之关联的注册令牌。消息仅成功发送到 1 个注册令牌。响应消息列出了未能接收到消息的注册令牌 ( 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 个与之关联的注册令牌。消息仅成功发送到 1 个注册令牌。响应消息列出了未能收到消息的注册令牌:

{
  "from": "aUniqueKey",
  "message_type": "ack",
  "success":1,
  "failure":2,
  "failed_registration_ids":[
     "regId1",
     "regId2"
  ]
}

当 FCM 连接服务器无法传送到组中的所有设备时。应用服务器将收到一个 nack 响应。

有关消息选项的完整列表,请参阅您选择的连接服务器协议HTTPXMPP的参考信息。

向设备组发送上行消息

客户端应用程序可以通过将消息定位到to字段中的适当通知键,向上游发送消息到设备组。

以下对 FCM 的调用将上游消息发送到通知键。

Firebase.Messaging.Message message;
message.To = notification_key;
message.MessageId = a_unique_message_id;
message.Data["hello"] = "world";
Firebase.Messaging.FirebaseMessaging.Send(message);