Catch up on highlights from Firebase at Google I/O 2023. Learn more

在 Apple 平台上向設備組發送消息

設備組消息傳遞允許您將多個設備添加到一個組中。這類似於主題消息傳遞，但包括身份驗證以確保組成員資格僅由您的服務器管理。例如，如果你想向不同的手機型號發送不同的消息，你的服務器可以添加/刪除對適當組的註冊，並向每個組發送適當的消息。設備組消息傳遞不同於主題消息傳遞，因為它涉及從您的服務器而不是直接在您的應用程序中管理設備組。

您可以在應用服務器上通過舊版XMPP或HTTP協議使用設備組消息傳遞。用於 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_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的參考信息。

向設備組發送上行消息

要向 Apple 應用程序上的設備組發送上游消息，Apple 客戶端應用程序需要實現FIRMessaging.sendMessage ：

(void)sendMessage:(nonnull NSDictionary *)message
     to:(nonnull NSString *)receiver
withMessageID:(nonnull NSString *)messageID
timeToLive:(int64_t)ttl;