本文檔提供了在應用程式伺服器、用戶端應用程式和 Firebase Cloud Messaging (FCM) 之間傳遞訊息的 XMPP 語法的參考。您的應用程式伺服器必須連接到這些端點:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
可用的參數和選項分為以下幾類:
下游訊息語法
本節給出發送下游訊息的語法。
下游 XMPP 訊息 (JSON)
下表列出了 XMPP JSON 訊息的目標、選項和負載。
範圍 | 用法 | 描述 | |
---|---|---|---|
目標 | |||
to | 可選,字串 | 此參數指定訊息的接收者。 該值可以是設備的註冊令牌、設備群組的通知金鑰或單一主題(以 | |
condition | 可選,字串 | 此參數指定確定訊息目標的條件的邏輯表達式。 支援的條件:主題,格式為「主題中的'yourTopic'」。該值不區分大小寫。 支援的運算子: | |
選項 | |||
message_id | 必填,字串 | 此參數唯一標識XMPP連線中的消息。 | |
collapse_key | 可選,字串 | 此參數標識可以折疊的一組訊息(例如,使用 無法保證訊息發送的順序。 注意:在任何給定時間最多允許使用 4 個不同的折疊鍵。這意味著 FCM 可以為每個客戶端應用程式同時儲存 4 個不同的訊息。如果超過此數量,則無法保證 FCM 將保留哪 4 個折疊鍵。 | |
priority | 可選,字串 | 設定訊息的優先順序。有效值為“正常”和“高”。在 Apple 平台上,這些對應於 APN 優先權 5 和 10。 預設情況下,通知訊息以高優先順序發送,資料訊息以普通優先權發送。正常優先順序可最佳化用戶端應用程式的電池消耗,除非需要立即交付,否則應使用正常優先順序。對於具有正常優先權的訊息,應用程式可能會以未指定的延遲接收訊息。 當發送高優先級訊息時,會立即發送,並且應用程式可以顯示通知。 | |
content_available | 可選,布林值 | 在 Apple 平台上,使用此欄位表示 APNs 負載中 | |
mutable_content | 可選,JSON 布林值 | 在 Apple 平台上,使用此欄位來表示 APNs 負載中的 | |
time_to_live | 可選,數量 | 此參數指定如果設備離線,訊息應在 FCM 儲存中保留多長時間(以秒為單位)。支援的最長生存時間為 4 週,預設值為 4 週。有關詳細信息,請參閱設定訊息的生命週期。 | |
dry_run | 可選,布林值 | 當此參數設為 預設值為 | |
有效載荷 | |||
data | 可選,對象 | 此參數指定訊息負載的鍵值對。 例如,對於 在 Apple 平台上,如果訊息是透過 APN 傳遞的,則它代表自訂資料欄位。如果由 FCM 傳遞,則在 在 Android 上,這會產生一個名為 鍵不應是保留字(“from”、“message_type”或任何以“google”或“gcm”開頭的單字)。不要使用此表中定義的任何單字(例如 建議使用字串類型的值。您必須將物件或其他非字串資料類型(例如整數或布林值)中的值轉換為字串。 | |
notification | 可選,對象 | 此參數指定通知負載的預先定義、使用者可見的鍵值對。有關詳細信息,請參閱通知負載支援。有關通知訊息和資料訊息選項的更多信息,請參閱訊息類型。如果提供了通知有效負載,或將傳送至 Apple 裝置的訊息的content_available 選項設為true ,則訊息將透過 APNs 傳送,否則將透過 FCM 傳送。 |
通知負載支持
下表列出了可用於為 Apple 平台和 Android 建立通知訊息的預先定義鍵。
範圍 | 用法 | 描述 |
---|---|---|
title | 可選,字串 | 通知的標題。 該欄位在手機和平板電腦上不可見。 |
body | 可選,字串 | 通知的正文。 |
sound | 可選,字串 | 設備收到通知時播放的聲音。 指定客戶端應用程式主包中或應用程式資料容器的 |
badge | 可選,字串 | 主螢幕應用程式圖示上的徽章的值。 如果未指定,則不會變更徽章。 如果設定為 |
click_action | 可選,字串 | 與使用者點選通知關聯的操作。 對應於 APNs 負載中的 |
subtitle | 可選,字串 | 通知的副標題。 |
body_loc_key | 可選,字串 | 應用程式字串資源中正文字串的鍵,用於將正文文字本地化為使用者目前的本地化。 對應於 APNs 負載中的 有關更多信息,請參閱有效負載密鑰參考和本地化遠端通知的內容。 |
body_loc_args | 可選,JSON 數組作為字串 | 用於取代 對應於 APNs 負載中的 有關更多信息,請參閱有效負載密鑰參考和本地化遠端通知的內容。 |
title_loc_key | 可選,字串 | 應用程式字串資源中標題字串的鍵,用於將標題文字本地化為使用者目前的本地化版本。 對應於 APNs 負載中的 有關更多信息,請參閱有效負載密鑰參考和本地化遠端通知的內容。 |
title_loc_args | 可選,JSON 數組作為字串 | 用於取代 對應於 APNs 負載中的 有關更多信息,請參閱有效負載密鑰參考和本地化遠端通知的內容。 |
範圍 | 用法 | 描述 |
---|---|---|
title | 可選,字串 | 通知的標題。 |
body | 可選,字串 | 通知的正文。 |
android_channel_id | 可選,字串 | 通知的頻道 ID (Android O 中的新增功能)。 在收到具有此通道 ID 的任何通知之前,應用程式必須建立具有此通道 ID 的通道。 如果您未在請求中傳送此通道 ID,或套用尚未建立提供的通道 ID,則 FCM 將使用應用程式清單中指定的通道 ID。 |
icon | 可選,字串 | 通知的圖示。 將可繪製資源 |
sound | 可選,字串 | 設備收到通知時播放的聲音。 支援 |
tag | 可選,字串 | 用於替換通知抽屜中現有通知的標識符。 如果未指定,每個請求都會建立一個新通知。 如果指定並且已顯示具有相同標籤的通知,則新通知將取代通知抽屜中的現有通知。 |
color | 可選,字串 | 通知的圖示顏色,以 |
click_action | 可選,字串 | 與使用者點選通知關聯的操作。 如果指定,當使用者按一下通知時,將啟動具有匹配意圖過濾器的活動。 |
body_loc_key | 可選,字串 | 應用程式字串資源中正文字串的鍵,用於將正文文字本地化為使用者目前的本地化。 有關詳細信息,請參閱字串資源。 |
body_loc_args | 可選,JSON 數組作為字串 | 用於取代 有關詳細信息,請參閱格式和样式。 |
title_loc_key | 可選,字串 | 應用程式字串資源中標題字串的鍵,用於將標題文字本地化為使用者目前的本地化版本。 有關詳細信息,請參閱字串資源。 |
title_loc_args | 可選,JSON 數組作為字串 | 用於取代 有關詳細信息,請參閱格式和样式。 |
範圍 | 用法 | 描述 |
---|---|---|
title | 可選,字串 | 通知的標題。 |
body | 可選,字串 | 通知的正文。 |
icon | 可選,字串 | 用於通知圖示的 URL。 |
click_action | 可選,字串 | 與使用者點選通知關聯的操作。 對於所有 URL 值,都需要 HTTPS。 |
解釋下游 XMPP 訊息回應
下表列出了下游 XMPP 訊息回應中出現的欄位。
範圍 | 用法 | 描述 |
---|---|---|
from | 必填,字串 | 此參數指定誰發送了該回應。 該值為客戶端應用程式的註冊令牌。 |
message_id | 必填,字串 | 此參數唯一標識XMPP連線中的消息。該值是唯一標識關聯訊息的字串。 |
message_type | 必填,字串 | 此參數指定從 FCM 到應用程式伺服器的 如果該值設定為 |
error | 可選,字串 | 此參數指定與下游訊息相關的錯誤。當message_type 為nack 時設定它。詳細資訊請參閱表4 。 |
error_description | 可選,字串 | 此參數提供錯誤的描述資訊。當message_type 為nack 時設定它。 |
下游報文錯誤回應碼
下表列出了下游訊息的錯誤回應碼。
錯誤 | XMPP程式碼 | 建議操作 |
---|---|---|
缺少註冊令牌 | INVALID_JSON | 檢查請求是否包含註冊令牌(在純文字訊息中的registration_id 中,或在 JSON 中的to 或registration_ids 欄位中)。 |
無效的 APN 註冊 | INVALID_JSON | 對於 iOS 註冊,請檢查用戶端的註冊請求是否包含有效的 APNs 令牌和應用程式 ID。 |
註冊令牌無效 | BAD_REGISTRATION | 檢查您傳遞給伺服器的註冊令牌的格式。確保它與客戶端應用程式透過 FCM 註冊收到的註冊令牌相符。不要截斷或添加額外的字元。 |
未註冊設備 | DEVICE_UNREGISTERED | 現有的註冊令牌可能在多種情況下不再有效,包括:
|
寄件者不匹配 | 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 週)之間的持續時間(以秒為單位)。 |
錯誤的 ACK 訊息 | BAD_ACK | 重試前,請檢查ack 的格式是否正確。詳細資訊請參閱表6 。 |
暫停 | SERVICE_UNAVAILABLE | 伺服器無法及時處理請求。重試相同的請求,但您必須:
注意:造成問題的寄件者可能會被列入黑名單。 |
內部伺服器錯誤 | INTERNAL_SERVER_ | 伺服器在嘗試處理請求時遇到錯誤。您可以按照「超時」中列出的要求重試相同的請求(請參閱上面的行)。 |
設備訊息速率超出 | DEVICE_MESSAGE_RATE | 向特定裝置發送訊息的速率太高。減少發送到該設備的訊息數量,並且不要立即重試發送到該設備。 |
主題 訊息速率超出 | TOPICS_MESSAGE_RATE | 向特定主題的訂閱者發送訊息的比率太高。減少為此主題發送的訊息數量,並且不要立即重試發送。 |
連接排空 | CONNECTION_DRAINING | 無法處理該訊息,因為連線正在耗盡。發生這種情況是因為 FCM 需要定期關閉連線以執行負載平衡。透過另一個 XMPP 連線重試該訊息。 |
APN 憑證無效 | INVALID_APNS_CREDENTIAL | 無法傳送針對 iOS 裝置的訊息,因為所需的 APNs 驗證金鑰未上傳或已過期。檢查您的開發和生產憑證的有效性。 |
認證失敗 | AUTHENTICATION_FAILED | 無法透過外部推播服務進行身份驗證。檢查您是否使用了正確的 Web 推送憑證。 |
上游訊息語法
上游訊息是客戶端應用程式發送到應用程式伺服器的訊息。目前只有 XMPP 支援上游訊息傳遞。有關從客戶端應用程式發送訊息的更多信息,請參閱您的平台的文檔。
解釋上游 XMPP 訊息
下表描述了 FCM 為回應來自客戶端應用程式的上游訊息請求而產生的 XMPP 節中的欄位。
範圍 | 用法 | 描述 |
---|---|---|
from | 必填,字串 | 此參數指定訊息的發送者。 該值為客戶端應用程式的註冊令牌。 |
category | 必填,字串 | 此參數指定傳送訊息的用戶端應用程式的應用程式套件名稱。 |
message_id | 必填,字串 | 此參數指定訊息的唯一ID。 |
data | 可選,字串 | 此參數指定訊息負載的鍵值對。 |
發送ACK訊息
下表描述了應用程式伺服器預期發送到FCM以回應應用程式伺服器收到的上游訊息的 ACK 回應。
範圍 | 用法 | 描述 |
---|---|---|
to | 必填,字串 | 此參數指定回應訊息的接收者。 該值必須是發送上游訊息的客戶端應用程式的註冊令牌。 |
message_id | 必填,字串 | 此參數指定回應的目的是哪一則訊息。該值必須是對應上游訊息的message_id 值。 |
message_type | 必填,字串 | 此參數指定從應用伺服器到CCS的ack 訊息。對於上游訊息,應始終將其設為ack 。 |
FCM 伺服器訊息 (XMPP)
這是從 FCM 發送到應用程式伺服器的訊息。以下是 FCM 發送到應用程式伺服器的主要訊息類型:
- 控制:這些 CCS 產生的訊息表示應用程式伺服器需要採取操作。
下表描述了 CCS 發送到應用程式伺服器的訊息中包含的欄位。
範圍 | 用法 | 描述 |
---|---|---|
公共領域 | ||
message_type | 必填,字串 | 此參數指定訊息的類型:控制。 當設定為 |
control_type | 可選,字串 | 此參數指定從 FCM 發送的控制訊息的類型。 目前,僅支援 |