Firebase 雲端通訊 XMPP 通訊協定

本文件提供 XMPP 語法的參考資料，可用於在應用程式伺服器、用戶端應用程式和 Firebase Cloud Messaging (FCM) 之間傳遞訊息。應用程式伺服器必須連線至下列端點：

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

可用的參數和 共分為以下類別：

下游訊息語法

本節提供傳送下游訊息的語法。

下游 XMPP 訊息 (JSON)

下表列出 XMPP JSON 訊息的目標、選項和酬載。

表 1 下游 XMPP 訊息 (JSON) 的目標、選項和酬載。

參數 用量 說明
目標
to 選填，字串

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

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

condition 選用，字串

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

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

支援的運算子：&&、||。最多兩個 每個主題訊息支援的運算子。
選項
message_id 必要，字串

這個參數可明確識別 XMPP 連線中的訊息。
collapse_key 選用，字串

這個參數可識別訊息群組 (例如 collapse_key: "Updates Available") 可收合的文字，這樣就只會 最後一則訊息傳送成功這可避免裝置重新上線或結束休眠狀態時，傳送太多相同的訊息。

我們無法保證訊息的傳送順序。

注意：系統在任何時間點最多允許 4 個不同的收合鍵。也就是說 FCM 可同時儲存 4 種不同的資料 每個用戶端應用程式的訊息數量。如果發生以下情況： 超過這個數字，不保證可收合的鍵 FCM 能夠保存。
priority 選用，字串

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

預設情況下，通知訊息的優先程度較高，而資料訊息則是以高優先順序傳送 以一般優先順序傳送一般優先順序可為用戶端應用程式的 但除非需要立即交付，否則應使用電量。 對於優先順序為「一般」的訊息，應用程式可能會在未指定的延遲時間後收到訊息。

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

在 Apple 平台上，請使用這個欄位代表 APN 中的 content-available 酬載。收到通知或訊息並設為 true 時， 系統會喚醒閒置的用戶端應用程式，而 APN 會以靜音模式傳送訊息 而非透過 FCM 發出通知請注意，靜音通知 視使用者等因素而定，我們無法保證 APN 一定會送達 開啟低耗電模式、強制退出應用程式等。在 Android 裝置上，資料訊息會喚醒 應用程式。目前不支援在 Chrome 上使用。
mutable_content 選用，JSON 布林值

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

time_to_live 選用，數字

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

如果將這項參數設為 true，開發人員就能測試 不必實際傳送訊息即可執行要求

預設值為 false。
酬載
data 選用，物件

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

例如，使用 data:{"score":"3x1"}:

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

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

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

建議使用字串類型的值。您需要轉換物件或其他非字串資料類型中的值 (例如整數或布林值) 至字串。
notification 選用，物件 這個參數會指定使用者能夠查看的 通知酬載詳情請參閱通知酬載支援。如要進一步瞭解通知訊息和資料訊息選項，請參閱「訊息類型」。如果提供通知酬載，或是將 content_available 選項設為 true，以便傳送訊息至 Apple 裝置，則系統會透過 APN 傳送訊息；否則，則會透過 FCM 傳送。

通知酬載支援

下表列出 鍵，用於建構 Apple 平台和 Android 的通知訊息。

表 2a.Apple - 通知訊息的鍵

參數 用量 說明
title 選用，字串

通知的標題。

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

body 選用，字串

通知的內文。

sound 選填，字串

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

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

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

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

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

click_action 選用，字串

與使用者點選通知相關聯的動作。

對應至 APN 酬載中的 category。
subtitle 選填，字串

通知的副標題。
body_loc_key 選用，字串

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

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

詳情請參閱「酬載鍵參考資料」和「將遠端通知內容本地化」。
body_loc_args 選用，JSON 陣列做為字串

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

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

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

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

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

詳情請參閱「酬載鍵參考資料」和「將遠端通知內容本地化」。
title_loc_args 選用，JSON 陣列做為字串

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

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

詳情請見 酬載金鑰參考資料和 將遠端通知內容本地化 可能不準確或不適當

表 2b. Android：通知訊息的鍵

參數 用量 說明
title 選用，字串

通知的標題。

body 選填，字串

通知的內文。

android_channel_id 選填，字串

通知的頻道 ID (在 Android O 中提供)。

應用程式必須使用此頻道 ID 建立頻道，才能傳送任何含有此頻道 ID 的通知 。

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

通知圖示。

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

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

