關於 FCM 訊息

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Firebase Cloud Messaging (FCM) 提供多種訊息傳送選項和功能。本頁面提供的資訊旨在協助您瞭解不同類型的 FCM 訊息，以及如何使用這些訊息。

訊息類型

您可以使用 FCM 向用戶端傳送兩種類型的訊息：

• 通知訊息，有時也稱為「顯示訊息」。這些事件會由 FCM SDK 自動處理。
• 由用戶端應用程式處理的資料訊息。

通知訊息包含一組預先定義的使用者可見鍵。相反地，資料訊息只包含使用者定義的自訂鍵/值組合。通知訊息可包含選用的資料酬載。兩種訊息類型的酬載大小上限為 4096 個位元組，但從 Firebase 主控台傳送訊息時，系統會強制限制為 1000 個字元。

如要讓 FCM SDK 在應用程式於背景執行時自動顯示通知，請使用通知訊息。如要使用自己的用戶端應用程式程式碼處理訊息，請使用資料訊息。

FCM 可以傳送通知訊息，包括選用的資料酬載。在這種情況下，FCM 會負責顯示通知酬載，而用戶端應用程式會處理資料酬載。

通知訊息

如要進行測試，或是用於行銷和使用者再參與，您可以使用 Firebase 控制台傳送通知訊息。Firebase 控制台提供以數據為基礎的 A/B 測試功能，協助您調整及改善行銷訊息。

如要使用程式輔助方式透過 Admin SDK 或 FCM 通訊協定傳送通知訊息，請為通知訊息的使用者可見部分，設定 notification 鍵，並為該鍵提供必要的預先定義鍵/值選項組合。舉例來說，以下是 IM 應用程式中 JSON 格式的通知訊息。使用者會在裝置上看到標題為「Portugal vs. Denmark」的訊息，以及「great match!」的文字：

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

應用程式在背景運作時，通知訊息會傳送至通知匣。對於前景應用程式，系統會使用回呼函式處理訊息。

如需可用於建立通知訊息的完整預先定義鍵清單，請參閱 HTTP v1 通訊協定通知物件參考說明文件。

資料訊息

使用自訂的鍵/值組合設定適當的鍵，以便將資料酬載傳送至用戶端應用程式。

舉例來說，以下是與上述相同的即時通訊應用程式中，以 JSON 格式呈現的訊息，其中資訊已封裝在常見的 data 鍵中，而用戶端應用程式應會解讀內容：

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

上例顯示頂層或常見的 data 欄位用法，這些欄位會在收到訊息的所有平台上由用戶端解讀。在每個平台上，用戶端應用程式都會在回呼函式中接收資料酬載。

資料訊息的加密

Android 傳輸層 (請參閱 FCM 架構) 會使用點對點加密。視您的需求而定，您可以選擇為資料訊息加入端對端加密功能。FCM 不提供端對端解決方案。不過，您可以使用 Capillary 或 DTLS 等外部解決方案。

含有選用資料酬載的通知訊息

您可以透過程式設計或 Firebase 控制台，傳送包含自訂鍵/值組合選用酬載的通知訊息。在 通知編輯器中，使用進階選項中的自訂資料欄位。

應用程式在收到同時包含通知和資料酬載的訊息時，其行為取決於應用程式處於背景或前景，也就是說，取決於應用程式在收到訊息時是否處於活動狀態。

• 在背景執行時，應用程式會在通知匣中收到通知酬載，並只在使用者輕觸通知時處理資料酬載。
• 在前景運作時，應用程式會收到含有兩種酬載的可用訊息物件。

以下是 JSON 格式的訊息，其中包含 notification 鍵和 data 鍵：

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

跨平台自訂訊息

Firebase Admin SDK 和 FCM v1 HTTP 通訊協定都允許訊息要求設定 message 物件中可用的所有欄位。包括：

• 一組常見的欄位，可供所有接收訊息的應用程式執行個體解讀。
• 特定平台的欄位組合 (例如 AndroidConfig 和 WebpushConfig)，僅由在指定平台上執行的應用程式執行個體解讀。

您可以使用特定平台的區塊，靈活地為不同平台自訂訊息，確保訊息在收到時能正確處理。FCM 後端會考量所有指定參數，並為各平台自訂訊息。

使用常用欄位的時機

使用常用欄位時，請注意：

• 指定所有平台 (Apple、Android 和網站) 上的應用程式執行個體
• 將訊息傳送至主題

無論平台為何，所有應用程式例項都能解讀下列常見欄位：

• message.notification.title
• message.notification.body
• message.data

使用特定平台欄位的時機

請在下列情況下使用平台專屬欄位：

