本文檔提供了透過 Firebase Cloud Messaging 將訊息從應用伺服器傳遞到客戶端應用程式的 HTTP 語法的參考。
使用舊版 HTTP 協定時,您的應用程式伺服器必須將所有 HTTP 請求定向到此端點:
https://fcm.googleapis.com/fcm/send
可用的參數和選項分為以下幾大類:
下游訊息語法
本部分提供發送下游訊息和解釋來自 Firebase Cloud Messaging 的 HTTP 回應的語法。
下游 HTTP 訊息 (JSON)
下表列出了 HTTP JSON 訊息的目標、選項和負載。
範圍 | 用法 | 描述 | |
---|---|---|---|
目標 | |||
to | 可選,字串 | 此參數指定訊息的接收者。 該值可以是設備的註冊令牌、設備群組的通知金鑰或單一主題(以 | |
registration_ids | 可選,字串數組 | 此參數指定多播訊息的接收者,該訊息傳送至多個註冊令牌。 該值應該是向其發送多播訊息的註冊令牌數組。此陣列必須包含至少 1 個、最多 1000 個註冊令牌。若要將訊息傳送到單一設備,請使用 多播訊息僅允許使用 HTTP JSON 格式。 | |
condition | 可選,字串 | 此參數指定確定訊息目標的條件的邏輯表達式。 支援的條件:主題,格式為「主題中的'yourTopic'」。該值不區分大小寫。 支援的運算子: | |
notification_key 已棄用 | 可選,字串 | 該參數已被棄用。相反,請使用 | |
選項 | |||
collapse_key | 可選,字串 | 此參數標識一組可以折疊的訊息(例如,使用 請注意,無法保證訊息發送的順序。 注意:在任何給定時間最多允許使用 4 個不同的折疊鍵。這意味著 FCM 可以為每個客戶端應用程式同時儲存 4 個不同的訊息。如果超過此數量,則無法保證 FCM 將保留哪 4 個折疊鍵。 | |
priority | 可選,字串 | 設定訊息的優先順序。有效值為“正常”和“高”。在 Apple 平台上,這些對應於 APN 優先權 5 和 10。 預設情況下,通知訊息以高優先順序發送,資料訊息以普通優先權發送。正常優先順序可最佳化用戶端應用程式的電池消耗,除非需要立即交付,否則應使用正常優先順序。對於具有正常優先權的訊息,應用程式可能會以未指定的延遲接收訊息。 當發送高優先級訊息時,會立即發送,並且應用程式可以顯示通知。 | |
content_available | 可選,布林值 | 在 Apple 平台上,使用此欄位表示 APNs 負載中 | |
mutable_content | 可選,JSON 布林值 | 在 Apple 平台上,使用此欄位來表示 APNs 負載中的 | |
time_to_live | 可選,數量 | 此參數指定如果設備離線,訊息應在 FCM 儲存中保留多長時間(以秒為單位)。支援的最長生存時間為 4 週,預設值為 4 週。有關詳細信息,請參閱設定訊息的生命週期。 | |
restricted_package_ (僅限 Android) | 可選,字串 | 此參數指定應用程式的套件名稱,其中註冊令牌必須匹配才能接收訊息。 | |
dry_run | 可選,布林值 | 當此參數設為 預設值為 | |
有效載荷 | |||
data | 可選,對象 | 此參數指定訊息負載的自訂鍵值對。 例如,對於 在 Apple 平台上,如果訊息是透過 APN 發送的,則它代表自訂資料欄位。如果透過 FCM 發送,它將在 在 Android 上,這將導致一個名為 鍵不應是保留字(“from”、“message_type”或任何以“google”或“gcm”開頭的單字)。不要使用此表中定義的任何單字(例如 建議使用字串類型的值。您必須將物件或其他非字串資料類型(例如整數或布林值)中的值轉換為字串。 | |
notification | 可選,對象 | 此參數指定通知負載的預先定義、使用者可見的鍵值對。有關詳細信息,請參閱通知負載支援。有關通知訊息和資料訊息選項的更多信息,請參閱訊息類型。如果提供了通知負載,或發送至 Apple 裝置的訊息的content_available 選項設為true ,則訊息將透過 APNs 傳送,否則將透過 FCM 傳送。 |
通知負載支持
下表列出了可用於建立 iOS 和 Android 通知訊息的預先定義鍵。
範圍 | 用法 | 描述 |
---|---|---|
title | 可選,字串 | 通知的標題。 該欄位在手機和平板電腦上不可見。 |
body | 可選,字串 | 通知的正文。 |
sound | 可選,字串 | 設備收到通知時播放的聲音。 指定客戶端應用程式主包中或應用程式資料容器的 |
badge | 可選,字串 | 主螢幕應用程式圖示上的徽章的值。 如果未指定,則不會變更徽章。 如果設定為 |
click_action | 可選,字串 | 與使用者點選通知關聯的操作。 對應於 APNs 負載中的 |
subtitle | 可選,字串 | 通知的副標題。 |
body_loc_key | 可選,字串 | 應用程式字串資源中正文字串的鍵,用於將正文文字本地化為使用者目前的本地化。 對應於 APNs 負載中的 有關更多信息,請參閱有效負載密鑰參考和本地化遠端通知的內容。 |
body_loc_args | 可選,JSON 數組作為字串 | 用於取代 對應於 APNs 負載中的 有關更多信息,請參閱有效負載密鑰參考和本地化遠端通知的內容。 |
title_loc_key | 可選,字串 | 應用程式字串資源中標題字串的鍵,用於將標題文字本地化為使用者目前的本地化版本。 對應於 APNs 負載中的 有關更多信息,請參閱有效負載密鑰參考和本地化遠端通知的內容。 |
title_loc_args | 可選,JSON 數組作為字串 | 用於取代 對應於 APNs 負載中的 有關更多信息,請參閱有效負載密鑰參考和本地化遠端通知的內容。 |
範圍 | 用法 | 描述 |
---|---|---|
title | 可選,字串 | 通知的標題。 |
body | 可選,字串 | 通知的正文。 |
android_channel_id | 可選,字串 | 通知的頻道 ID (Android O 中的新增功能)。 在收到具有此通道 ID 的任何通知之前,應用程式必須建立具有此通道 ID 的通道。 如果您未在請求中傳送此通道 ID,或套用尚未建立提供的通道 ID,則 FCM 將使用應用程式清單中指定的通道 ID。 |
icon | 可選,字串 | 通知的圖示。 將可繪製資源 |
sound | 可選,字串 | 設備收到通知時播放的聲音。 支援 |
tag | 可選,字串 | 用於替換通知抽屜中現有通知的標識符。 如果未指定,每個請求都會建立一個新通知。 如果指定並且已顯示具有相同標籤的通知,則新通知將取代通知抽屜中的現有通知。 |
color | 可選,字串 | 通知的圖示顏色,以 |
click_action | 可選,字串 | 與使用者點選通知關聯的操作。 如果指定,當使用者按一下通知時,將啟動具有匹配意圖過濾器的活動。 |
body_loc_key | 可選,字串 | 應用程式字串資源中正文字串的鍵,用於將正文文字本地化為使用者目前的本地化。 有關詳細信息,請參閱字串資源。 |
body_loc_args | 可選,JSON 數組作為字串 | 用於取代 有關詳細信息,請參閱格式和样式。 |
title_loc_key | 可選,字串 | 應用程式字串資源中標題字串的鍵,用於將標題文字本地化為使用者目前的本地化版本。 有關詳細信息,請參閱字串資源。 |
title_loc_args | 可選,JSON 數組作為字串 | 用於取代 有關詳細信息,請參閱格式和样式。 |
範圍 | 用法 | 描述 |
---|---|---|
title | 可選,字串 | 通知的標題。 |
body | 可選,字串 | 通知的正文。 |
icon | 可選,字串 | 用於通知圖示的 URL。 |
click_action | 可選,字串 | 與使用者點選通知關聯的操作。 對於所有 URL 值,都需要 HTTPS。 |
下游 HTTP 訊息(純文字)
下表列出了純文字下游 HTTP 訊息中的目標、選項和負載的語法。
範圍 | 用法 | 描述 |
---|---|---|
目標 | ||
registration_id | 必填,字串 | 此參數指定接收訊息的用戶端應用程式(註冊令牌)。 僅允許使用 HTTP JSON 格式進行多播訊息傳遞(傳送至多個註冊令牌)。 |
選項 | ||
collapse_key | 可選,字串 | 詳情請參閱表1 。 |
time_to_live | 可選,數量 | 詳情請參閱表1 。 |
restricted_package_name | 可選,字串 | 詳情請參閱表1 。 |
dry_run | 可選,布林值 | 詳情請參閱表1 。 |
有效載荷 | ||
data.<key> | 可選,字串 | 此參數指定訊息負載的鍵值對。鍵值參數的數量沒有限制,但訊息總大小限制為 4000 位元組。 例如,在 Android 中, 鍵不應是保留字(“from”、“message_type”或任何以“google”或“gcm”開頭的單字)。不要使用此表中定義的任何單字(例如 |
解釋下游訊息回應
應用伺服器應評估訊息回應標頭和正文,以解釋從 FCM 發送的訊息回應。下表描述了可能的回應。
回覆 | 描述 |
---|---|
200 | 訊息已成功處理。回應正文將包含有關訊息狀態的更多詳細信息,但其格式將取決於請求是 JSON 還是純文字。更多詳情請參閱表5 。 |
400 | 僅適用於 JSON 請求。表示請求無法解析為 JSON,或包含無效欄位(例如,在需要數字的地方傳遞了字串)。回應中描述了確切的失敗原因,並且應該在重試請求之前解決問題。 |
401 | 驗證寄件者帳戶時發生錯誤。 |
5xx | 500-599 範圍內的錯誤(例如 500 或 503)表示 FCM 後端在嘗試處理請求時出現內部錯誤,或伺服器暫時無法使用(例如,由於逾時)。發送者必須稍後重試,尊重回應中包含的任何Retry-After 標頭。應用程式伺服器必須實現指數退避。 |
下表列出了下游訊息回應正文 (JSON) 中的欄位。
範圍 | 用法 | 描述 |
---|---|---|
multicast_id | 必填,數量 | 標識多播訊息的唯一 ID(編號)。 |
success | 必填,數量 | 已處理且沒有錯誤的訊息數。 |
failure | 必填,數量 | 無法處理的訊息數。 |
results | 必需,物件數組 | 表示已處理訊息的狀態的物件陣列。物件按照與請求相同的順序列出(即,對於請求中的每個註冊 ID,其結果在回應中的相同索引中列出)。
|
範圍 | 用法 | 描述 |
---|---|---|
message_id | 可選,數量 | FCM 成功接收請求並將嘗試傳遞到所有訂閱裝置時的主題訊息 ID。 |
error | 可選,字串 | 處理訊息時發生錯誤。可能的值可在表 9中找到。 |
範圍 | 用法 | 描述 |
---|---|---|
id | 必填,字串 | 此參數指定 FCM 處理成功的唯一訊息 ID。 |
registration_id | 可選,字串 | 此參數指定處理訊息並將其發送到的客戶端應用程式的註冊令牌。 |
範圍 | 用法 | 描述 |
---|---|---|
Error | 必填,字串 | 此參數指定為收件人處理訊息時的錯誤值。詳細資訊請參閱表9 。 |
下游報文錯誤回應碼
下表列出了下游訊息的錯誤回應碼。
錯誤 | HTTP 程式碼 | 建議操作 |
---|---|---|
缺少註冊令牌 | 200 + 錯誤:缺少註冊 | 檢查請求是否包含註冊令牌(在純文字訊息中的registration_id 中,或在 JSON 中的to 或registration_ids 欄位中)。 |
註冊令牌無效 | 200 + 錯誤:無效註冊 | 檢查您傳遞給伺服器的註冊令牌的格式。確保它與客戶端應用程式透過 Firebase 通知註冊收到的註冊令牌相符。不要截斷或添加額外的字元。 |
未註冊設備 | 200 + 錯誤:未註冊 | 現有的註冊令牌可能在多種情況下不再有效,包括:
|
包名稱無效 | 200 + 錯誤:InvalidPackageName | 確保訊息傳送至註冊令牌,其套件名稱與請求中傳遞的值相符。 |
授權錯誤 | 401 | 用於發送訊息的寄件者帳戶無法通過身份驗證。可能的原因有:
|
寄件者不匹配 | 200 + 錯誤:不符合寄件者 ID | 註冊令牌與特定的發送者群組相關聯。當客戶端應用程式註冊 FCM 時,它必須指定允許哪些寄件者傳送訊息。向客戶端應用程式發送訊息時,您應該使用這些寄件者 ID 之一。如果您切換到其他寄件人,現有的註冊令牌將無法運作。 |
無效的 JSON | 400 | 檢查 JSON 訊息的格式是否正確並包含有效欄位(例如,確保傳入正確的資料類型)。 |
無效參數 | 400 + 錯誤:參數無效 | 檢查提供的參數是否具有正確的名稱和類型。 |
訊息太大 | 200 + 錯誤:MessageTooBig | 檢查訊息中包含的有效負載資料的總大小是否超過 FCM 限制:大多數訊息為 4096 字節,對於主題訊息為 2048 位元組。這包括鍵和值。 |
資料金鑰無效 | 200+錯誤: 無效的資料金鑰 | 檢查負載資料是否不包含 FCM 內部使用的金鑰(例如from 、 gcm 或任何以google 為前綴的值)。請注意,FCM 也使用某些單字(例如collapse_key ),但在有效負載中允許使用,在這種情況下,有效負載值將被 FCM 值覆蓋。 |
無效生存時間 | 200 + 錯誤:InvalidTtl | 檢查time_to_live 中使用的值是否為整數,表示 0 到 2,419,200(4 週)之間的持續時間(以秒為單位)。 |
暫停 | 5xx 或 200 + 錯誤:不可用 | 伺服器無法及時處理請求。重試相同的請求,但您必須:
造成問題的寄件者可能會被列入黑名單。 |
內部伺服器錯誤 | 500 或 200 + 錯誤:InternalServerError | 伺服器在嘗試處理請求時遇到錯誤。您可以按照「超時」中列出的要求重試相同的請求(請參閱上面的行)。如果錯誤仍然存在,請聯絡Firebase 支援。 |
設備訊息速率超出 | 200+錯誤: 裝置訊息速率 超過 | 向特定裝置發送訊息的速率太高。如果 Apple 應用程式以超出 APNs 限制的速率發送訊息,則可能會收到此錯誤訊息 減少發送到該裝置的訊息數量並使用指數退避來重試發送。 |
主題 訊息速率超出 | 200+錯誤: 主題留言率 超過 | 向特定主題的訂閱者發送訊息的比率太高。減少為此主題發送的訊息數量並使用指數退避來重試發送。 |
APNs 憑證無效 | 200+錯誤: 無效的 Apns 憑證 | 無法傳送針對 Apple 裝置的訊息,因為所需的 APNs 驗證金鑰未上傳或已過期。檢查您的開發和生產憑證的有效性。 |
設備分組管理
下表列出了用於建立設備群組以及新增和刪除成員的按鍵。有關更多信息,請參閱適用於您的平台( iOS+或Android)的指南。
範圍 | 用法 | 描述 |
---|---|---|
operation | 必填,字串 | 要執行的操作。有效值為create 、 add 和remove 。 |
notification_key_name | 必填,字串 | 若要建立或修改的設備群組的使用者定義名稱。 |
notification_key | 必填( create 操作除外,字串 | 設備組的唯一識別碼。該值在成功create 操作的回應中傳回,並且是設備群組上的所有後續操作所必需的。 |
registration_ids | 必需,字串數組 | 若要新增或刪除的設備令牌。如果您從裝置群組中刪除所有現有註冊令牌,FCM 會刪除該裝置群組。 |