支援 "default" 或音效資源的檔案名稱 某個應用程式套裝組合中音效檔案必須位於 /res/raw/。

tag 選用，字串

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

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

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

通知的圖示顏色，以 #rrggbb 格式表示。
click_action 選用，字串

與使用者點擊通知相關的動作。

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

應用程式字串資源中要用於主體字串的鍵 將內文本地化到使用者目前的本地化。

詳情請參閱「字串資源」。
body_loc_args 選用，JSON 陣列做為字串

用來取代格式指定碼的變數字串值 body_loc_key，用於將內文本地化 使用者的目前本地化內容

詳情請參閱「格式化和樣式」。
title_loc_key 選填，字串

應用程式字串資源中標題字串的鍵，用來 根據使用者目前的本地化翻譯標題文字。

詳情請參閱「字串資源」。
title_loc_args 選用：JSON 陣列做為字串

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

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

表 2c.網頁 (JavaScript)：通知訊息的鍵

參數 用量 說明
title 選用，字串

通知的標題。

body 選填，字串

通知的內文。

icon 選填，字串

用於通知圖示的網址。
click_action 選填，字串

與使用者點選通知相關聯的動作。

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

解讀下游 XMPP 訊息回應

下表列出下游 XMPP 訊息回應中顯示的欄位。

表 3 下游訊息 XMPP 回應內文。

參數 用量 說明
from 必要，字串

這個參數可指定此回應的傳送者。

值為用戶端應用程式的註冊權杖。
message_id 必要，字串 這個參數可明確識別 XMPP 連線中的訊息。 這個值是用來唯一識別相關訊息的字串。
message_type 必要，字串

此參數指定來自 ack 或 nack 訊息 FCM 至應用程式伺服器。

如果值設為 nack，應用程式伺服器應查看 error 和 error_description 來取得失敗資訊。
error 選填，字串 這個參數會指定與下游訊息相關的錯誤。系統會在 message_type為 nack。詳情請參閱表 4。
error_description 選填，字串 此參數可提供錯誤的描述性資訊。當 message_type 為 nack 時，系統會設定此值。

下游訊息錯誤回應代碼

下表列出下游訊息的錯誤回應代碼。

表 4 下游訊息錯誤回應代碼。

錯誤 XMPP 程式碼 建議做法
缺少註冊權杖 INVALID_JSON 檢查請求中，是否已包含註冊權杖 (位於 純文字訊息中的 registration_id，或出現在 to 中 或 JSON 中的 registration_ids 欄位)。
APN 註冊無效 INVALID_JSON 針對 iOS 註冊，請檢查用戶端的註冊要求是否包含有效的 APNs 權杖和應用程式 ID。
無效的註冊權杖 BAD_REGISTRATION 請檢查您傳遞至伺服器的註冊權杖格式。確定 與用戶端應用程式透過 FCM 註冊時收到的註冊權杖相符。請勿截斷或新增其他字元。
未註冊的裝置 DEVICE_UNREGISTERED 在許多情況下，現有的註冊權杖可能會失效，包括：
  • 如果用戶端應用程式已取消註冊 FCM。
  • 如果用戶端應用程式會自動取消註冊，這可能會發生在使用者解除安裝應用程式時。舉例來說，如果在 iOS 上，APNs 回報 APNs 權杖無效。
  • 如果註冊權杖過期 (例如，Google 可能會決定更新 或裝置的 APN 權杖已過期)。
  • 如果用戶端應用程式已更新，但新版本未設定為接收訊息。
如發生上述情況，請從應用程式中移除這個註冊權杖 並停止使用該伺服器傳送訊息
寄件者不符 SENDER_ID_MISMATCH 註冊權杖會與特定一組寄件者相關聯。當用戶端應用程式註冊時 FCM 時，必須指定哪些寄件者可以傳送郵件。傳送訊息至用戶端應用程式時，請使用其中一個傳送者 ID。如果切換至其他傳送者，現有的註冊權杖將無法運作。
JSON 無效 INVALID_JSON 檢查 JSON 訊息的格式是否正確，並包含有效的欄位 (例如，確保傳入正確的資料類型)。
訊息過大 INVALID_JSON 請確認郵件中附帶的酬載資料總大小不超過 FCM 限制：大多數郵件為 4096 個位元組，郵件主題為 2048 個位元組。這包括 這些鍵和值
資料金鑰無效 INVALID_JSON 請確認酬載資料不含 FCM 在內部使用的鍵 (例如 from、gcm 或任何前面有 google 的值)。請注意部分字詞，例如 collapse_key 也會用於酬載，但在這種情況下，FCM 酬載值已由 FCM 值覆寫。
無效存留時間 INVALID_JSON 確認 time_to_live 中使用的值是代表 時間長度，以秒為單位，介於 0 到 2,419,200 (4 週) 之間。
確認訊息無效 BAD_ACK 請先檢查 ack 訊息的格式是否正確，再重試。詳情請見 表 6。
逾時 SERVICE_UNAVAILABLE

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

  • 在重試機制中實作指數輪詢。(例如，如果您在第一次重試前等待一秒，請在下一次重試前至少等待兩秒，然後再等待四秒，以此類推)。如果您傳送多則訊息，請為每則訊息額外延遲隨機時間，避免同時針對所有訊息發出新要求。
  • 初始重試延遲時間應設為一秒。