• 只將欄位傳送至特定平台
• 除了一般欄位外，也傳送特定平台欄位

如要只將值傳送至特定平台，請不要使用通用欄位，請使用特定平台的欄位。舉例來說，如果您想只將通知傳送給 Apple 平台和網頁，但不傳送給 Android，就必須使用兩組不同的欄位，一組用於 Apple，另一組用於網頁。

傳送含有特定傳送選項的郵件時，請使用特定平台的欄位進行設定。您可以視需要為每個平台指定不同的值。不過，即使您想在各平台上設定相同的值，也必須使用平台專屬欄位。這是因為每個平台對這個值的解讀方式略有不同。舉例來說，Android 將生命週期設為以秒為單位的到期時間，而 Apple 則將生命週期設為到期日期。

範例：含有平台專屬提交選項的通知訊息

下列 v1 傳送要求會將常見的通知標題和內容傳送至所有平台，但也會傳送一些平台專屬的覆寫值。具體來說，要求如下：

• 為 Android 和網頁平台設定長的有效時間，同時將 APN (Apple 平台) 訊息優先順序設為低
• 設定適當的鍵，定義使用者在 Android 和 Apple 上輕觸通知的結果，分別為 click_action 和 category。

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

如要進一步瞭解郵件主體中平台專屬區塊可用的鍵，請參閱 HTTP v1 參考說明文件。如要進一步瞭解如何建立含有郵件主體的傳送要求，請參閱「建立傳送要求」。

外送選項

FCM 為傳送至 Android 裝置的訊息提供特定的傳送選項組合，並允許在 Apple 平台和網站上使用類似的選項。舉例來說，Android 支援透過 FCM 的 collapse_key 使用「可摺疊」訊息行為，Apple 則是透過 apns-collapse-id，而 JavaScript/Web 則是透過 Topic。詳情請參閱本節和相關參考說明文件中的說明。

不可收合和可收合的訊息

不可收合的訊息表示每則個別訊息都會傳送至裝置。不收折疊的訊息會提供一些實用的內容，而非收折疊的訊息則會提供無內容的「ping」訊息，用於與伺服器聯絡以擷取資料。

不顯示收合按鈕的訊息常見用途包括即時通訊訊息或重要訊息。舉例來說，在即時通訊應用程式中，您會希望傳送每則訊息，因為每則訊息都有不同的內容。

在 Android 中，最多可儲存 100 則訊息，且不會折疊。如果達到限制，系統會捨棄所有儲存的訊息。裝置重新上線後，會收到一則特殊訊息，指出已達到上限。應用程式就能妥善處理這種情況，通常會要求應用程式伺服器進行完整同步處理。

可摺疊訊息是指尚未傳送至裝置的訊息，可能會被新訊息取代。

可摺疊訊息的常見用途是用於通知行動應用程式同步伺服器資料。舉例來說，體育應用程式會向使用者更新最新比分。只有最新的訊息才有參考價值。

如要在 Android 上將訊息標示為可摺疊，請在訊息酬載中加入 collapse_key 參數。根據預設，摺疊鍵是 Firebase 主控台中登錄的應用程式套件名稱。FCM 伺服器可為每部裝置同時儲存四則不同的可摺疊訊息，每則訊息都有不同的摺疊鍵。如果超過這個數量，FCM 只會保留四個折疊鍵，且無法保證會保留哪些鍵。

根據預設，沒有酬載的專訊會收折疊。通知訊息一律可摺疊，且會忽略 collapse_key 參數。

我該使用哪一個？

從效能角度來看，只要您的應用程式不需要使用不可收合訊息，使用可收合訊息會是更好的選擇。不過，如果您使用可摺疊的訊息，請注意，FCM 在任何特定時間點，最多只允許 FCM 使用每個註冊權杖的四個不同摺疊鍵。請勿超過這個數量，否則可能會導致無法預測的後果。

設定訊息的優先順序

您可以為下游郵件指派傳送優先順序，有兩種選項：一般和高優先順序。雖然不同平台的行為略有差異，但一般和高優先順序訊息的傳送方式如下：

• 一般優先順序。 應用程式位於前景時，系統會立即傳送一般優先順序的訊息。對於背景應用程式，傳送作業可能會延遲。如果是較不受時間限制的訊息，例如新電子郵件的通知、保持 UI 同步，或在背景同步處理應用程式資料，請選擇一般傳送優先順序。

• 高優先順序。即使裝置處於 Doze 模式，FCM 仍會嘗試立即傳送高優先順序訊息。高優先順序訊息適用於有時效性、使用者可見的內容。

