關於 FCM 訊息

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

訊息類型

透過 FCM，您可以傳送兩種類型的訊息給客戶：

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

通知訊息包含一組預先定義的使用者可見鍵。 相較之下，資料訊息只包含您定義的自訂鍵值組。通知訊息可以包含選用的資料酬載。兩種訊息類型的酬載上限皆為 4, 096 個位元組，但透過 Firebase 控制台傳送訊息時，酬載上限為 1, 000 個字元。

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

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

通知訊息

如要進行測試，或是用於行銷及重新吸引使用者，您可以使用 Firebase 控制台傳送通知訊息。Firebase 控制台提供以數據分析為基礎的 A/B 測試，協助您修正及改善行銷訊息。

如要使用 Admin SDK 或 FCM 通訊協定以程式輔助方式傳送通知訊息，請設定 notification 鍵，並為通知訊息中向使用者顯示的部分，提供必要的一組預先定義鍵/值選項。舉例來說，以下是即時通訊應用程式中 JSON 格式的通知訊息。使用者應會在裝置上看到標題為「葡萄牙對丹麥」的訊息，以及「精彩賽事！」的文字：

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

應用程式在背景運作時，通知訊息會傳送到通知匣。如果是前景應用程式，訊息會由回呼函式處理。

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

資料訊息

您可以自行決定如何使用 FCM 酬載 data 實作所選的加密配置。請確認自訂鍵/值組合中沒有任何保留字。保留字詞包括「from」、「notification」、「message_type」，或任何以「google」或「gcm」開頭的字詞。

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

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

上例顯示頂層或通用 data 欄位的使用情形，所有接收訊息的平台上的用戶端都會解讀這個欄位。在各個平台上，用戶端應用程式都會在回呼函式中接收資料酬載。

通知訊息 (可選用資料酬載)

無論是透過程式輔助或 Firebase 控制台，您都可以傳送通知訊息，其中包含自訂鍵/值組合的選用酬載。在 通知撰寫工具中，使用「進階選項」的「自訂資料」欄位。

應用程式收到同時包含通知和資料酬載的訊息時，會根據應用程式處於背景或前景狀態 (也就是收到訊息時是否處於活動狀態)，採取不同的行為。

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

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

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

在不同平台上自訂訊息

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

• 一組通用欄位，供接收訊息的所有應用程式例項解讀。
• 平台專屬的欄位集，例如 AndroidConfig 和 WebpushConfig， 只有在指定平台上執行的應用程式例項會解讀這些欄位。

平台專屬區塊可讓您彈性自訂不同平台的訊息，確保訊息在收到時能正確處理。FCM 後端會考量所有指定的參數，並為每個平台自訂訊息。

使用通用欄位的時機

在下列情況下使用通用欄位：

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

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

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

使用平台專屬欄位的時機

如要執行下列操作，請使用平台專屬欄位：

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

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

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

示例：含有平台專屬傳送選項的通知訊息

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

• 為 Android 和 Web 平台設定較長的存留時間，同時將 APNs (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 同步，或在背景同步處理應用程式資料，請選擇一般傳送優先順序。

• 高優先順序：即使裝置處於「打盹」模式，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"
      }
    }
  }
}

如要進一步瞭解如何設定訊息優先順序，請參閱下列平台專屬詳細資料：

• APNs 說明文件
• 設定及管理訊息優先順序 (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，且螢幕開啟，沒有任何節流限制，訊息就會立即送達。

如果裝置已連線但處於打盹模式，FCM 會儲存低優先順序訊息，直到裝置離開打盹模式為止。這時 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. 選取「QUOTA & SYSTEM LIMITS」(配額與系統限制)。

注意：這些圖表的時間軸與配額分鐘數並不完全一致，因此即使流量似乎低於配額，系統仍可能提供 429 狀態碼。

申請提高配額

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

• 每天至少有 5 分鐘的配額用量 ≥ 80%。
• 用戶端錯誤率低於 5%，尤其是在流量高峰期間。
• 您遵循大量傳送訊息的最佳做法。

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

如果即將推出產品或舉辦臨時活動，需要更多下游訊息配額，請至少提前 15 天申請配額，確保有足夠時間處理要求。如果要求量很大 (每分鐘超過 1,800 萬則訊息)，請至少提前 30 天通知我們。發布和特別活動要求仍須符合用戶端錯誤率和最佳做法規定。

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

主題訊息限制

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

如要瞭解訊息傳送速率，請參閱「扇出節流」。

擴散傳遞節流

訊息散播是指將訊息傳送至多部裝置的程序，例如指定主題和群組，或是使用通知撰寫器指定目標對象或使用者區隔時。

訊息散播並非即時，因此有時會同時進行多個散播作業。每項專案的並行訊息扇出數量上限為 1,000 個。之後，我們可能會拒絕其他扇出要求，或延後扇出要求，直到部分進行中的扇出完成為止。

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

可收合訊息節流

如上所述，可收合訊息是沒有內容的通知，設計目的是要彼此重疊收合。如果開發人員太常將相同訊息傳送至應用程式，我們會延遲 (節流) 訊息，以減少對使用者電池續航力的影響。

舉例來說，如果您傳送大量新的電子郵件同步要求至單一裝置，我們可能會延遲幾分鐘再處理下一個電子郵件同步要求，讓裝置以較低的平均速率同步處理。這項節流措施嚴格來說是為了限制使用者感受到的電池影響。

如果您的用途需要高爆量傳送模式，則不可收合的訊息可能是不錯的選擇。對於這類訊息，請務必在訊息中加入內容，以降低電池耗電量。

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

單一裝置的訊息速率上限

在 Android 裝置上，你每分鐘最多可傳送 240 則訊息，每小時最多可傳送 5,000 則訊息給單一裝置。這個高門檻是為了允許短期流量爆增，例如使用者在即時通訊中快速互動時。這項限制可避免傳送邏輯發生錯誤，導致裝置電量意外耗盡。

如果速率超過 APNs 限制，iOS 會傳回錯誤。

憑證

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