注意：系統會將可能造成問題風險的寄件者列入黑名單。
內部伺服器錯誤 INTERNAL_SERVER_
ERROR		 伺服器在處理要求時發生錯誤，你可以再試一次 要求使用「逾時」(請見上列)。
裝置訊息傳送頻率超出上限 DEVICE_MESSAGE_RATE
_EXCEEDED		 傳送到特定裝置的訊息頻率過高。減少 傳送到這部裝置的訊息數量，並且不會立即重試傳送到這部裝置。
超出主題訊息率 TOPICS_MESSAGE_RATE
_EXCEEDED		 特定主題的訊息訂閱者比率過高。減少 為這個主題傳送的訊息數量，而且不會立即重試。
連線排除 CONNECTION_DRAINING 正在排除連線，因此無法處理訊息。這是因為 FCM 需要定期關閉連線，才能執行負載平衡。請重新傳送訊息 另一個 XMPP 連線。
APN 憑證無效 INVALID_APNS_CREDENTIAL 無法傳送指定 iOS 裝置的訊息，因為必要的 APN 未上傳驗證金鑰或驗證金鑰已過期。檢查開發和實際運作環境的憑證是否有效。
驗證失敗 AUTHENTICATION_FAILED 無法透過外部推播服務進行驗證。請檢查您是否使用正確的網頁推播憑證。

上游訊息語法

上游訊息是指用戶端應用程式傳送至應用程式伺服器的訊息。目前只有 XMPP 支援上游訊息傳送功能。詳情請見 查看您的平台的說明文件 瞭解如何從用戶端應用程式傳送訊息。

解讀上游 XMPP 訊息

下表說明 FCM 在回應用戶端應用程式上游訊息要求時，所產生 XMPP 節中的欄位。

表 5 上游 XMPP 訊息。

參數 用量 說明
from 必要，字串

這個參數可指定訊息的傳送者。

值為用戶端應用程式的註冊權杖。
category 必要，字串 這個參數會指定傳送訊息的用戶端應用程式應用程式套件名稱。
message_id 必要，字串 這個參數可指定訊息的專屬 ID。
data 選用，字串 此參數會指定訊息酬載的鍵/值組合。

傳送確認訊息

下表說明應用程式伺服器應傳送至 ACK 回應 FCM 可回應 應用程式伺服器收到的上游訊息。

表 6 上游 XMPP 訊息回應。

參數 用量 說明
to 必要，字串

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

這個值必須是傳送上游訊息的用戶端應用程式註冊權杖。
message_id 必要，字串 這個參數會指定回應適用的訊息。值必須是 對應上游訊息的 message_id 值。
message_type 必要，字串 這個參數會指定從應用程式伺服器傳送至 CCS 的 ack 訊息。對於上游訊息，應一律設為 ack。

FCM 伺服器訊息 (XMPP)

這是從 FCM 傳送至應用程式伺服器的訊息。以下是 FCM 傳送至應用程式伺服器的主要訊息類型：

  • 控制：這些由 CCS 產生的訊息表示應用程式伺服器需要採取行動。

下表說明訊息 CCS 中的欄位 應用程式伺服器

表 7 FCM 控管訊息 (XMPP)。

參數 用量 說明
常用欄位
message_type 必要，字串

這個參數會指定訊息類型：控制項。

設定為 control 時，訊息會包含 control_type，用於指出控制訊息類型。
control_type 選用，字串

這個參數會指定從 FCM 傳送的控制訊息類型。

目前僅支援 CONNECTION_DRAINING。FCM 會在關閉負載平衡連線之前傳送此控制訊息。連線排除時，不會再傳送任何訊息 可以傳送至連線，但管道中的現有訊息 。