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