Firebase 雲端訊息傳遞 HTTP 協定

本文檔提供了透過 Firebase Cloud Messaging 將訊息從應用伺服器傳遞到客戶端應用程式的 HTTP 語法的參考。

使用舊版 HTTP 協定時,您的應用程式伺服器必須將所有 HTTP 請求定向到此端點:

https://fcm.googleapis.com/fcm/send

可用的參數和選項分為以下幾大類:

下游訊息語法

本部分提供發送下游訊息和解釋來自 Firebase Cloud Messaging 的 HTTP 回應的語法。

下游 HTTP 訊息 (JSON)

下表列出了 HTTP JSON 訊息的目標、選項和負載。

表 1.下游 HTTP 訊息 (JSON) 的目標、選項和負載。

範圍用法描述
目標
to可選,字串

此參數指定訊息的接收者。

該值可以是設備的註冊令牌、設備群組的通知金鑰或單一主題(以/topics/為前綴)。若要傳送到多個主題,請使用condition參數。

registration_ids
可選,字串數組

此參數指定多播訊息的接收者,該訊息傳送至多個註冊令牌。

該值應該是向其發送多播訊息的註冊令牌數組。此陣列必須包含至少 1 個、最多 1000 個註冊令牌。若要將訊息傳送到單一設備,請使用to參數。

多播訊息僅允許使用 HTTP JSON 格式。

condition可選,字串

此參數指定確定訊息目標的條件的邏輯表達式。

支援的條件:主題,格式為「主題中的'yourTopic'」。該值不區分大小寫。

支援的運算子: &&|| 。每個主題訊息最多支援兩個運算符。

notification_key
已棄用
可選,字串

該參數已被棄用。相反,請使用to來指定訊息收件人。有關如何向多個設備發送訊息的更多信息,請參閱適用於您的平台的文檔。

選項
collapse_key可選,字串

此參數標識一組可以折疊的訊息(例如,使用collapse_key: "Updates Available" ),以便在可以恢復傳遞時僅發送最後一條訊息。這是為了避免當設備恢復在線或變為活動狀態時發送太多相同的訊息。

請注意,無法保證訊息發送的順序。

注意:在任何給定時間最多允許使用 4 個不同的折疊鍵。這意味著 FCM 可以為每個客戶端應用程式同時儲存 4 個不同的訊息。如果超過此數量,則無法保證 FCM 將保留哪 4 個折疊鍵。

priority可選,字串

設定訊息的優先順序。有效值為“正常”和“高”。在 Apple 平台上,這些對應於 APN 優先權 5 和 10。

預設情況下,通知訊息以高優先順序發送,資料訊息以普通優先權發送。正常優先順序可最佳化用戶端應用程式的電池消耗,除非需要立即交付,否則應使用正常優先順序。對於具有正常優先權的訊息,應用程式可能會以未指定的延遲接收訊息。

當發送高優先級訊息時,會立即發送,並且應用程式可以顯示通知。

content_available可選,布林值

在 Apple 平台上,使用此欄位表示 APNs 負載中content-available 。當發送通知或訊息並將其設為true時,將喚醒不活動的客戶端應用程序,並且訊息將透過 APN 作為靜默通知發送,而不是透過 FCM 發送。請注意,APN 中的靜默通知不能保證一定會發送,並且可能取決於用戶打開低功耗模式、強制退出應用程式等因素。在 Android 上,預設情況下,資料訊息會喚醒應用程式。在 Chrome 上,目前不支援。

mutable_content可選,JSON 布林值

在 Apple 平台上,使用此欄位來表示 APNs 負載中的mutable-content 。當發送通知並將其設為true時,可以使用通知服務應用程式擴充功能在顯示通知之前修改通知的內容。對於 Android 和 Web,此參數將被忽略。

time_to_live可選,數量

此參數指定如果設備離線,訊息應在 FCM 儲存中保留多長時間(以秒為單位)。支援的最長生存時間為 4 週,預設值為 4 週。有關詳細信息,請參閱設定訊息的生命週期

restricted_package_
name
(僅限 Android)
可選,字串此參數指定應用程式的套件名稱,其中註冊令牌必須匹配才能接收訊息。
dry_run可選,布林值

當此參數設為true時,開發人員可以在不實際發送訊息的情況下測試請求。

預設值為false

有效載荷
data可選,對象

此參數指定訊息負載的自訂鍵值對。

例如,對於data:{"score":"3x1"}:

在 Apple 平台上,如果訊息是透過 APN 發送的,則它代表自訂資料欄位。如果透過 FCM 發送,它將在AppDelegate application:didReceiveRemoteNotification:中表示為鍵值字典。

在 Android 上,這將導致一個名為score的意圖額外,其字串值為3x1

鍵不應是保留字(“from”、“message_type”或任何以“google”或“gcm”開頭的單字)。不要使用此表中定義的任何單字(例如collapse_key )。

