本文件提供將用於傳遞 訊息,透過 Firebase Cloud Messaging 從應用程式伺服器傳送到用戶端應用程式。
使用舊版 HTTP 通訊協定時 應用程式伺服器必須將所有 HTTP 要求導向這個端點:
https://fcm.googleapis.com/fcm/send
可用的參數和選項 以下廣泛類別:
下游訊息語法
本節說明傳送下游訊息及解讀 Firebase Cloud Messaging 的 HTTP 回應。
下游 HTTP 訊息 (JSON)
下表列出 HTTP JSON 訊息的目標、選項和酬載。
表 1.下游 HTTP 訊息 (JSON) 的目標、選項和酬載。
參數 | 用量 | 說明 | |
---|---|---|---|
目標 | |||
to |
選填,字串 |
這個參數可指定訊息的收件者。
這個值可以是裝置註冊權杖、裝置群組的註冊權杖
通知鍵或單一主題 (前置字串為
|
|
registration_ids | 選用,字串陣列 |
這個參數可指定多點傳播訊息的接收者,例如訊息 。
值必須為註冊權杖陣列,以便傳送該
多點傳播訊息陣列必須包含介於 1 至 1000 之間
註冊權杖如要傳送訊息至單一裝置,請使用
多點傳播訊息只能使用 HTTP JSON 格式。 |
|
condition |
選填,字串 | 這個參數可指定條件式的邏輯運算式; 判斷訊息目標 支援的條件:主題,格式為「yourTopic」主題。這個 不區分大小寫。 支援的運算子: |
|
notification_key 已淘汰 |
選填,字串 | 此參數已淘汰。請改用 |
|
選項 | |||
collapse_key |
選填,字串 | 這個參數可識別訊息群組 (例如
請注意,我們無法保證訊息的傳送順序。 注意:一次最多只能使用 4 個不同的收合鍵。也就是說 FCM 可以為每個用戶端應用程式同時儲存 4 則不同的訊息。如果發生以下情況: 超過這個數字,我們無法保證 FCM 會保留哪 4 個收合鍵。 |
|
priority |
選填,字串 | 設定郵件的優先順序。有效值為「normal」和「高」。在 Apple 平台上 這些 Pod 會對應至 APN 優先順序 5 和 10 預設情況下,通知訊息的優先程度較高,而資料訊息則是以高優先順序傳送 以一般優先順序傳送一般優先順序可為用戶端應用程式的 但除非需要立即交付,否則應使用電量。 如果是優先順序為「一般」的訊息,應用程式可能會收到含有 未指定延遲時間 如果傳送的是高優先順序的訊息,系統就會立即傳送訊息,並將應用程式傳送到應用程式 可顯示通知 |
|
content_available |
選填,布林值 | 在 Apple 平台上,請使用這個欄位代表 |
|
mutable_content |
選用,JSON 布林值 | 如果是 Apple 平台,請使用這個欄位
|
|
time_to_live |
選填,數字 | 這個參數可指定訊息應在 FCM 儲存空間中保留多久 (以秒為單位) 裝置離線。上線時間上限是 4 週,預設值為 4 週。 詳情請參閱「設定訊息的效期」。 |
|
restricted_package_
(僅限 Android 裝置) |
選填,字串 | 這個參數會指定應用程式的套件名稱, 註冊符記必須相符,才能接收訊息。 | |
dry_run |
選填,布林值 | 如果將這項參數設為 預設值為 |
|
酬載 | |||
data |
選填,物件 | 這個參數可指定訊息酬載的自訂鍵/值組合。 例如,使用 在 Apple 平台上,如果訊息是透過 APN 傳送,則代表自訂資料欄位。如果是透過 FCM 傳送,
該字串會在 在 Android 上,這會產生名為 金鑰不得為保留字詞 (「from」、「message_type」),或任何開頭為
Google或「gcm」)。請勿使用本表中定義的任何字詞
(例如 建議使用字串類型的值。您必須在物件或其他非字串資料類型中轉換值 (例如整數或布林值) 至字串。 |
|
notification |
選填,物件 | 這個參數會指定使用者能夠查看的預先定義鍵/值組合
通知酬載詳情請參閱「通知酬載支援」。
如要進一步瞭解通知訊息和資料訊息選項,
看
訊息類型:如果有提供通知酬載,或
將訊息傳送給 Apple 的「content_available 」選項已設為「true 」
訊息,訊息會透過 APN 傳送,否則訊息是經由 APN 傳送
FCM。
|
通知酬載支援
下表列出 鍵。
表 2a:iOS - 通知訊息的鍵
參數 | 用量 | 說明 |
---|---|---|
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 酬載中的 詳情請見 酬載金鑰參考資料和 將遠端通知內容本地化 可能不準確或不適當 |
表 2b.Android - 通知訊息的鍵
參數 | 用量 | 說明 |
---|---|---|
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 陣列做為字串 |
用來取代格式指定碼的變數字串值
詳情請見 格式和樣式瞭解詳情。 |
表 2c.網頁 (JavaScript):通知訊息的鍵
參數 | 用量 | 說明 |
---|---|---|
title |
選填,字串 |
通知的標題。 |
body |
選填,字串 |
通知的內文。 |
icon |
選填,字串 |
通知圖示所用的網址。 |
click_action |
選填,字串 |
與使用者點擊通知相關的動作。 所有網址值都必須使用 HTTPS。 |
下游 HTTP 訊息 (純文字)
下表以純文字格式列出目標、選項和酬載的語法 文字下游 HTTP 訊息
表 3.下游純文字 HTTP 訊息的目標、選項和酬載。
參數 | 用量 | 說明 |
---|---|---|
目標 | ||
registration_id |
必要,字串 | 這個參數會指定接收訊息的用戶端應用程式 (註冊權杖)。 多點傳播訊息 (傳送至多個註冊權杖) 只能使用 HTTP JSON 格式。 |
選項 | ||
collapse_key |
選填,字串 | 詳情請參閱表 1。 |
time_to_live |
選填,數字 | 詳情請參閱表 1。 |
restricted_package_name |
選填,字串 | 詳情請參閱表 1。 |
dry_run |
選填,布林值 | 詳情請參閱表 1。 |
酬載 | ||
data.<key> |
選填,字串 | 這個參數會指定訊息酬載的鍵/值組合。 鍵/值參數沒有數量限制 但訊息的總大小上限為 4,096 個位元組。 例如,在 Android 中, 金鑰不得為保留字詞 (「from」、「message_type」),或任何開頭為
Google或「gcm」)。請勿使用本表中定義的任何字詞
(例如 |
解讀下游訊息回應
應用程式伺服器應評估訊息回應標頭和內文 解讀從 FCM 傳送的訊息回覆。下表 描述可能的回應
表 4.下游 HTTP 訊息回應標頭。
回應 | 說明 |
---|---|
200 | 已成功處理訊息。回應主體會包含更多 訊息狀態的詳細資料,但格式會因要求 可以是 JSON 或純文字請參閱表 5 ,掌握更多詳細資訊。 |
400 | 僅適用於 JSON 要求。 表示要求無法剖析為 JSON,或包含無效要求 欄位 (例如傳送預期數字的字串)。與 會在回應中說明失敗原因,以便解決問題 才能重試要求 |
401 | 驗證寄件者帳戶時發生錯誤。 |
5xx | 如果錯誤範圍落在 500-599 範圍內 (例如 500 或 503),代表
嘗試處理要求時 FCM 後端發生內部錯誤,或
伺服器暫時無法使用 (例如作業逾時),寄件者
必須稍後重試,且遵循Retry-After
回應。應用程式伺服器必須實作指數輪詢。 |
下表列出了下游訊息回應內文中的欄位 (JSON)。
表 5.下游 HTTP 訊息回應主體 (JSON)。
參數 | 用量 | 說明 |
---|---|---|
multicast_id |
必填,數字 | 用於識別多點傳播訊息的專屬 ID (數字)。 |
success |
必填,數字 | 已處理且沒有錯誤的訊息數量。 |
failure |
必填,數字 | 無法處理的訊息數量。 |
results |
必要,物件陣列 | 代表已處理訊息狀態的物件陣列。
物件會列在與要求的順序相同 (亦即每筆註冊
時,其結果會在回應的同一個索引中列出)。
|
表 6.主題訊息 HTTP 回應主體 (JSON)。
參數 | 用量 | 說明 |
---|---|---|
message_id |
選填,數字 | 主題訊息 ID:FCM 成功收到要求,並 會嘗試傳送至所有訂閱的裝置。 |
error |
選填,字串 | 處理訊息時發生錯誤。 可能的值列於表 9。 |
表 7.下游 HTTP 訊息回應內文 (純文字) 的成功回應。
參數 | 用量 | 說明 |
---|---|---|
id |
必要,字串 | 這個參數指定已成功處理的專屬訊息 ID FCM。 |
registration_id |
選填,字串 | 這個參數會指定訊息所代表的用戶端應用程式註冊權杖 而是會接收並傳送至 |
表 8.下游 HTTP 訊息回應內文 (純文字) 的錯誤回應。
參數 | 用量 | 說明 |
---|---|---|
Error |
必要,字串 | 這個參數會在處理收件者訊息時指定錯誤值。 詳情請參閱表 9。 |
下游訊息錯誤回應代碼
下表列出下游訊息的錯誤回應代碼。
表 9.下游訊息錯誤回應代碼。
錯誤 | HTTP 代碼 | 建議做法 |
---|---|---|
缺少註冊權杖 | 200 + 錯誤: MissingRegistration | 檢查請求中,是否已包含註冊權杖 (位於
純文字訊息中的 registration_id ,或出現在 to 中
或 JSON 中的 registration_ids 欄位)。 |
註冊權杖無效 | 200 + 錯誤:註冊無效 | 檢查您傳遞至伺服器的註冊權杖格式。確定 與用戶端應用程式在註冊 Firebase 時收到的註冊權杖相符 通知。請勿截斷或新增其他字元。 |
未註冊的裝置 | 200 + 錯誤:未註冊 | 現有的註冊權杖可能會在許多情況下失效,包括:
|
套件名稱無效 | 200 + 錯誤:InvalidPackageName | 確認訊息已傳送至套件名稱的註冊權杖 與要求中傳送的值相符。 |
驗證錯誤 | 401 | 無法驗證用來傳送郵件的寄件者帳戶。可能的原因如下:
|
寄件者不符 | 200 + error:MismatchSenderId | 註冊權杖會與特定一群寄件者相關聯。當用戶端應用程式註冊時 FCM 時,必須指定哪些寄件者可以傳送郵件。您應該使用一組 才能加密訊息至用戶端應用程式。如果您切換到其他 寄件者,現有的註冊權杖將失效。 |
JSON 無效 | 400 | 請檢查 JSON 訊息格式是否正確且包含有效欄位 (例如,確認傳入正確的資料類型)。 |
參數無效 | 400 + error:InvalidParameters | 確認提供的參數名稱和類型正確無誤。 |
訊息太大 | 200 + 錯誤:MessageTooBig | 檢查訊息內含的酬載資料總大小是否 不得超過 FCM 限制:大部分訊息為 4096 個位元組,案件最多 2048 個位元組 把訊息轉換為主題這包括 這些鍵和值 |
資料金鑰無效 | 200 + 錯誤:
資料金鑰無效 |
確認酬載資料不含金鑰 (例如 from 、
或 gcm ,或任何值
前方加上 google ),供 FCM 內部使用。請注意部分字詞,例如 collapse_key
也用於酬載,但 FCM
,FCM 值將覆寫酬載值。 |
無效存留時間 | 200 + 錯誤:InvalidTtl | 確認 time_to_live 中使用的值是代表
時間長度,以秒為單位,介於 0 到 2,419,200 (4 週) 之間。 |
逾時 | 5xx 或 200 + 錯誤:無法使用 | 伺服器無法及時處理要求。重試相同要求,但你必須:
系統會將會造成問題風險的寄件者列入黑名單。 |
內部伺服器錯誤 | 500 或 200 + error:InternalServerError | 伺服器嘗試處理要求時發生錯誤。你可以再試一次 要求使用「逾時」(請見上列)。如果錯誤 如仍持續發生,請與 Firebase 支援團隊聯絡。 |
超過裝置訊息速率 | 200 + 錯誤:
裝置訊息速率 超過 |
傳送到特定裝置的訊息頻率過高。如果是 Apple 應用程式 傳送訊息的速率超過 APN 限制,就可能收到這則錯誤訊息 減少 傳送到這部裝置及傳送的訊息數量 使用指數輪詢 重試傳送。 |
超出主題訊息率 | 200 + 錯誤:
主題訊息率 超過 |
特定主題的訊息訂閱者比率過高。減少 針對這個主題傳送的訊息數量和 使用指數輪詢 重試傳送。 |
APN 憑證無效 | 200 + 錯誤:
ApnsCredential 無效 |
無法傳送指定 Apple 裝置的訊息,因為必要的 APN 未上傳驗證金鑰或驗證金鑰已過期。檢查開發作業的有效性 和實際工作環境的憑證 |
裝置管理
下表列出建立裝置群組的金鑰 以及新增及移除成員詳情請參閱 做為平台的指南 iOS+ 或 Android:
表 10.裝置群組管理金鑰。
參數 | 用量 | 說明 |
---|---|---|
operation |
必要,字串 | 要執行的作業。有效值為 create 、
add 和remove 。 |
notification_key_name |
必要,字串 | 要建立或修改的裝置群組名稱。 |
notification_key |
必要 (create 作業、字串除外) |
裝置群組的專屬 ID。這個值
會在成功 create 的回應中傳回
執行,且
對裝置群組所有後續作業都一樣。 |
registration_ids |
必要,字串陣列 | 要新增或移除的裝置權杖。如果您移除所有的現有 裝置群組中註冊憑證,FCM 會刪除裝置群組。 |