以下是透過 FCM HTTP v1 通訊協定傳送的一般優先訊息範例，用於通知雜誌訂閱者可下載新內容：

{
  "message":{
    "topic":"subscriber-updates",
    "notification":{
      "body" : "This week's edition is now available.",
      "title" : "NewsMagazine.com",
    },
    "data" : {
      "volume" : "3.21.15",
      "contents" : "http://www.news-magazine.com/world-week/21659772"
    },
    "android":{
      "priority":"normal"
    },
    "apns":{
      "headers":{
        "apns-priority":"5"
      }
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      }
    }
  }
}

如要進一步瞭解如何設定訊息優先順序，請參閱以下平台的相關說明：

• APN 說明文件
• 設定及管理訊息優先順序 (Android)
• 網頁推播訊息的緊急程度

生命攸關的用途

FCM API 並非設計用於緊急警報或其他高風險活動，因為使用或發生 API 故障時，可能會導致死亡、人身傷害或環境損害 (例如核子設施、空中交通管制或維生系統的操作)。根據第 4.a 節規定，我們明文禁止這類使用行為。7 服務條款。您必須自行負責管理應用程式是否遵守「條款」，以及因違反「條款」而產生的任何損害。Google 提供的 API 為「現況」版本，且保留隨時基於任何理由停止提供 API 或其中任何部分或功能，或終止您對這些項目的存取權限，且無須向您或您的使用者承擔責任或履行其他義務。

設定訊息的生命週期

FCM 通常會在訊息傳送後立即傳送。不過，這不一定可行。舉例來說，如果平台是 Android，裝置可能會關機、離線或無法使用。或者，FCM 可能會刻意延遲訊息，避免應用程式消耗過多資源，進而影響電池續航力。

在這種情況下，FCM 會儲存訊息，並盡快傳送。雖然在大多數情況下這都沒問題，但有些應用程式可能會導致延遲訊息永遠無法傳送。舉例來說，如果訊息是來電或視訊通話通知，只有在通話結束前短短的一段時間內才有意義。或者，如果訊息是活動邀請，在活動結束後收到這類訊息就沒有用處。

在 Android 和 Web/JavaScript 中，您可以指定訊息的最大生命週期。這個值必須是 0 到 2,419,200 秒 (28 天) 之間的時間長度，且對應於 FCM 儲存訊息並嘗試傳送訊息的最長時間。不含此欄位的請求預設為四週的上限期間。

以下是這項功能的幾種可能用途：

• 視訊通話來電
• 邀請活動到期
• 日曆活動

指定訊息生命週期的另一個優點是，FCM 不會將可折疊訊息調節功能套用至有效時間值為 0 秒的訊息。FCM 會盡力處理必須「立即傳送」的訊息。請注意，time_to_live 值為 0 表示系統會捨棄無法立即傳送的訊息。不過，由於這類訊息永遠不會儲存，因此可提供最佳的通知訊息傳送延遲時間。

以下是含有 TTL 的請求範例：

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    },
    "apns":{
      "headers":{
        "apns-expiration":"1604750400"
      }
    },
    "android":{
      "ttl":"4500s"
    },
    "webpush":{
      "headers":{
        "TTL":"4500"
      }
    }
  }
}

訊息的生命週期

當應用程式伺服器將訊息發布至 FCM，並收到訊息 ID 回應時，並不代表訊息已傳送至裝置。而是表示郵件已通過郵件系統的接收程序。訊息接受後的處理方式取決於許多因素。

在最佳情況下，如果裝置已連線至 FCM、螢幕已開啟且沒有節流限制，系統會立即傳送訊息。

如果裝置已連線但處於 Doze 模式，FCM 會儲存低優先順序訊息，直到裝置離開 Doze 模式為止。這就是 collapse_key 標記發揮作用的地方：如果已經有訊息使用相同的折疊鍵 (和註冊權杖) 儲存在系統中，並等待傳送，舊訊息就會遭到捨棄，新訊息會取而代之 (也就是舊訊息會被新訊息折疊)。不過，如果未設定折疊鍵，系統會儲存新訊息和舊訊息，以便日後傳送。

如果裝置未連線至 FCM，系統會儲存訊息，直到建立連線為止 (再次遵循折疊鍵規則)。建立連線後，FCM 會將所有待處理訊息傳送至裝置。如果裝置從未再次連線 (例如已恢復原廠設定)，訊息最終會逾時，並從 FCM 儲存空間中捨棄。除非設定 time_to_live 旗標，否則預設逾時時間為四週。

如要進一步瞭解訊息的傳送情況，請按照下列步驟操作：