建議使用字串類型的值。您必須將物件或其他非字串資料類型(例如整數或布林值)中的值轉換為字串。

notification可選,對象此參數指定通知負載的預先定義、使用者可見的鍵值對。有關詳細信息,請參閱通知負載支援。有關通知訊息和資料訊息選項的更多信息,請參閱訊息類型。如果提供了通知負載,或發送至 Apple 裝置的訊息的content_available選項設為true ,則訊息將透過 APNs 傳送,否則將透過 FCM 傳送。

通知負載支持

下表列出了可用於建立 iOS 和 Android 通知訊息的預先定義鍵。

表 2a. iOS — 通知訊息按鍵

範圍用法描述
title可選,字串

通知的標題。

該欄位在手機和平板電腦上不可見。

body可選,字串

通知的正文。

sound可選,字串

設備收到通知時播放的聲音。

指定客戶端應用程式主包中或應用程式資料容器的Library/Sounds資料夾中的聲音檔案的字串。有關詳細信息,請參閱iOS 開發人員庫

badge可選,字串

主螢幕應用程式圖示上的徽章的值。

如果未指定,則不會變更徽章。

如果設定為0 ,則徽章將被刪除。

click_action可選,字串

與使用者點選通知關聯的操作。

對應於 APNs 負載中的category

subtitle可選,字串

通知的副標題。

body_loc_key可選,字串

應用程式字串資源中正文字串的鍵,用於將正文文字本地化為使用者目前的本地化。

對應於 APNs 負載中的loc-key

有關更多信息,請參閱有效負載密鑰參考本地化遠端通知的內容

body_loc_args可選,JSON 數組作為字串

用於取代body_loc_key中的格式說明符的變數字串值,用於將正文文字本地化為使用者目前的本地化。

對應於 APNs 負載中的loc-args

有關更多信息,請參閱有效負載密鑰參考本地化遠端通知的內容

title_loc_key可選,字串

應用程式字串資源中標題字串的鍵,用於將標題文字本地化為使用者目前的本地化版本。

對應於 APNs 負載中的title-loc-key

有關更多信息,請參閱有效負載密鑰參考本地化遠端通知的內容

title_loc_args可選,JSON 數組作為字串

用於取代title_loc_key中的格式說明符的變數字串值,用於將標題文字本地化為使用者目前的本地化。

對應於 APNs 負載中的title-loc-args

有關更多信息,請參閱有效負載密鑰參考本地化遠端通知的內容

表 2b. Android — 通知訊息按鍵

範圍用法描述
title可選,字串

通知的標題。

body可選,字串

通知的正文。

android_channel_id可選,字串

通知的頻道 ID (Android O 中的新增功能)。

在收到具有此通道 ID 的任何通知之前,應用程式必須建立具有此通道 ID 的通道。

如果您未在請求中傳送此通道 ID,或套用尚未建立提供的通道 ID,則 FCM 將使用應用程式清單中指定的通道 ID。

icon可選,字串

通知的圖示。

將可繪製資源myicon的通知圖示設定為myicon 。如果您不在請求中傳送此金鑰,FCM 將顯示應用程式清單中指定的啟動器圖示。

sound可選,字串

設備收到通知時播放的聲音。

支援"default"或應用程式中捆綁的聲音資源的檔案名稱。聲音檔案必須位於/res/raw/中。

tag可選,字串

用於替換通知抽屜中現有通知的標識符。

如果未指定,每個請求都會建立一個新通知。

如果指定並且已顯示具有相同標籤的通知,則新通知將取代通知抽屜中的現有通知。

color可選,字串

通知的圖示顏色,以#rrggbb格式表示。

click_action可選,字串

與使用者點選通知關聯的操作。

如果指定,當使用者按一下通知時,將啟動具有匹配意圖過濾器的活動。

body_loc_key可選,字串

應用程式字串資源中正文字串的鍵,用於將正文文字本地化為使用者目前的本地化。

有關詳細信息,請參閱字串資源

body_loc_args可選,JSON 數組作為字串

用於取代body_loc_key中的格式說明符的變數字串值,用於將正文文字本地化為使用者目前的本地化。

有關詳細信息,請參閱格式和样式

title_loc_key可選,字串

應用程式字串資源中標題字串的鍵,用於將標題文字本地化為使用者目前的本地化版本。

有關詳細信息,請參閱字串資源

title_loc_args可選,JSON 數組作為字串

用於取代title_loc_key中的格式說明符的變數字串值,用於將標題文字本地化為使用者目前的本地化。

有關詳細信息,請參閱格式和样式

表 2c. Web (JavaScript) — 通知訊息的鍵

範圍用法描述
title可選,字串

通知的標題。

body可選,字串

通知的正文。

icon可選,字串

