設備組消息允許您將多個設備添加到單個組。這類似於主題消息傳遞,但包括身份驗證以確保組成員身份僅由您的服務器管理。例如,如果您想向不同的手機型號發送不同的消息,您的服務器可以將註冊添加/刪除到適當的組,並將適當的消息發送到每個組。設備組消息與主題消息的不同之處在於它涉及從您的服務器而不是直接在您的應用程序中管理設備組。
您可以通過應用服務器上的舊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` 值。
在設備組中添加和刪除設備
要從現有組中添加或刪除設備,請發送 POST 請求,並將operation
參數設置為add
或remove
,並提供註冊令牌以進行添加或刪除。
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 響應。
有關消息選項的完整列表,請參閱您選擇的連接服務器協議HTTP或XMPP的參考信息。