Firebase 雲端通訊 HTTP 通訊協定

這個參數可指定訊息的收件者。

這個值可以是裝置的註冊權杖、裝置群組的通知鍵或單一主題 (前置字串為 /topics/)。如要傳送至多個主題，請使用 condition 參數。

這個參數會指定多播訊息的收件者，也就是傳送至多個註冊符記的訊息。

這個值應為要傳送多播訊息的註冊符記陣列。陣列必須包含至少 1 個，最多 1000 個註冊權杖。如要傳送訊息給單一裝置，請使用 to 參數。

多播訊息只能使用 HTTP JSON 格式。

這個參數會指定邏輯運算式，其中包含用來決定訊息目標的條件。

支援的條件：主題，格式為「在主題中使用'yourTopic'」。這個值不區分大小寫。

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

這個參數已淘汰。請改用 to 指定訊息收件者。如要進一步瞭解如何傳送訊息給多部裝置，請參閱平台的說明文件。

這個參數可用於識別可摺疊的一組訊息 (例如使用 collapse_key: "Updates Available")，這樣一來，系統就能在可恢復傳送時只傳送最後一則訊息。這項功能是為了避免在裝置恢復連線或恢復使用時傳送過多相同訊息。

請注意，我們無法保證訊息的傳送順序。

注意：系統在任何時間點最多允許 4 個不同的收合鍵。這表示 FCM 可為每個用戶端應用程式同時儲存 4 個不同的訊息。如果超過這個數量，FCM 將保留哪些 4 個折疊鍵，我們無法保證。

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

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

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

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

在 Apple 平台上，請使用這個欄位代表 APN 酬載中的 mutable-content。當通知傳送且已設為 true 時，您可以使用 通知服務應用程式擴充功能，在通知顯示前修改通知內容。系統會忽略 Android 和網頁的此參數。

如果裝置處於離線狀態，此參數會指定訊息應保留在 FCM 儲存空間中的時間長度 (以秒為單位)。支援的存留時間上限為 4 週，預設值為 4 週。詳情請參閱「設定訊息的效期」。

這個參數若設為 true，開發人員就能測試要求，而無須實際傳送訊息。

預設值為 false。

此參數會指定訊息酬載的自訂鍵/值組合。

例如：data:{"score":"3x1"}:

在 Apple 平台上，如果訊息是透過 APN 傳送，則代表自訂資料欄位。如果是透過 FCM 傳送，則會在 AppDelegate application:didReceiveRemoteNotification: 中以鍵值字典的形式表示。

在 Android 上，這會產生名為 score 的意圖額外意圖，且字串值為 3x1。

鍵不得是保留字詞 (「from」、「message_type」或任何以「google」或「gcm」開頭的字詞)。請勿使用本表所定義的任何字詞 (例如 collapse_key)。

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

通知的標題。

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

通知的內文。

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

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

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

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

如果設為 0，系統會移除徽章。

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

對應至 APN 酬載中的 category。

通知的副標題。

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

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

詳情請參閱「 酬載金鑰參考資料」和「 本地化遠端通知內容」。

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

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

詳情請參閱「 酬載金鑰參考資料」和「 本地化遠端通知內容」。

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

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

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

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

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

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

通知的標題。

通知的內文。

通知的管道 ID (Android O 的新功能)。

應用程式必須先建立含有這個管道 ID 的管道，才能收到含有這個管道 ID 的任何通知。

如果您未在要求中傳送這個管道 ID，或是應用程式尚未建立所提供的管道 ID，FCM 會使用應用程式資訊清單中指定的管道 ID。

通知的圖示。

將可繪製資源 myicon 的通知圖示設為 myicon。如果您未在要求中傳送這個鍵，FCM 會顯示應用程式資訊清單中指定的啟動器圖示。

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

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

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

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

如果已指定，且系統正在顯示同一個標記的通知，新通知會取代通知列中的現有通知。

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

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

如果指定，使用者點選通知時，系統就會啟動具有相符意圖篩選器的活動。

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

詳情請參閱「字串資源」。

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

詳情請參閱「格式化和樣式」。

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

詳情請參閱「 字串資源」。

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

詳情請參閱「 格式設定和樣式」一文。

通知的標題。

通知的內文。

用於通知圖示的網址。

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

所有網址值都必須使用 HTTPS。

這個參數會指定接收訊息的用戶端應用程式 (註冊權杖)。

多點傳播訊息 (傳送至多個註冊符記) 僅限使用 HTTP JSON 格式。

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

舉例來說，在 Android 中，"data.score"."3x1" 會產生名為 score 的意圖額外項目，其字串值為 3x1。

鍵不得是保留字詞 (「from」、「message_type」或任何以「google」或「gcm」開頭的字詞)。請勿使用此表中定義的任何字詞 (例如 collapse_key)。

• message_id：字串，指定每則成功處理的訊息專屬 ID。
• error：字串，指出處理收件者的訊息時發生的錯誤。如要查看可能的值，請參閱表格 9。

• 如果用戶端應用程式已取消註冊 FCM。
• 如果用戶端應用程式會自動取消註冊，這可能會發生在使用者解除安裝應用程式時。舉例來說，如果在 iOS 上，APNs 回饋服務回報 APNs 權杖無效。
• 如果註冊權杖到期 (例如 Google 可能決定重新整理註冊權杖，或是 iOS 裝置的 APN 權杖到期)。
• 如果用戶端應用程式已更新，但新版本未設定為接收訊息。

• HTTP 要求中缺少授權標頭或含有無效的語法。
• 指定的伺服器金鑰所屬的 Firebase 專案有誤。
• 僅限舊版伺服器金鑰：要求來自未列入伺服器金鑰 IP 白名單的伺服器。

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

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

造成問題的寄件者可能會遭到封鎖。

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

請減少傳送至這部裝置的訊息數量，並使用指數輪詢重試。