用於通知圖示的 URL。

click_action可選,字串

與使用者點選通知關聯的操作。

對於所有 URL 值,都需要 HTTPS。

下游 HTTP 訊息(純文字)

下表列出了純文字下游 HTTP 訊息中的目標、選項和負載的語法。

表 3.下游純文字 HTTP 訊息的目標、選項和負載。

範圍用法描述
目標
registration_id必填,字串

此參數指定接收訊息的用戶端應用程式(註冊令牌)。

僅允許使用 HTTP JSON 格式進行多播訊息傳遞(傳送至多個註冊令牌)。

選項
collapse_key可選,字串詳情請參閱表1
time_to_live可選,數量詳情請參閱表1
restricted_package_name可選,字串詳情請參閱表1
dry_run可選,布林值詳情請參閱表1
有效載荷
data.<key>可選,字串

此參數指定訊息負載的鍵值對。鍵值參數的數量沒有限制,但訊息總大小限制為 4000 位元組。

例如,在 Android 中, "data.score"."3x1"將產生一個意圖額外命名的score ,字串值為3x1

鍵不應是保留字(“from”、“message_type”或任何以“google”或“gcm”開頭的單字)。不要使用此表中定義的任何單字(例如collapse_key )。

解釋下游訊息回應

應用伺服器應評估訊息回應標頭和正文,以解釋從 FCM 發送的訊息回應。下表描述了可能的回應。

表 4.下游 HTTP 訊息回應標頭。

回覆描述
200訊息已成功處理。回應正文將包含有關訊息狀態的更多詳細信息,但其格式將取決於請求是 JSON 還是純文字。更多詳情請參閱表5
400僅適用於 JSON 請求。表示請求無法解析為 JSON,或包含無效欄位(例如,在需要數字的地方傳遞了字串)。回應中描述了確切的失敗原因,並且應該在重試請求之前解決問題。
401驗證寄件者帳戶時發生錯誤。
5xx 500-599 範圍內的錯誤(例如 500 或 503)表示 FCM 後端在嘗試處理請求時出現內部錯誤,或伺服器暫時無法使用(例如,由於逾時)。發送者必須稍後重試,尊重回應中包含的任何Retry-After標頭。應用程式伺服器必須實現指數退避。

下表列出了下游訊息回應正文 (JSON) 中的欄位。

表 5.下游 HTTP 訊息回應正文 (JSON)。

範圍用法描述
multicast_id必填,數量標識多播訊息的唯一 ID(編號)。
success必填,數量已處理且沒有錯誤的訊息數。
failure必填,數量無法處理的訊息數。
results必需,物件數組表示已處理訊息的狀態的物件陣列。物件按照與請求相同的順序列出(即,對於請求中的每個註冊 ID,其結果在回應中的相同索引中列出)。
  • message_id :為每個成功處理的訊息指定唯一 ID 的字串。
  • error :指定為收件人處理訊息時發生的錯誤的字串。可能的值可在表 9中找到。

表 6.主題訊息 HTTP 回應正文 (JSON)。

範圍用法描述
message_id可選,數量FCM 成功接收請求並將嘗試傳遞到所有訂閱裝置時的主題訊息 ID。
error可選,字串處理訊息時發生錯誤。可能的值可在表 9中找到。

表 7.下游 HTTP 訊息回應正文的成功回應(純文字)。

範圍用法描述
id必填,字串此參數指定 FCM 處理成功的唯一訊息 ID。
registration_id可選,字串此參數指定處理訊息並將其發送到的客戶端應用程式的註冊令牌。

表 8.下游 HTTP 訊息回應正文的錯誤回應(純文字)。

範圍用法描述
Error必填,字串此參數指定為收件人處理訊息時的錯誤值。詳細資訊請參閱表9

下游報文錯誤回應碼

下表列出了下游訊息的錯誤回應碼。

表 9.下游訊息錯誤回應代碼。

錯誤HTTP 程式碼建議操作
缺少註冊令牌200 + 錯誤:缺少註冊檢查請求是否包含註冊令牌(在純文字訊息中的registration_id中,或在 JSON 中的toregistration_ids欄位中)。
註冊令牌無效200 + 錯誤:無效註冊檢查您傳遞給伺服器的註冊令牌的格式。確保它與客戶端應用程式透過 Firebase 通知註冊收到的註冊令牌相符。不要截斷或添加額外的字元。
未註冊設備200 + 錯誤:未註冊現有的註冊令牌可能在多種情況下不再有效,包括:
  • 如果用戶端應用程式向 FCM 取消註冊。
  • 如果用戶端應用程式自動取消註冊(如果用戶卸載該應用程序,則可能會發生這種情況)。例如,在 iOS 上,如果 APNs 回饋服務將 APNs 令牌報告為無效。
  • 如果註冊令牌過期(例如,Google 可能決定刷新註冊令牌,或 iOS 裝置的 APNs 令牌已過期)。
  • 如果用戶端應用程式已更新,但新版本未配置為接收訊息。