如要進一步瞭解 Android 或 Apple 平台上的訊息遞送情況，請參閱 FCM 報表資訊主頁，這裡會記錄在 Apple 和 Android 裝置上傳送及開啟的訊息數量，以及 Android 應用程式「曝光次數」(使用者看到的通知) 資料。

如果 Android 裝置已啟用直接管道訊息功能，且裝置未連線至 FCM 超過一個月，FCM 仍會接受訊息，但會立即捨棄。如果裝置在您上次傳送資料訊息後的四週內連線，您的用戶端就會收到 onDeletedMessages() 回呼。應用程式就能妥善處理這種情況，通常會要求應用程式伺服器進行完整同步處理。

最後，當 FCM 嘗試將訊息傳送至裝置，但應用程式已解除安裝時，FCM 會立即捨棄該訊息，並使註冊權杖失效。日後嘗試傳送訊息至該裝置時，就會導致 NotRegistered 錯誤。

節流和配額

我們的目標是確保每則透過 FCM 傳送的訊息都能送達。不過，有時傳送每則訊息都會導致整體使用者體驗不佳。在其他情況下，我們需要提供限制，確保 FCM 可為所有寄件者提供可擴充的服務。本節所述的限制和配額類型有助於平衡這些重要因素。

下游訊息節流

HTTP v1 API 為下游訊息引進了專案層級的每分鐘配額。預設配額為每分鐘 60 萬則訊息，可涵蓋 99% 的 FCM 開發人員，同時確保系統穩定性，並盡量減少尖峰專案的影響。

尖峰流量模式可能會導致配額超出錯誤。在配額超出情況下，系統會傳回 HTTP 狀態碼 429 (QUOTA_EXCEEDED)，直到下一個分鐘配額重新填滿為止。在超載情況下，系統也可能會傳回 429 回應，因此強烈建議您按照已發布的最佳化建議處理 429 回應。

注意事項：

• 下游配額會評估訊息，而非要求。
• 系統會計算用戶端錯誤 (HTTP 狀態碼 400-499) (不含 429)。
• 配額是以分鐘為單位，但這些分鐘並未與時鐘對齊。

監控配額

您可以在 Google Cloud 控制台查看配額、用量和錯誤：

1. 前往 Google Cloud 控制台
2. 選取「API 和服務」
3. 從表格清單中選取「Firebase Cloud Messaging API」
4. 選取「配額與系統限制」。

注意：這些圖表並未精確對齊配額分鐘，因此當流量似乎低於配額時，可能會傳送 429 錯誤。

申請提高配額

申請提高配額前，請確認以下事項：

• 您的用量通常會達到配額的 80%，且每天至少連續 5 分鐘。
• 您有 < 5% 的用戶端錯誤比率，尤其是在流量高峰期間。
• 您遵循大規模傳送訊息的最佳做法。

如果您符合這些條件，可以提交配額調高要求，最多可調高 25%，FCM 會盡力滿足您的要求 (但無法保證一定能調高)。

如果您因即將推出的產品或臨時活動而需要更多訊息下游配額，請提前至少 15 天提出配額申請，以便我們有足夠的時間處理您的要求。如果是大型要求 (每分鐘超過 1,800 萬則訊息)，則至少需要 30 天的通知時間。啟動和特殊事件要求仍須遵守用戶端錯誤比率和最佳做法規定。

另請參閱 FCM 配額的常見問題。

主題訊息限制

主題訂閱新增/移除頻率上限為每個專案 3,000 QPS。

如要瞭解訊息傳送率，請參閱「分支節流」。

擴散傳遞節流

訊息分發是指將訊息傳送至多個裝置的程序，例如指定主題和群組，或是使用通知編輯器指定目標對象或使用者區隔。

訊息分支並非即時發生，因此有時會同時進行多個分支。我們將每項專案的並行訊息分支數量限制為 1,000 個。之後，我們可能會拒絕額外的分支要求，或將要求的分支延後，直到部分已進行的分支作業完成為止。

實際可達的發散率會受到同時要求發散的專案數量影響。個別專案的扇形比率達到 10,000 QPS 並不少見，但這並非保證，而是系統總負載的結果。請注意，可用的分支容量會分配給各個專案，而非分支要求。因此，如果您的專案有兩個正在進行的發散，則每個發散只會看到可用的發散率的一半。建議您一次只執行一個有效的扇形展開作業，以便盡量提高扇形展開速度。

可收合的訊息節流

如上所述，可摺疊訊息是沒有內容的通知，設計目的是讓訊息可摺疊疊放。如果開發人員經常重複傳送相同的訊息給應用程式，我們會延遲 (節流) 訊息，以減少對使用者電池的影響。

