Firebase 雲端通訊 HTTP 通訊協定

本文件提供 HTTP 語法參考資料，可用於透過 Firebase Cloud Messaging 將訊息從應用程式伺服器傳送至用戶端應用程式。

使用舊版 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 選用，字串

設定訊息的優先順序。有效值為「normal」和「high」。在 Apple 平台上，這些優先順序對應至 APN 5 和 10。

根據預設，系統會以高優先順序傳送通知訊息，以一般優先順序傳送資料訊息。正常優先順序可最佳化用戶端應用程式的電池消耗量，除非需要立即傳送，否則應使用這類順序。對於優先順序為「一般」的訊息，應用程式可能會在未指定的延遲時間後收到訊息。

以高優先順序傳送的訊息會立即傳送，應用程式可以顯示通知。
content_available 選用，布林值

在 Apple 平台上，請使用這個欄位代表 APN 酬載中的 content-available。傳送通知或訊息時，如果將其設為 true，系統會喚醒閒置的用戶端應用程式，並透過 APN 傳送訊息，做為靜默通知，而非透過 FCM 傳送。請注意，APN 中的靜默通知不保證會傳送，且可能會受到使用者開啟省電模式、強制結束應用程式等因素影響。在 Android 上，資料訊息預設會喚醒應用程式。目前不支援在 Chrome 上使用。
mutable_content 選用，JSON 布林值

在 Apple 平台上，請使用這個欄位代表 APN 酬載中的 mutable-content。當通知傳送且已設為 true 時，您可以使用 通知服務應用程式擴充功能，在通知顯示前修改通知內容。系統會忽略 Android 和網頁的此參數。
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 選用，物件 這個參數會指定通知酬載的預先定義使用者可見鍵/值組合。詳情請參閱通知酬載支援。如要進一步瞭解通知訊息和資料訊息選項，請參閱「 訊息類型」。如果提供通知酬載，或是將 content_available 選項設為 true，以便傳送訊息至 Apple 裝置，則系統會透過 APN 傳送訊息；否則，則會透過 FCM 傳送。

通知酬載支援

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

表 2a. iOS - 通知訊息的鍵

參數 用量 說明
title 選用，字串

通知的標題。

這個欄位不會顯示在手機和平板電腦上。

body 選用，字串

通知的內文。

sound 選用，字串

裝置收到通知時要播放的音效。

字串，指定用戶端應用程式主套件或應用程式資料容器的 Library/Sounds 資料夾中的音效檔案。詳情請參閱 iOS 開發人員資料庫。
badge 選用，字串

主畫面應用程式圖示上的徽章值。

如未指定，徽章不會變更。

如果設為 0，則會移除徽章。
click_action 選用，字串

使用者點選通知時會觸發的動作。

對應至 APN 酬載中的 category。
subtitle 選用，字串

通知的副標題。
body_loc_key 選用，字串

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

對應至 APN 酬載中的 loc-key。

詳情請參閱「 酬載鍵參考資料」和「 將遠端通知內容本地化」。
body_loc_args 選用：JSON 陣列做為字串

變數字串值，可用於取代 body_loc_key 中的格式指定符，以便將內文本地化為使用者目前的語言。

對應至 APN 酬載中的 loc-args。

詳情請參閱「 酬載鍵參考資料」和「 將遠端通知內容本地化」。
title_loc_key 選用，字串

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

對應至 APN 酬載中的 title-loc-key。

詳情請參閱「 酬載鍵參考資料」和「 將遠端通知內容本地化」。
title_loc_args 選用：JSON 陣列做為字串

變數字串值，可用於取代 title_loc_key 中的格式指定符，以便將標題文字本地化為使用者的目前語言。

對應至 APN 酬載中的 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 選用，字串

用於取代通知導覽匣中現有通知的 ID。

如果未指定，每個要求都會建立新的通知。

如果已指定，且系統正在顯示同一個標記的通知，新通知會取代通知列中的現有通知。
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. 網路 (JavaScript)：通知訊息的鍵

參數 用量 說明
title 選用，字串

通知的標題。

body 選用，字串

通知的內文。

icon 選用，字串

用於通知圖示的網址。
click_action 選用，字串

使用者點選通知時會觸發的動作。

所有網址值都必須使用 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> 選用，字串

此參數會指定訊息酬載的鍵/值組合。鍵/值參數數量沒有限制，但總訊息大小上限為 4096 位元組。

舉例來說，在 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 必要，字串 這個參數會指定成功處理的專屬訊息 ID FCM。
registration_id 選用，字串 這個參數會為用戶端應用程式指定註冊權杖，該應用程式會處理及傳送訊息。

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

參數 用量 說明
Error 必要，字串 這個參數會在處理收件者的訊息時指定錯誤值。詳情請參閱表格 9。

下游訊息錯誤回應代碼

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

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

