Firebase 雲端通訊 HTTP 通訊協定

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

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

這個參數會指定多點傳送訊息的接收者 (傳送至多個註冊權杖的訊息)。

這個值應為傳送多點傳送訊息的註冊權杖陣列。陣列必須包含 1 至 1,000 個註冊權杖。如要向單一裝置傳送訊息，請使用 to 參數。

多點傳送訊息只能使用 HTTP JSON 格式。

這個參數指定的邏輯運算式會決定訊息目標。

支援的條件：主題，格式為「<主題>」。這個值不區分大小寫。

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

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

此參數可識別可收合的一組訊息 (例如包含 collapse_key: "Updates Available")，如此一來，系統只會在可以繼續傳送時，傳送最後一則訊息。這是為了避免在裝置恢復連線或處於啟用狀態時傳送過多相同訊息。

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

注意：在任何指定時間內，最多可有 4 個不同的收合鍵。這表示 FCM 可以為每個用戶端應用程式同時儲存 4 則不同的訊息。如果超過這個數量，則無法保證 FCM 會保留哪 4 個收合金鑰。

設定訊息的優先順序。有效值為「正常」和「高」。在 Apple 平台上，這些 ID 相當於 5 和 10 的 APN 優先順序。

根據預設，通知訊息會以高優先順序傳送，資料訊息則會以一般優先順序傳送。一般優先順序會最佳化用戶端應用程式的電池消耗量，因此除非需要立即提交，否則應使用此功能。對於優先順序較高的訊息，應用程式可能會收到未指定延遲時間的訊息。

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

在 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 上，如果 APN 意見回饋服務將 APN 權杖回報為無效，
• 如果註冊權杖過期 (例如，Google 可能會決定更新註冊權杖，或者 iOS 裝置的 APN 權杖已失效)。
• 如果用戶端應用程式已更新，但新版本尚未設定可接收訊息，

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

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

• 如果 Retry-After 標頭包含在 FCM 連線伺服器的回應中，請使用標頭。
• 在重試機制中實作指數輪詢策略。(比方說，假設您在第一次重試之前等待一秒，請至少先等待兩秒再按一次，接著再等待 4 秒，依此類推)。如果您要傳送多則訊息，請以額外的隨機數量逐一延遲每個訊息，以免同時對所有訊息發出新要求。

導致問題風險的寄件者被列入黑名單。

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

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