舉例來說，如果您向單一裝置傳送大量新的電子郵件同步處理要求，我們可能會延遲下一個電子郵件同步處理要求幾分鐘，以便裝置以較低的平均速率同步處理。這項節流功能的目的，是嚴格限制使用者體驗的電池效能影響。

如果您的用途需要高峰傳送模式，則不應收合訊息可能會是合適的選擇。針對這類訊息，請務必在訊息中加入內容，以減少電池消耗。

我們限制可摺疊訊息的數量，每個裝置每個應用程式最多 20 則，每 3 分鐘補充 1 則。

單一裝置的訊息傳送速度上限

針對 Android，您最多可向單一裝置傳送 240 則訊息/分鐘和 5,000 則訊息/小時。這個高門檻旨在允許短期流量激增，例如使用者透過即時通訊快速互動時。這項限制可避免傳送邏輯中的錯誤意外耗盡裝置電量。

在 iOS 中，如果頻率超過 APN 限制，我們會傳回錯誤。

FCM 通訊埠和防火牆

如果貴機構有防火牆來限制來自或前往網際網路的流量，您必須設定防火牆，允許行動裝置連線至 FCM，讓網路上的裝置能夠接收訊息。FCM 通常會使用 5228 埠，但有時也會使用 443、5229 和 5230。

對於連線至您網路的裝置，FCM 不會提供特定 IP，因為我們的 IP 範圍變動頻繁，您的防火牆規則可能會過時，進而影響使用者體驗。理想情況下，您應將通訊埠 5228-5230 和 443 加入白名單，且不設 IP 限制。不過，如果您必須設有 IP 限制，請將 goog.json 中列出的所有 IP 位址加入許可清單。這份龐大的清單會定期更新，建議您每月更新規則。防火牆 IP 限制造成的問題通常會間歇性發生，且難以診斷。

我們提供一組可加入許可清單的網域名稱，而非 IP 位址。這些主機名稱如下所列。如果我們開始使用其他主機名稱，我們會在這裡更新清單。在防火牆規則中使用網域名稱，在防火牆裝置中可能無法正常運作。

要開啟的 TCP 通訊埠：

• 5228
• 5229
• 5230
• 443

要開啟的主機名稱：

• mtalk.google.com
• mtalk4.google.com
• mtalk-staging.google.com
• mtalk-dev.google.com
• alt1-mtalk.google.com
• alt2-mtalk.google.com
• alt3-mtalk.google.com
• alt4-mtalk.google.com
• alt5-mtalk.google.com
• alt6-mtalk.google.com
• alt7-mtalk.google.com
• alt8-mtalk.google.com
• android.apis.google.com
• device-provisioning.googleapis.com
• firebaseinstallations.googleapis.com

網路位址轉譯和/或具狀態的封包檢查防火牆：

如果您的網路採用網路位址轉譯 (NAT) 或具狀態的封包檢查 (SPI)，請為透過 5228-5230 連接埠的連線，設定 30 分鐘或更長的逾時時間。這可讓我們提供可靠的連線服務，同時降低使用者行動裝置的電池消耗量。

VPN 互動和繞過方式

Firebase Cloud Messaging 會採取各種步驟，確保從手機到伺服器的推播訊息連線可靠且盡可能可用。使用 VPN 會使這項工作變得複雜。

VPN 會遮蓋 FCM 需要調整連線的基礎資訊，以便盡可能提高可靠性和電池續航力。在某些情況下，VPN 會主動中斷長時間連線，導致使用者體驗不佳，因為訊息可能會遺漏或延遲，電池費用也可能會偏高。當 VPN 設定允許我們這麼做時，我們會使用加密連線 (透過基礎網路 Wi-Fi 或 LTE) 略過 VPN，以確保可靠且不耗電的使用體驗。FCM 使用可繞過的 VPN 僅限於 FCM 推播通知管道。其他 FCM 流量 (例如註冊流量) 會在 VPN 處於啟用狀態時使用 VPN。當 FCM 連線略過 VPN 時，就會失去 VPN 可能提供的額外優勢，例如 IP 遮罩。

不同的 VPN 會使用不同的方法控制是否可略過 VPN。如需操作說明，請參閱特定 VPN 的說明文件。

如果未將 VPN 設為可繞過，Firebase Cloud Messaging 就會使用 VPN 網路連線至伺服器。這可能會導致訊息延遲，並且可能會導致電池使用量增加，因為 Cloud Messaging 會透過 VPN 連線維持連線。

憑證

視您要實作的 FCM 功能而定，您可能需要 Firebase 專案中的下列憑證：