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