錯誤 HTTP 代碼 建議做法
缺少註冊權杖 200 + 錯誤：MissingRegistration 確認要求包含註冊權杖 (位於純文字訊息的 registration_id 中，或位於 JSON 中的 to 或 registration_ids 欄位)。
無效的註冊權杖 200 + error:InvalidRegistration 請檢查您傳遞至伺服器的註冊權杖格式。請確認該值與用戶端應用程式透過 Firebase Notifications 註冊所收到的註冊權杖相符。請勿截斷或新增其他字元。
未註冊的裝置 200 + error:NotRegistered 在許多情況下，現有的註冊權杖可能會失效，包括：
  • 如果用戶端應用程式已取消註冊 FCM。
  • 如果用戶端應用程式會自動取消註冊，這可能會發生在使用者解除安裝應用程式時。舉例來說，如果在 iOS 上，APNs 回饋服務回報 APNs 權杖無效。
  • 如果註冊權杖到期 (例如 Google 可能決定重新整理註冊權杖，或是 iOS 裝置的 APN 權杖到期)。
  • 如果用戶端應用程式已更新，但新版本未設定為接收訊息。
在所有這些情況下，請從應用程式伺服器中移除此註冊權杖，並停止使用該權杖傳送訊息。
套件名稱無效 200 + error:InvalidPackageName 請確認訊息已傳送至註冊權杖，且權杖的套件名稱與要求中傳遞的值相符。
驗證錯誤 401 系統無法驗證用來傳送郵件的寄件者帳戶。可能的原因包括：
  • HTTP 要求中缺少授權標頭或含有無效的語法。
  • 指定的伺服器金鑰所屬的 Firebase 專案有誤。
  • 僅限舊版伺服器金鑰：要求來自未列入伺服器金鑰 IP 白名單的伺服器。
請確認您在驗證標頭中傳送的符記，是否為與專案相關聯的正確伺服器金鑰。詳情請參閱「檢查伺服器金鑰的有效性 」。如果您使用的是舊版伺服器金鑰，建議您升級至沒有 IP 限制的新金鑰。請參閱「 遷移舊版伺服器金鑰」一文。
寄件者不符 200 + error:MismatchSenderId 註冊權杖會與特定一組寄件者相關聯。當用戶端應用程式註冊 FCM 時，必須指定哪些寄件者可以傳送訊息。傳送訊息至用戶端應用程式時，請使用其中一個傳送者 ID。如果切換至其他傳送者，現有的註冊權杖就無法運作。
JSON 無效 400 檢查 JSON 訊息的格式是否正確，並包含有效的欄位 (例如，確保傳入正確的資料類型)。
無效的參數 400 + error:InvalidParameters 確認提供的參數名稱和類型正確無誤。
訊息過大 200 + error:MessageTooBig 請確認郵件中附帶的酬載資料總大小不超過 FCM 限制：大多數郵件的大小為 4096 個位元組，郵件傳送至主題時則為 2048 個位元組。包括鍵和值。
資料鍵無效 200 + 錯誤：
InvalidDataKey		 請確認酬載資料不含 FCM 內部使用的鍵 (例如 from、gcm 或任何前面有 google 的值)。請注意，FCM 也會使用部分字詞 (例如 collapse_key)，但這些字詞在酬載中是允許的，在這種情況下，酬載值會遭到 FCM 值覆寫。
存留時間無效 200 + error:InvalidTtl 請確認 time_to_live 中使用的值為整數，代表 0 到 2,419,200 秒 (4 週) 之間的時間長度。
逾時時間 5xx 或 200 以上錯誤：無法使用

伺服器無法及時處理要求。重試相同要求，但您必須：

  • 如果 Retry-After 標頭包含在 FCM 連線伺服器的回應中，請遵循該標頭。
  • 在重試機制中實作指數輪詢。(例如，如果您在第一次重試前等待一秒，請在下次重試前等待至少兩秒，然後是 4 秒，依此類推)。如果您傳送多則訊息，請為每則訊息額外增加隨機延遲時間，避免同時針對所有訊息發出新要求。

造成問題的寄件者可能會遭到列入黑名單。
內部伺服器錯誤 500 或 200 + error:InternalServerError 伺服器在處理要求時發生錯誤，您可以按照「逾時」(請參閱上方列) 中的規定重試相同要求。如果錯誤持續發生，請與 Firebase 支援團隊聯絡。
裝置訊息傳送頻率超出上限 200 以上錯誤：
DeviceMessageRate
超出限制

傳送至特定裝置的訊息比率過高。如果 Apple 應用程式傳送訊息的頻率超過 APN 限制，可能會收到這則錯誤訊息

請減少傳送至此裝置的訊息數量，並使用指數輪詢重試傳送。
主題訊息傳送頻率超出上限 200 以上錯誤：
TopicsMessageRate
超出上限		 向特定主題訂閱者的訊息比率過高。減少為此主題傳送的訊息數量，並使用指數輪詢重試傳送。
APN 憑證無效 200 + 錯誤：
InvalidApnsCredential 		由於未上傳必要的 APN 驗證金鑰或金鑰已過期，因此無法傳送指定 Apple 裝置的訊息。檢查開發和正式版憑證是否有效。

裝置群組管理

下表列出建立裝置群組、新增及移除成員的索引鍵。如需更多資訊，請參閱您平台的相關指南： iOS+ 或 Android。

表 10. 裝置群組管理鍵。

參數 用量 說明
operation 必要，字串 要執行的作業。有效值為 create、add 和 remove。
notification_key_name 必要，字串 要建立或修改的裝置群組使用者定義名稱。
notification_key 必填 (除了 create 作業、字串 裝置群組的專屬 ID。這個值會在成功的 create 作業回應中傳回，且為裝置群組的所有後續作業所需。
registration_ids 必要項目，字串陣列 要新增或移除的裝置符記。如果您從裝置群組中移除所有現有註冊權杖，FCM 會刪除裝置群組。