Firebase 雲端訊息傳遞 XMPP 協議

本文檔提供了在應用程式伺服器、用戶端應用程式和 Firebase Cloud Messaging (FCM) 之間傳遞訊息的 XMPP 語法的參考。您的應用程式伺服器必須連接到這些端點:

// 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 將保留哪 4 個折疊鍵。

priority可選,字串

設定訊息的優先順序。有效值為“正常”和“高”。在 Apple 平台上,這些對應於 APN 優先權 5 和 10。

預設情況下,通知訊息以高優先順序發送,資料訊息以普通優先權發送。正常優先順序可最佳化用戶端應用程式的電池消耗,除非需要立即交付,否則應使用正常優先順序。對於具有正常優先權的訊息,應用程式可能會以未指定的延遲接收訊息。

當發送高優先級訊息時,會立即發送,並且應用程式可以顯示通知。

content_available可選,布林值

在 Apple 平台上,使用此欄位表示 APNs 負載中content-available 。當發送通知或訊息並將其設為true時,將喚醒不活動的客戶端應用程序,並且訊息將透過 APN 作為靜默通知發送,而不是透過 FCM 發送。請注意,APN 中的靜默通知不能保證一定會發送,並且可能取決於用戶打開低功耗模式、強制退出應用程式等因素。在 Android 上,預設情況下,資料訊息會喚醒應用程式。在 Chrome 上,目前不支援。

mutable_content可選,JSON 布林值

在 Apple 平台上,使用此欄位來表示 APNs 負載中的mutable-content 。當發送通知並將其設為true時,可以使用通知服務應用程式擴充功能在顯示通知之前修改通知的內容。對於 Android 和 Web,此參數將被忽略。

time_to_live可選,數量

此參數指定如果設備離線,訊息應在 FCM 儲存中保留多長時間(以秒為單位)。支援的最長生存時間為 4 週,預設值為 4 週。有關詳細信息,請參閱設定訊息的生命週期

dry_run可選,布林值

當此參數設為true時,開發人員可以在不實際發送訊息的情況下測試請求。

預設值為false

有效載荷
data可選,對象

此參數指定訊息負載的鍵值對。

例如,對於data:{"score":"3x1"}:

在 Apple 平台上,如果訊息是透過 APN 傳遞的,則它代表自訂資料欄位。如果由 FCM 傳遞,則在AppDelegate application:didReceiveRemoteNotification:中表示為鍵值字典。

在 Android 上,這會產生一個名為score的意圖額外值,其字串值為3x1

鍵不應是保留字(“from”、“message_type”或任何以“google”或“gcm”開頭的單字)。不要使用此表中定義的任何單字(例如collapse_key )。

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

notification可選,對象此參數指定通知負載的預先定義、使用者可見的鍵值對。有關詳細信息,請參閱通知負載支援。有關通知訊息和資料訊息選項的更多信息,請參閱訊息類型。如果提供了通知有效負載,或將傳送至 Apple 裝置的訊息的content_available選項設為true ,則訊息將透過 APNs 傳送,否則將透過 FCM 傳送。

通知負載支持

下表列出了可用於為 Apple 平台和 Android 建立通知訊息的預先定義鍵。

表 2a. Apple — 通知訊息鍵

範圍用法描述
title可選,字串

通知的標題。

該欄位在手機和平板電腦上不可見。

body可選,字串

通知的正文。

sound可選,字串

設備收到通知時播放的聲音。

指定客戶端應用程式主包中或應用程式資料容器的Library/Sounds資料夾中的聲音檔案的字串。有關詳細信息,請參閱iOS 開發人員庫

badge可選,字串

主螢幕應用程式圖示上的徽章的值。

如果未指定,則不會變更徽章。

如果設定為0 ,則徽章將被刪除。

click_action可選,字串

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

對應於 APNs 負載中的category

subtitle可選,字串

通知的副標題。

body_loc_key可選,字串

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

對應於 APNs 負載中的loc-key

有關更多信息,請參閱有效負載密鑰參考本地化遠端通知的內容

body_loc_args可選,JSON 數組作為字串

用於取代body_loc_key中的格式說明符的變數字串值,用於將正文文字本地化為使用者目前的本地化。

對應於 APNs 負載中的loc-args

有關更多信息,請參閱有效負載密鑰參考本地化遠端通知的內容

title_loc_key可選,字串

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

對應於 APNs 負載中的title-loc-key

有關更多信息,請參閱有效負載密鑰參考本地化遠端通知的內容

title_loc_args可選,JSON 數組作為字串

用於取代title_loc_key中的格式說明符的變數字串值,用於將標題文字本地化為使用者目前的本地化。

對應於 APNs 負載中的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可選,字串

用於替換通知抽屜中現有通知的標識符。

如果未指定,每個請求都會建立一個新通知。

如果指定並且已顯示具有相同標籤的通知,則新通知將取代通知抽屜中的現有通知。

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. Web (JavaScript) — 通知訊息的鍵

範圍用法描述
title可選,字串

通知的標題。

body可選,字串

通知的正文。

icon可選,字串