對於所有這些情況,請從應用程式伺服器中刪除此註冊令牌並停止使用它發送訊息。
包名稱無效200 + 錯誤:InvalidPackageName確保訊息傳送至註冊令牌,其套件名稱與請求中傳遞的值相符。
授權錯誤401用於發送訊息的寄件者帳戶無法通過身份驗證。可能的原因有:
  • HTTP 請求中缺少授權標頭或語法無效。
  • 指定伺服器金鑰所屬的 Firebase 項目不正確。
  • 僅舊伺服器金鑰 - 請求源自未列入伺服器金鑰 IP 白名單的伺服器。
檢查您在身份驗證標頭內發送的令牌是否是與您的項目關聯的正確伺服器金鑰。有關詳細信息,請參閱檢查伺服器金鑰的有效性。如果您使用的是舊版伺服器金鑰,建議您升級到沒有 IP 限制的新金鑰。請參閱遷移舊伺服器密鑰
寄件者不匹配200 + 錯誤:不符合寄件者 ID註冊令牌與特定的發送者群組相關聯。當客戶端應用程式註冊 FCM 時,它必須指定允許哪些寄件者傳送訊息。向客戶端應用程式發送訊息時,您應該使用這些寄件者 ID 之一。如果您切換到其他寄件人,現有的註冊令牌將無法運作。
無效的 JSON 400檢查 JSON 訊息的格式是否正確並包含有效欄位(例如,確保傳入正確的資料類型)。
無效參數400 + 錯誤:參數無效檢查提供的參數是否具有正確的名稱和類型。
訊息太大200 + 錯誤:MessageTooBig檢查訊息中包含的有效負載資料的總大小是否超過 FCM 限制:大多數訊息為 4096 字節,對於主題訊息為 2048 位元組。這包括鍵和值。
資料金鑰無效200+錯誤:
無效的資料金鑰
檢查負載資料是否不包含 FCM 內部使用的金鑰(例如fromgcm或任何以google為前綴的值)。請注意,FCM 也使用某些單字(例如collapse_key ),但在有效負載中允許使用,在這種情況下,有效負載值將被 FCM 值覆蓋。
無效生存時間200 + 錯誤:InvalidTtl檢查time_to_live中使用的值是否為整數,表示 0 到 2,419,200(4 週)之間的持續時間(以秒為單位)。
暫停5xx 或 200 + 錯誤:不可用

伺服器無法及時處理請求。重試相同的請求,但您必須:

  • 如果Retry-After標頭包含在 FCM 連線伺服器的回應中,請遵守該標頭。
  • 在重試機制中實施指數退避。 (例如,如果您在第一次重試之前等待一秒,則在下一次重試之前至少等待兩秒,然後等待 4 秒,依此類推)。如果您要發送多個訊息,請將每個訊息獨立延遲一個額外的隨機量,以避免同時對所有訊息發出新請求。

造成問題的寄件者可能會被列入黑名單。

內部伺服器錯誤500 或 200 + 錯誤:InternalServerError伺服器在嘗試處理請求時遇到錯誤。您可以按照「超時」中列出的要求重試相同的請求(請參閱上面的行)。如果錯誤仍然存在,請聯絡Firebase 支援
設備訊息速率超出200+錯誤:
裝置訊息速率
超過

向特定裝置發送訊息的速率太高。如果 Apple 應用程式以超出 APNs 限制的速率發送訊息,則可能會收到此錯誤訊息

減少發送到該裝置的訊息數量並使用指數退避來重試發送。

主題 訊息速率超出200+錯誤:
主題留言率
超過
向特定主題的訂閱者發送訊息的比率太高。減少為此主題發送的訊息數量並使用指數退避來重試發送。
APNs 憑證無效200+錯誤:
無效的 Apns 憑證
無法傳送針對 Apple 裝置的訊息,因為所需的 APNs 驗證金鑰未上傳或已過期。檢查您的開發和生產憑證的有效性。

設備分組管理

下表列出了用於建立設備群組以及新增和刪除成員的按鍵。有關更多信息,請參閱適用於您的平台( iOS+Android)的指南。

表 10.設備組管理金鑰。

範圍用法描述
operation必填,字串要執行的操作。有效值為createaddremove
notification_key_name必填,字串若要建立或修改的設備群組的使用者定義名稱。
notification_key必填( create操作除外,字串設備組的唯一識別碼。該值在成功create操作的回應中傳回,並且是設備群組上的所有後續操作所必需的。
registration_ids必需,字串數組若要新增或刪除的設備令牌。如果您從裝置群組中刪除所有現有註冊令牌,FCM 會刪除該裝置群組。