Firebase 雲端通訊 XMPP 通訊協定

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

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

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

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

下游訊息語法

本節說明傳送下游訊息的語法。

下游 XMPP 訊息 (JSON)

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

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

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

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

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

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

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

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

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

這個參數可識別可收合的一組訊息 (例如使用 collapse_key: "Updates Available")，這樣系統繼續傳送時，就只會傳送最後一則訊息。這個機制是為了避免在裝置恢復連線或停止運作時，傳送過多相同訊息。

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

注意：一次最多只能使用 4 個不同的收合鍵。這表示每個用戶端應用程式可同時儲存 4 則不同的訊息。如果超過這個數字，FCM 不一定會保留 4 個收合金鑰。
priority 選填，字串

設定郵件的優先順序。有效值為「normal」和「高」。在 Apple 平台上，這些要求會對應至 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 選填，物件 這個參數會指定使用者可見的預先定義通知酬載鍵/值組合，詳情請參閱「通知酬載支援」。如要進一步瞭解通知訊息和資料訊息選項，請參閱「 訊息類型」。如果提供通知酬載，或針對傳送至 Apple 裝置的訊息，將 content_available 選項設為 true，則訊息會透過 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 必要，字串

這個參數會指定從 FCM 傳送至應用程式伺服器的 ack 或 nack 訊息。

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

下游訊息錯誤回應代碼

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

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

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

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

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

注意：系統會將可能造成問題風險的寄件者列入黑名單。
內部伺服器錯誤 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 選填，字串 這個參數會指定訊息酬載的鍵/值組合。

傳送確認訊息

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

表 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 時，訊息會包含 control_type 表示控制訊息的類型。
control_type 選填，字串

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

目前僅支援 CONNECTION_DRAINING。FCM 會在連線關閉以執行負載平衡前，先傳送這個控制訊息。當連線排除時，系統就不會再將訊息傳送至連線，但會繼續處理管道中的現有訊息。