用於通知圖示的 URL。

click_action可選,字串

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

對於所有 URL 值,都需要 HTTPS。

解釋下游 XMPP 訊息回應

下表列出了下游 XMPP 訊息回應中出現的欄位。

表3下行訊息XMPP響應體。

範圍用法描述
from必填,字串

此參數指定誰發送了該回應。

該值為客戶端應用程式的註冊令牌。

message_id必填,字串此參數唯一標識XMPP連線中的消息。該值是唯一標識關聯訊息的字串。
message_type必填,字串

此參數指定從 FCM 到應用程式伺服器的acknack訊息。

如果該值設定為nack ,應用程式伺服器應查看errorerror_description以取得失敗資訊。

error可選,字串此參數指定與下游訊息相關的錯誤。當message_typenack時設定它。詳細資訊請參閱表4
error_description可選,字串此參數提供錯誤的描述資訊。當message_typenack時設定它。

下游報文錯誤回應碼

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

表4下行報文錯誤回應碼

錯誤XMPP程式碼建議操作
缺少註冊令牌INVALID_JSON檢查請求是否包含註冊令牌(在純文字訊息中的registration_id中,或在 JSON 中的toregistration_ids欄位中)。
無效的 APN 註冊INVALID_JSON對於 iOS 註冊,請檢查用戶端的註冊請求是否包含有效的 APNs 令牌和應用程式 ID。
註冊令牌無效BAD_REGISTRATION檢查您傳遞給伺服器的註冊令牌的格式。確保它與客戶端應用程式透過 FCM 註冊收到的註冊令牌相符。不要截斷或添加額外的字元。
未註冊設備DEVICE_UNREGISTERED現有的註冊令牌可能在多種情況下不再有效,包括:
  • 如果用戶端應用程式向 FCM 取消註冊。
  • 如果用戶端應用程式自動取消註冊(如果用戶卸載該應用程序,則可能會發生這種情況)。例如,在 iOS 上,如果 APNs 報告 APNs 令牌無效。
  • 如果註冊令牌過期(例如,Google 可能決定刷新註冊令牌,或裝置的 APNs 令牌已過期)。
  • 如果用戶端應用程式已更新,但新版本未配置為接收訊息。
對於所有這些情況,請從應用程式伺服器中刪除此註冊令牌並停止使用它發送訊息。
寄件者不匹配SENDER_ID_MISMATCH註冊令牌與特定的發送者群組相關聯。當客戶端應用程式註冊 FCM 時,它必須指定允許哪些寄件者傳送訊息。向客戶端應用程式發送訊息時,您應該使用這些寄件者 ID 之一。如果您切換到其他寄件人,現有的註冊令牌將無法運作。
無效的 JSON INVALID_JSON檢查 JSON 訊息的格式是否正確並包含有效欄位(例如,確保傳入正確的資料類型)。
訊息太大INVALID_JSON檢查訊息中包含的有效負載資料的總大小是否超過 FCM 限制:大多數訊息為 4096 字節,對於主題訊息為 2048 位元組。這包括鍵和值。
資料金鑰無效INVALID_JSON檢查負載資料是否不包含 FCM 內部使用的金鑰(例如fromgcm或任何以google為前綴的值)。請注意,FCM 也使用某些單字(例如collapse_key ),但在有效負載中允許使用,在這種情況下,有效負載值將被 FCM 值覆蓋。
無效生存時間INVALID_JSON檢查time_to_live中使用的值是否為整數,表示 0 到 2,419,200(4 週)之間的持續時間(以秒為單位)。
錯誤的 ACK 訊息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 裝置的訊息,因為所需的 APNs 驗證金鑰未上傳或已過期。檢查您的開發和生產憑證的有效性。
認證失敗AUTHENTICATION_FAILED無法透過外部推播服務進行身份驗證。檢查您是否使用了正確的 Web 推送憑證。

上游訊息語法

上游訊息是客戶端應用程式發送到應用程式伺服器的訊息。目前只有 XMPP 支援上游訊息傳遞。有關從客戶端應用程式發送訊息的更多信息,請參閱您的平台的文檔。

解釋上游 XMPP 訊息

下表描述了 FCM 為回應來自客戶端應用程式的上游訊息請求而產生的 XMPP 節中的欄位。

表 5上行 XMPP 訊息。

範圍用法描述
from必填,字串

此參數指定訊息的發送者。

該值為客戶端應用程式的註冊令牌。

category必填,字串此參數指定傳送訊息的用戶端應用程式的應用程式套件名稱。
message_id必填,字串此參數指定訊息的唯一ID。
data可選,字串此參數指定訊息負載的鍵值對。

發送ACK訊息

下表描述了應用程式伺服器預期發送到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_type來指示控制訊息的類型。

control_type可選,字串

此參數指定從 FCM 發送的控制訊息的類型。

目前,僅支援CONNECTION_DRAINING 。 FCM 在關閉連線之前傳送此控制訊息以執行負載平衡。當連接耗盡時,不允許將更多訊息發送到連接,但管道中的現有訊息將繼續被處理。