Firebase 雲端通訊疑難排解與常見問題

通知編輯器和 FCM 有何不同？

Firebase Cloud Messaging 透過用戶端 SDK 和 HTTP 伺服器通訊協定，提供一整套訊息功能。如果部署作業有更複雜的訊息傳遞需求，FCM 是合適的選擇。

通知編寫器是以 Firebase Cloud Messaging 為基礎建構的輕量型無伺服器訊息解決方案。通知編輯器提供容易使用的圖形控制台，並減少程式設計需求，讓使用者能傳送訊息，重新吸引並留住使用者、促進應用程式業務拓展，以及支援行銷廣告活動。

是否需要使用其他 Firebase 服務，才能使用 FCM？

您可以將 Firebase Cloud Messaging 做為獨立元件使用，不需搭配其他 Firebase 服務。

為什麼目標裝置似乎無法接收訊息？

如果裝置似乎未成功接收訊息，請先檢查以下兩個可能原因：

通知訊息的前景訊息處理。當應用程式在裝置上處於前景時，用戶端應用程式需要新增訊息處理邏輯，才能處理通知訊息。詳情請參閱 iOS 和 Android 相關說明。

網路防火牆限制。如果貴組織的防火牆會限制網際網路的往來流量，您必須設定防火牆，允許與 FCM 連線，Firebase Cloud Messaging 用戶端應用程式才能接收訊息。要開啟的通訊埠如下：

• 5228
• 5229
• 5230

FCM 通常會使用 5228，但有時會使用 5229 和 5230。FCM 不提供特定 IP，因此您應允許防火牆接受連至 Google ASN 15169 中所列 IP 區塊內所有 IP 位址的傳出連線。

為什麼我的 Android 應用程式未呼叫 onMessageReceived？

應用程式在背景執行時，系統匣會顯示通知訊息，且不會呼叫 onMessageReceived。如果通知訊息含有資料酬載，通知訊息會顯示在系統匣中，而通知訊息中包含的資料，則可從使用者輕觸通知時啟動的意圖中擷取。

詳情請參閱「接收及處理訊息」。

為什麼我傳送訊息至從備份還原的有效應用程式執行個體時，會收到 404 錯誤？

FID (Firebase 安裝 ID) 是應用程式執行個體的 ID。根據預設，系統會備份及還原 Firebase 安裝資料。因此，在還原情況下，還原的應用程式執行個體和原始應用程式執行個體會共用相同的 FID。由於 FCM 每個 FID 只會儲存一個權杖，因此如果原始應用程式執行個體和還原的應用程式執行個體都在使用中，當其中一個應用程式執行個體向 FCM 註冊時，另一個應用程式執行個體的權杖就會遭到移除，導致 404 錯誤。

建議開發人員在應用程式中採取下列做法：

• 排除 備份中的 Firebase 安裝資料。Firebase 安裝資料會儲存在 PersistedInstallation....json 檔案中。檔案名稱是應用程式的常數。例如 <exclude domain="file" path="PersistedInstallation.W0R...GQ.json" />

Apple 宣布將淘汰 APNs 的舊版二進位通訊協定。我需要採取任何行動嗎？

否。Firebase Cloud Messaging 已於 2017 年改用 HTTP/2 型 APNs 通訊協定。如果您使用 FCM 將通知傳送至 iOS 裝置，則無須採取任何行動。

如何在 2 分鐘內通知大量客戶？

不支援這項用途。您必須將流量分散在 5 分鐘內。

我的應用程式會通知使用者事件，且這些訊息必須立即傳送，才能支援我的商業模式。可以提高配額嗎？

很抱歉，我們無法基於這個原因提高配額。您必須將流量分散在 5 分鐘內，避免流量激增。

我的訊息與排定的活動有關。如何將所有流量集中在整點傳送？

建議您至少在活動開始前 5 分鐘傳送通知。或者，您也可以傳送資料訊息，並實作平台類似 onMessageReceived 處理常式的機制，預先排定本機通知。

如何監控配額用量？

請參閱 Google Cloud 指南，瞭解如何繪製配額指標圖表並監控配額指標。

429 錯誤對我和我的業務來說很難處理。我可以申請豁免或提高配額，避免收到 429 錯誤嗎？

我們瞭解配額限制可能會造成不便，但配額是維持服務可靠性的重要機制，因此無法提供豁免。請重試，妥善處理 429 錯誤。

配額提高要求需要多久才能完成？

配額提高要求取決於您對 FCM 的使用情形。無論如何，您應該會在幾個工作天內收到回覆。在某些情況下，我們可能會就您使用 FCM 的情況和各種情況進行溝通，這可能會延長處理時間。如果符合所有規定，大部分要求會在 2 週內處理完畢。

可以為臨時活動申請更多配額嗎？

您可以申請額外配額，支援最長 1 個月的活動。請至少在活動開始前 1 個月提出要求，並清楚說明活動開始和結束時間，FCM 將盡一切努力滿足要求。如果獲准，這些配額增加將在活動結束日期後恢復。

目前的配額是否會變更？

雖然 Google 不會輕易變更配額，但可能會視需要調整，以維護系統完整性。Google 會盡可能提前通知您這類異動。請務必更新 Cloud MSA 聯絡人，提高收到服務公告的機率。

