本文件提供 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 |
選填,字串 | 這個參數指定的邏輯運算式會決定訊息目標。 支援的條件:主題,格式為「<主題>」。這個值不區分大小寫。 支援的運算子: |
|
notification_key 已淘汰 |
選填,字串 | 此參數已淘汰。請改用 |
|
選項 | |||
collapse_key |
選填,字串 | 此參數可識別可收合的一組訊息 (例如包含 請注意,我們無法保證訊息的傳送順序。 注意:在任何指定時間內,最多可有 4 個不同的收合鍵。這表示 FCM 可以為每個用戶端應用程式同時儲存 4 則不同的訊息。如果超過這個數量,則無法保證 FCM 會保留哪 4 個收合金鑰。 |
|
priority |
選填,字串 | 設定訊息的優先順序。有效值為「正常」和「高」。在 Apple 平台上,這些 ID 相當於 5 和 10 的 APN 優先順序。 根據預設,通知訊息會以高優先順序傳送,資料訊息則會以一般優先順序傳送。一般優先順序會最佳化用戶端應用程式的電池消耗量,因此除非需要立即提交,否則應使用此功能。對於優先順序較高的訊息,應用程式可能會收到未指定延遲時間的訊息。 高優先順序的訊息會立即傳送,且應用程式可以顯示通知。 |
|
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 |
選用,物件 | 這個參數會指定通知酬載的預先定義、使用者可以看見的鍵/值組合。詳情請參閱通知酬載支援。如要進一步瞭解通知訊息和資料訊息選項,請參閱「
訊息類型」。如果提供了通知酬載,或是將訊息的 content_available 選項設為 true ,訊息會透過 APNs 傳送,否則訊息會透過 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> |
選填,字串 | 這個參數會指定訊息酬載的鍵/值組合。鍵/值參數的數量沒有限制,但訊息總大小限制為 4096 個位元組。 舉例來說,在 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 + 錯誤:缺少註冊 | 檢查要求是否包含註冊權杖 (在純文字訊息的 registration_id 或 JSON 的 to 或 registration_ids 欄位中)。 |
註冊權杖無效 | 200 + 錯誤:InvalidRegistration | 檢查傳送給伺服器的註冊權杖格式。請確保用戶端應用程式透過註冊 Firebase 通知而收到的註冊權杖相符。請勿截斷或新增其他字元。 |
未註冊的裝置 | 200 + 錯誤:未註冊 | 現有的註冊權杖在多種情況下可能會失效,包括:
|
套件名稱無效 | 200 + 錯誤:InvalidPackageName | 確認訊息已傳送至註冊權杖,該權杖的套件名稱與要求中傳遞的值相符。 |
驗證發生錯誤 | 401 | 無法驗證用來傳送郵件的寄件者帳戶。可能的原因包括:
|
寄件者不符 | 200 + error:MismatchSenderId | 註冊權杖與特定的寄件者群組相關聯。用戶端應用程式註冊 FCM 時,必須指定允許哪些寄件者傳送訊息。傳送訊息至用戶端應用程式時,您應使用其中一個傳送者 ID。如果您切換至其他傳送者,現有的註冊憑證將無法運作。 |
JSON 無效 | 400 | 檢查 JSON 訊息的格式是否正確,且包含有效的欄位 (例如,確認傳入的資料類型正確無誤)。 |
參數無效 | 400 + 錯誤:InvalidParameters | 請確認提供的參數名稱和類型正確無誤。 |
訊息太大 | 200 + 錯誤:MessageTooBig | 確認訊息中包含的酬載資料總大小並未超過 FCM 限制:多數訊息為 4096 個位元組;如果對主題傳送訊息,則為 2048 位元組。包括鍵和值。 |
資料鍵無效 | 200 + 錯誤:
InvalidDataKey |
確認酬載資料不含 FCM 內部使用的索引鍵 (例如 from 、gcm 或 google 開頭的任何值)。請注意,某些字詞 (例如 collapse_key ) 也適用於 FCM,但允許在酬載中使用,在這種情況下,FCM 值會覆寫酬載值。 |
無效的存留時間 | 200 + 錯誤:InvalidTtl | 確認 time_to_live 中使用的值是否為整數,代表介於 0 至 2,419,200 (4 週) 之間的持續時間,以秒為單位。 |
逾時 | 5xx 或 200 + 錯誤:Unavailable | 伺服器無法及時處理這項要求。重試相同的要求,但您必須:
導致問題風險的寄件者被列入黑名單。 |
內部伺服器錯誤 | 500 或 200 + 錯誤:InternalServerError | 伺服器在嘗試處理要求時發生錯誤。您可以按照「逾時」所列的規定重試相同要求 (請參閱上方列)。如果錯誤持續發生,請與 Firebase 支援團隊聯絡。 |
裝置訊息傳送率超過上限 | 200 + 錯誤:
DeviceMessageRate 超過 |
傳送至特定裝置的訊息速率過高。如果 Apple 應用程式傳送訊息的頻率超過 APNs 限制,可能會收到這則錯誤訊息 減少傳送至這部裝置的訊息數量,並使用指數輪詢重試傳送。 |
主題訊息傳送率超過上限 | 200 + 錯誤:
TopicsMessageRate 超過 |
向訂閱者傳送特定主題的訊息的頻率過高。請減少針對這個主題傳送的訊息數量,並使用指數輪詢重試傳送。 |
APN 憑證無效 | 200 + 錯誤:
InvalidApnsCredential |
未上傳必要的 APN 驗證金鑰或驗證金鑰已過期,因此無法傳送指定 Apple 裝置的訊息。請檢查開發與實際工作環境憑證是否有效。 |
裝置群組管理
下表列出建立裝置群組及新增及移除成員的鍵。詳情請參閱所用平台適用的指南: iOS+ 或 Android。
參數 | 使用方式 | 說明 |
---|---|---|
operation |
必要,字串 | 要執行的作業。有效值為 create 、add 和 remove 。 |
notification_key_name |
必要,字串 | 要建立或修改的裝置群組的使用者定義名稱。 |
notification_key |
必要 (create 作業、字串除外) |
裝置群組的專屬 ID。如果 create 作業成功,系統會在回應中傳回這個值;對裝置群組的所有後續操作都必須提供這個值。 |
registration_ids |
必要,字串陣列 | 要新增或移除的裝置權杖,如果你從裝置群組中移除所有現有的註冊權杖,FCM 會刪除該裝置群組。 |