本文件提供用來傳遞 應用程式伺服器、用戶端應用程式和 Firebase 雲端通訊 (FCM) 之間的訊息。 應用程式伺服器必須連線至以下端點:
// 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 可以收合哪些鍵 能夠保存。 |
|
priority |
選填,字串 | 設定郵件的優先順序。有效值為「normal」和「高」。在 Apple 平台上 這些 Pod 會對應至 APN 優先順序 5 和 10 預設情況下,通知訊息的優先程度較高,而資料訊息則是以高優先順序傳送 以一般優先順序傳送一般優先順序可為用戶端應用程式的 但除非需要立即交付,否則應使用電量。 如果是優先順序為「一般」的訊息,應用程式可能會收到含有 未指定延遲時間 如果傳送的是高優先順序的訊息,系統就會立即傳送訊息,並將應用程式傳送到應用程式 可顯示通知 |
|
content_available |
選填,布林值 | 在 Apple 平台上,請使用這個欄位代表 APN 中的 |
|
mutable_content |
選用,JSON 布林值 | 如果是 Apple 平台,請使用這個欄位
|
|
time_to_live |
選填,數字 | 這個參數可指定訊息應在 FCM 儲存空間保留多久 (以秒為單位) 裝置離線。上線時間上限是 4 週,預設值為 4 週。 詳情請參閱「設定訊息的效期」。 |
|
dry_run |
選填,布林值 | 如果將這項參數設為 預設值為 |
|
酬載 | |||
data |
選填,物件 | 這個參數會指定訊息酬載的鍵/值組合。 例如,使用 在 Apple 平台上,如果訊息是由 APNs 傳送,則代表自訂資料欄位。如果
是由 FCM 放送
並在 在 Android 上,這會產生名為 金鑰不得為保留字詞 (「from」、「message_type」),或任何開頭為
Google或「gcm」)。請勿使用本表中定義的任何字詞
(例如 建議使用字串類型的值。您必須在物件或其他非字串資料類型中轉換值 (例如整數或布林值) 至字串。 |
|
notification |
選填,物件 | 這個參數會指定使用者能夠查看的
通知酬載詳情請參閱「通知酬載支援」。如要進一步瞭解
關於通知訊息和資料訊息選項,請參閱
訊息類型:如果有提供通知酬載,或
將訊息傳送給 Apple 的「content_available 」選項已設為「true 」
訊息,訊息會透過 APN 傳送,否則訊息是經由 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 |
必要,字串 | 這個參數會指定來自 如果將值設為 |
error |
選填,字串 | 這個參數指定與下游訊息相關的錯誤。系統會在
message_type 為 nack 。詳情請參閱表 4。 |
error_description |
選填,字串 | 此參數可提供錯誤的描述性資訊。已設定
當 message_type 為 nack 時。 |
下游訊息錯誤回應代碼
下表列出下游訊息的錯誤回應代碼。
錯誤 | XMPP 程式碼 | 建議做法 |
---|---|---|
缺少註冊權杖 | INVALID_JSON |
檢查請求中,是否已包含註冊權杖 (位於
純文字訊息中的 registration_id ,或出現在 to 中
或 JSON 中的 registration_ids 欄位)。 |
APN 註冊無效 | INVALID_JSON |
如果是 iOS 註冊,請確認用戶端的註冊要求包含 有效的 APN 權杖和應用程式 ID |
註冊權杖無效 | BAD_REGISTRATION |
檢查您傳遞至伺服器的註冊權杖格式。確定 與用戶端應用程式註冊 FCM 後收到的註冊權杖相符。禁止事項 截斷或新增其他字元。 |
未註冊的裝置 | DEVICE_UNREGISTERED |
現有的註冊權杖可能會在許多情況下失效,包括:
|
寄件者不符 | SENDER_ID_MISMATCH |
註冊權杖會與特定一群寄件者相關聯。當用戶端應用程式註冊時 FCM 要求,必須指定哪些寄件者可以傳送訊息。您應該使用一組 才能加密訊息至用戶端應用程式。如果您切換到其他 寄件者,現有的註冊權杖將失效。 |
JSON 無效 | INVALID_JSON |
請檢查 JSON 訊息格式是否正確且包含有效欄位 (例如,確認傳入正確的資料類型)。 |
訊息太大 | INVALID_JSON |
檢查訊息內含的酬載資料總大小是否 不得超過 FCM 限制:大部分訊息為 4,096 個位元組,在大多數情況下是 2,048 個位元組 把訊息轉換為主題這包括 這些鍵和值 |
資料金鑰無效 | INVALID_JSON |
確認酬載資料不含金鑰 (例如 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 |
無法使用外部推送服務進行驗證。檢查您是否使用 正確的網路 Push Certificate |
上游訊息語法
上游訊息是用戶端應用程式傳送至應用程式伺服器的訊息。 XMPP 目前僅支援上游訊息。詳情請見 查看您的平台的說明文件 瞭解如何從用戶端應用程式傳送訊息。
解讀上游 XMPP 訊息
下表說明 XMPP 字節產生的欄位。 以回應用戶端應用程式的上游訊息要求。
參數 | 用量 | 說明 |
---|---|---|
from |
必要,字串 | 這個參數可指定訊息的傳送者。 值為用戶端應用程式的註冊權杖。 |
category |
必要,字串 | 這個參數會指定傳送訊息的用戶端應用程式應用程式套件名稱。 |
message_id |
必要,字串 | 這個參數可指定訊息的專屬 ID。 |
data |
選填,字串 | 這個參數會指定訊息酬載的鍵/值組合。 |
傳送確認訊息
下表說明應用程式伺服器應傳送至 ACK 回應 FCM 以回應 應用程式伺服器收到的上游訊息。
參數 | 用量 | 說明 |
---|---|---|
to |
必要,字串 | 這個參數可指定回應訊息的收件者。 這個值必須是傳送上游訊息的用戶端應用程式註冊權杖。 |
message_id |
必要,字串 | 這個參數會指定回應的目標訊息。值必須是
對應上游訊息的 message_id 值。 |
message_type |
必要,字串 | 這個參數會指定從應用程式伺服器傳至 CCS 的 ack 訊息。
對於上游訊息,應一律設為 ack 。 |
FCM 伺服器訊息 (XMPP)
這則訊息是從 FCM 傳送至應用程式伺服器, 以下是 FCM 的主要訊息類型 傳送至應用程式伺服器:
- 控管:這些 CCS 產生的訊息表示 必須從應用程式伺服器進行。
下表說明訊息 CCS 中的欄位 應用程式伺服器
參數 | 用量 | 說明 |
---|---|---|
常用欄位 | ||
message_type |
必要,字串 | 這個參數會指定訊息的類型:control。 設為 |
control_type |
選填,字串 | 這個參數會指定從 FCM 傳送的控制訊息類型。 目前僅支援 |