哪些 API 和功能已淘汰，即將停用？如果我正在使用這些 API，該怎麼辦？

所有 InstanceId 伺服器 API 和裝置群組功能皆已淘汰，並將於 2027 年 9 月 29 日停用。下表詳細說明已淘汰的 API/功能，以及需要採取的行動。

如果我使用 Firebase Admin SDK 管理主題訂閱項目，會受到淘汰影響嗎？What should I do?

如果您使用舊版 Firebase Admin SDK 管理主題訂閱項目，就會受到淘汰影響。 請將 Firebase Admin SDK 升級至下列版本：

2027 年 9 月 29 日前，服務會降級嗎？

不會。您有 12 個月的時間，可以從已淘汰的 API 遷移至替代方案，服務不會降級。強烈建議您盡早規劃遷移作業，以免受到停用影響。

2027 年 9 月 29 日後，呼叫已淘汰的 API 時，預期會收到錯誤訊息。

新使用者可以在淘汰前，使用已淘汰的 API/功能嗎？

新使用者可在 2027 年 1 月 1 日前，開始使用已淘汰的 API/功能。2027 年 1 月 1 日後，新使用者將無法使用已淘汰的 API。使用者可以繼續使用已淘汰的 API，直到 2027 年 9 月 29 日為止。

舊版 AndroidConfig (v1) API 的支援期限為何？

FCM 計劃在 AndroidConfigV2 正式發布 (GA) 後，繼續支援 v1 AndroidConfig 酬載多年。雖然遷移時間表長達數年，但 AndroidConfigV2 提供更可預測的通知傳送功能，建議您盡快遷移。

AndroidConfigV2 支援哪些 Android 作業系統版本？

Google 支援的所有 Android 版本都將支援 AndroidConfigV2。舊版第 1 版 API 停用後，除了 10 年以上的裝置外，其他裝置都將支援。

AndroidConfigV2 是否會將酬載傳送至僅支援舊版 v1 介面的裝置？我應該按照什麼順序推出變更？

可以，傳送 AndroidConfigV2 要求時，FCM 和 GMS Core 會自動為搭載舊版用戶端 SDK 的裝置，或尚未覆寫 onNotificationReceived() 或 onBackgroundSyncReceived() 的應用程式轉譯酬載，並使用 onMessageReceived() 傳送。

為什麼 AndroidConfigV2 要求透過 FCM SDK 傳回通知，而不是直接呼叫 NotificationManager.notify()？

將 NotificationResponse 傳回開放原始碼 FCM SDK，或使用 FcmNotificationManager：

• 應用程式會收到受保護的執行視窗，用於解密或自訂通知。
• 如果應用程式逾時，GMS Core 會發布您在 remote_notification.notification 中設定的備份通知，確保及時傳送。

應用程式在前景或背景運作時，AndroidConfigV2 處理通知的方式是否不同？

不會。與舊版 v1 通知訊息不同，AndroidConfigV2 不會根據應用程式是在前景或背景，分割訊息轉送。傳送 RemoteNotification 時，除非您設定 mutable_content: true，並使用 NotificationResponse.createEmpty() 在 onNotificationReceived() 中明確設為靜音，否則通知會自動顯示在兩種狀態中。

應用程式處理可變動的 RemoteNotification 時，有多少時間？

在 RemoteNotification 上設定 mutable_content: true 時，應用程式在 onNotificationReceived() 內最多有 20 秒的時間解密酬載、擷取小型素材資源 (例如顯示圖片)，或在傳回 NotificationResponse 之前與應用程式伺服器聯絡。如果回呼超過 20 秒，系統會取消執行，GMS Core 則會根據 remote_notification.notification 酬載自動發布備用通知。

如何對可變動的 RemoteNotification 執行通知抑制？

應用程式可以從 onNotificationReceived() 傳回 NotificationResponse.suppress()，藉此抑制 RemoteNotification。例如，當即時通訊設為靜音、封鎖傳送者，或端對端加密酬載驗證失敗時。

• 在背景：應用程式在滾動週期內，最多可抑制 25% 收到的 RemoteNotification 訊息。如果應用程式的背景抑制率超過 25%，GMS Core 會自動轉譯並發布 remote_notification.notification 酬載中的備用通知。
• 前景：在前景執行時，您可以自由隱藏所有遠端通知。例如，顯示應用程式內浮動式訊息或更新開啟的即時通訊畫面，而不是發布系統通知。

我的應用程式可以透過單一 RemoteNotification 發布多則通知，或取消現有通知嗎？

可以，使用下列指令取消或發布多則通知：

• 取消單一通知：從 onNotificationReceived() 傳回 NotificationResponse.createCancel(tag, id)，關閉先前發布的通知。
• 發布多則通知，或合併取消和發布作業：在 onNotificationReceived() 內呼叫 getFcmNotificationManager(message)，多次叫用 postNow(tag, id, notification) 和 cancelNow(tag, id)，並在完成後傳回 manager.finished()。

自訂 RemoteViews 是否能與 AndroidConfigV2 搭配使用？

可以，自訂 RemoteViews 可與 AndroidConfigV2 搭配使用。onNotificationReceived() 會傳回標準 Android Notification 物件，所有標準 Android 通知 API (例如 setCustomContentView()) 仍受支援。請注意，RemoteViews 和 View 處於維護模式，建議您遷移至 Compose。