本文件提供 md 語法的參考資料,用於在應用程式伺服器、用戶端應用程式和 Firebase 雲端通訊 (FCM) 之間傳遞訊息。應用程式伺服器必須連線至以下端點:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
可用的參數和選項分為以下類別:
下游訊息語法
本節說明傳送下游訊息的語法。
下游 XMPP 訊息 (JSON)
下表列出 XMPP JSON 訊息的目標、選項和酬載。
參數 | 用量 | 說明 | |
---|---|---|---|
目標 | |||
to |
選填,字串 |
這個參數可指定訊息的收件者。
這個值可以是裝置的註冊權杖、裝置群組的通知鍵或單一主題 (前置字串為 |
|
condition |
選填,字串 | 這個參數會指定條件的邏輯運算式,以決定訊息目標。 支援條件:主題,格式為「yourTopics in topics」。這個值不區分大小寫。 支援的運算子: |
|
選項 | |||
message_id |
必要,字串 | 這個參數可明確識別 XMPP 連線中的訊息。 |
|
collapse_key |
選填,字串 | 這個參數可識別可收合的一組訊息 (例如使用 我們無法保證訊息的傳送順序。 注意:一次最多只能使用 4 個不同的收合鍵。這表示每個用戶端應用程式可同時儲存 4 則不同的訊息。如果超過這個數字,FCM 不一定會保留 4 個收合金鑰。 |
|
priority |
選填,字串 | 設定郵件的優先順序。有效值為「normal」和「高」。在 Apple 平台上,這些要求會對應至 APN 優先順序 5 和 10。 預設情況下,通知訊息會以高優先順序傳送,而資料訊息會以一般優先順序傳送。「一般優先順序」會最佳化用戶端應用程式的電池耗電量。除非需要立即提供功能,否則應使用這種優先順序。如果訊息的優先順序為一般,應用程式可能會收到未指定延遲時間的訊息。 如果訊息的優先順序較高,系統會立即傳送訊息,而且應用程式可以顯示通知。 |
|
content_available |
選填,布林值 | 在 Apple 平台上,請使用這個欄位代表 APN 酬載中的 |
|
mutable_content |
選用,JSON 布林值 | 在 Apple 平台上,請使用這個欄位代表 APN 酬載中的 |
|
time_to_live |
選填,數字 | 此參數用於指定裝置離線時,訊息應在 FCM 儲存空間保留的時間長度 (秒)。存留時間上限為 4 週,預設值為 4 週。詳情請參閱「設定訊息的效期」。 |
|
dry_run |
選填,布林值 | 如果將這個參數設為 預設值為 |
|
酬載 | |||
data |
選填,物件 | 這個參數會指定訊息酬載的鍵/值組合。 例如,使用 在 Apple 平台上,如果訊息是由 APNs 傳送,則代表自訂資料欄位。如果是由 FCM 傳送,則會在 在 Android 上,這會產生名為 金鑰不得為保留字詞 (「from」、「message_type」),或是任何以「google」或「gcm」開頭的字詞。請勿使用這個表格中定義的任何字詞,例如 建議使用字串類型的值。您必須將物件或其他非字串資料類型 (例如整數或布林值) 中的值轉換為字串。 |
|
notification |
選填,物件 | 這個參數會指定使用者可見的預先定義通知酬載鍵/值組合,詳情請參閱「通知酬載支援」。如要進一步瞭解通知訊息和資料訊息選項,請參閱「
訊息類型」。如果提供通知酬載,或針對傳送至 Apple 裝置的訊息,將 content_available 選項設為 true ,則訊息會透過 APN 傳送,否則訊息會透過 FCM 傳送。 |
通知酬載支援
下表列出可用來建構 Apple 平台和 Android 通知訊息的預先定義鍵。
參數 | 用量 | 說明 |
---|---|---|
title |
選填,字串 |
通知的標題。 手機和平板電腦不會顯示這個欄位。 |
body |
選填,字串 |
通知的內文。 |
sound |
選填,字串 |
裝置收到通知時要播放的音效。
此字串用於指定用戶端應用程式主要套件,或應用程式資料容器的 |
badge |
選填,字串 |
主畫面應用程式圖示上的徽章值。 如未指定,則徽章不會變更。
如果設為 |
click_action |
選填,字串 |
與使用者點擊通知相關的動作。
對應至 APN 酬載中的 |
subtitle |
選填,字串 |
通知的副標題。 |
body_loc_key |
選填,字串 |
應用程式字串資源中的主體字串鍵,用來將內文文字本地化至使用者目前的本地化。
對應至 APN 酬載中的 |
body_loc_args |
選用,JSON 陣列做為字串 |
用來取代
對應至 APN 酬載中的 |
title_loc_key |
選填,字串 |
應用程式字串資源中標題字串的鍵,用來將標題文字本地化,為使用者目前的本地化內容。
對應至 APN 酬載中的 |
title_loc_args |
選用,JSON 陣列做為字串 |
用來取代
對應至 APN 酬載中的 |
參數 | 用量 | 說明 |
---|---|---|
title |
選填,字串 |
通知的標題。 |
body |
選填,字串 |
通知的內文。 |
android_channel_id |
選填,字串 |
通知的頻道 ID (在 Android O 中新增)。 應用程式必須先使用這個管道 ID 建立頻道,才能接收任何含有這個頻道 ID 的通知。 如果您未在要求中傳送這個頻道 ID,或是尚未建立應用程式提供的頻道 ID,FCM 會使用應用程式資訊清單中指定的頻道 ID。 |
icon |
選填,字串 |
通知圖示。
將可繪製資源 |
sound |
選填,字串 |
裝置收到通知時要播放的音效。
支援 |
tag |
選填,字串 |
用於取代通知導覽匣中現有通知的 ID。 如未指定,每個要求都會建立新通知。 如果已指定,且已顯示含有相同標記的通知,新通知會取代通知導覽匣中的現有通知。 |
color |
選填,字串 |
通知的圖示顏色,以 |
click_action |
選填,字串 |
與使用者點擊通知相關的動作。 如果有指定,系統就會在使用者點選通知時啟動具有相符意圖篩選器的活動。 |
body_loc_key |
選填,字串 |
應用程式字串資源中的主體字串鍵,用來將內文文字本地化至使用者目前的本地化。 詳情請參閱「 字串資源」。 |
body_loc_args |
選用,JSON 陣列做為字串 |
用來取代 詳情請參閱「 格式設定和樣式」一文。 |
title_loc_key |
選填,字串 |
應用程式字串資源中標題字串的鍵,用來將標題文字本地化,為使用者目前的本地化內容。 詳情請參閱「 字串資源」。 |
title_loc_args |
選用,JSON 陣列做為字串 |
用來取代 詳情請參閱「 格式設定和樣式」一文。 |
參數 | 用量 | 說明 |
---|---|---|
title |
選填,字串 |
通知的標題。 |
body |
選填,字串 |
通知的內文。 |
icon |
選填,字串 |
通知圖示所使用的網址。 |
click_action |
選填,字串 |
與使用者點擊通知相關的動作。 所有網址值都必須使用 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 註冊,請確認用戶端的註冊要求包含有效的 APN 權杖和應用程式 ID。 |
註冊權杖無效 | BAD_REGISTRATION |
檢查您傳遞至伺服器的註冊權杖格式。請確定這個 ID 與用戶端應用程式向 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 週) 之間的時間長度,以秒為單位。 |
確認訊息無效 | BAD_ACK |
請確認 ack 訊息的格式正確,然後再重試。詳情請參閱表 6。 |
逾時 | SERVICE_UNAVAILABLE |
伺服器無法及時處理要求。重試相同要求,但你必須:
注意:系統會將可能造成問題風險的寄件者列入黑名單。 |
內部伺服器錯誤 | INTERNAL_SERVER_
|
伺服器嘗試處理要求時發生錯誤。您可以按照「逾時」一節所列的要求,重試相同要求 (請參閱上列)。 |
超過裝置訊息速率 | DEVICE_MESSAGE_RATE |
傳送到特定裝置的訊息頻率過高。請減少傳送至這部裝置的訊息數量,但不要立即重試傳送至這部裝置。 |
超出主題訊息率 | TOPICS_MESSAGE_RATE |
特定主題的訊息訂閱者比率過高。請減少針對這個主題傳送的訊息數量,不要立即重試。 |
連線排除 | CONNECTION_DRAINING |
正在排除連線,因此無法處理訊息。這是因為 FCM 必須定期關閉連線,才能執行負載平衡。透過其他 XMPP 連線重試訊息。 |
APN 憑證無效 | INVALID_APNS_CREDENTIAL |
無法傳送指定至 iOS 裝置的訊息,因為必要的 APN 驗證金鑰未上傳或已過期。檢查開發和正式環境憑證是否有效。 |
驗證失敗 | AUTHENTICATION_FAILED |
無法使用外部推送服務進行驗證。請檢查您使用的網路推播憑證是否正確。 |
上游訊息語法
上游訊息是用戶端應用程式傳送至應用程式伺服器的訊息。XMPP 目前僅支援上游訊息。如要進一步瞭解如何從用戶端應用程式傳送訊息,請參閱所用平台的說明文件。
解讀上游 XMPP 訊息
下表說明 FCM 為回應用戶端應用程式發出的上游訊息要求而產生的 XMPP 節中的欄位。
參數 | 用量 | 說明 |
---|---|---|
from |
必要,字串 | 這個參數可指定訊息的傳送者。 值為用戶端應用程式的註冊權杖。 |
category |
必要,字串 | 這個參數會指定傳送訊息的用戶端應用程式應用程式套件名稱。 |
message_id |
必要,字串 | 這個參數可指定訊息的專屬 ID。 |
data |
選填,字串 | 這個參數會指定訊息酬載的鍵/值組合。 |
傳送確認訊息
下表說明應用程式伺服器應傳送至 FCM 的 ACK 回應,以回應應用程式伺服器收到的上游訊息。
參數 | 用量 | 說明 |
---|---|---|
to |
必要,字串 | 這個參數可指定回應訊息的收件者。 這個值必須是傳送上游訊息的用戶端應用程式註冊權杖。 |
message_id |
必要,字串 | 這個參數會指定回應的目標訊息。這個值必須是對應上游訊息中的 message_id 值。 |
message_type |
必要,字串 | 這個參數會指定從應用程式伺服器傳至 CCS 的 ack 訊息。對於上游訊息,應一律設為 ack 。 |
FCM 伺服器訊息 (XMPP)
這是從 FCM 傳送至應用程式伺服器的訊息。以下是 FCM 傳送至應用程式伺服器的主要訊息類型:
- 控制:這些 CCS 產生的訊息表示需要從應用程式伺服器採取行動。
下表說明 CCS 傳送至應用程式伺服器的訊息所含欄位。
參數 | 用量 | 說明 |
---|---|---|
常用欄位 | ||
message_type |
必要,字串 | 這個參數會指定訊息的類型:control。 設為 |
control_type |
選填,字串 | 這個參數會指定從 FCM 傳送的控制訊息類型。 目前僅支援 |