โปรโตคอล HTTP ของ Firebase Cloud Messaging

ข้อควรระวัง: เราได้เลิกใช้งานการส่งข้อความ (รวมถึงข้อความอัปสตรีม) ด้วย FCM และ HTTP API เดิมไปเมื่อวันที่ 20 มิถุนายน 2023 และจะนำออกในเดือนมิถุนายน 2024 หากคุณใช้ FCM เดิมที่ส่ง API เราขอแนะนำอย่างยิ่งให้คุณย้ายข้อมูลไปยัง HTTP v1 API หรือพิจารณาใช้ Admin SDK เพื่อสร้างคำขอ

เอกสารนี้ให้ข้อมูลอ้างอิงสำหรับไวยากรณ์ HTTP ที่ใช้เพื่อส่งข้อความจากเซิร์ฟเวอร์แอปไปยังแอปไคลเอ็นต์ผ่าน Firebase Cloud Messaging

แอปที่ใช้ HTTP API เดิมของ FCM ควรพิจารณาย้ายข้อมูลไปยัง HTTP v1 API ดูข้อมูลเพิ่มเติมเกี่ยวกับประโยชน์ของ v1 API และวิธีการย้ายข้อมูลได้ในคำแนะนำในการย้ายข้อมูล

เมื่อใช้โปรโตคอล HTTP เดิม เซิร์ฟเวอร์แอปของคุณต้องส่งคำขอ HTTP ทั้งหมดไปยังปลายทางนี้

https://fcm.googleapis.com/fcm/send

พารามิเตอร์และตัวเลือกที่มีจะจัดอยู่ในหมวดหมู่กว้างๆ ต่อไปนี้

• ไวยากรณ์ข้อความดาวน์สตรีม
• โค้ดตอบกลับข้อผิดพลาดของข้อความดาวน์สตรีม

ไวยากรณ์ข้อความดาวน์สตรีม

ส่วนนี้จะแสดงไวยากรณ์สำหรับการส่งข้อความปลายทางและตีความการตอบกลับ HTTP จาก Firebase Cloud Messaging

ข้อความ HTTP ดาวน์สตรีม (JSON)

ตารางต่อไปนี้แสดงเป้าหมาย ตัวเลือก และเพย์โหลดสำหรับข้อความ HTTP JSON

ตาราง 1 เป้าหมาย ตัวเลือก และเพย์โหลดสำหรับข้อความ HTTP ดาวน์สตรีม (JSON)

พารามิเตอร์	การใช้งาน	คำอธิบาย
เป้าหมาย
to	สตริง (ไม่บังคับ)	พารามิเตอร์นี้จะระบุผู้รับข้อความ ค่านี้อาจเป็นโทเค็นการลงทะเบียนของอุปกรณ์ คีย์การแจ้งเตือนของกลุ่มอุปกรณ์ หรือหัวข้อเดียว (ขึ้นต้นด้วย /topics/) หากต้องการส่งไปยังหลายหัวข้อ ให้ใช้พารามิเตอร์ condition
registration_ids	อาร์เรย์ของสตริง (ไม่บังคับ)	พารามิเตอร์นี้จะระบุผู้รับข้อความมัลติแคสต์ ซึ่งเป็นข้อความที่ส่งไปยังโทเค็นการลงทะเบียนมากกว่า 1 รายการ ค่าควรเป็นอาร์เรย์ของโทเค็นการลงทะเบียนที่จะใช้ส่งข้อความมัลติแคสต์ไป อาร์เรย์ต้องมีโทเค็นการลงทะเบียนอย่างน้อย 1 รายการและไม่เกิน 1,000 รายการ หากต้องการส่งข้อความไปยังอุปกรณ์เครื่องเดียว ให้ใช้พารามิเตอร์ to อนุญาตให้ใช้ข้อความ Multicast โดยใช้รูปแบบ HTTP JSON เท่านั้น
condition	สตริง (ไม่บังคับ)	พารามิเตอร์นี้ระบุนิพจน์เชิงตรรกะของเงื่อนไขที่กำหนดเป้าหมายข้อความ เงื่อนไขที่รองรับ: หัวข้อ ซึ่งมีรูปแบบเป็น "หัวข้อของคุณ" ในหัวข้อ" โดยค่านี้ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ โอเปอเรเตอร์ที่รองรับ: &&, || รองรับโอเปอเรเตอร์สูงสุด 2 รายการต่อข้อความหัวข้อ
notification_key เลิกใช้งานแล้ว	สตริง (ไม่บังคับ)	พารามิเตอร์นี้เลิกใช้งานแล้ว แต่ให้ใช้ to เพื่อระบุผู้รับข้อความแทน ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีส่งข้อความไปยังอุปกรณ์หลายเครื่องได้ที่เอกสารประกอบสำหรับแพลตฟอร์มของคุณ
ตัวเลือก
collapse_key	สตริง (ไม่บังคับ)	พารามิเตอร์นี้จะระบุกลุ่มข้อความ (เช่น มี collapse_key: "Updates Available") ที่สามารถยุบได้ เพื่อให้ระบบส่งเฉพาะข้อความสุดท้ายเมื่อการนำส่งต่อได้ ทั้งนี้เพื่อหลีกเลี่ยงการส่งข้อความเดียวกันมากเกินไปเมื่ออุปกรณ์กลับมาออนไลน์หรือเปิดใช้งาน ทั้งนี้ เราไม่รับประกันลำดับของการส่งข้อความ หมายเหตุ: อนุญาตให้ใช้คีย์ยุบที่แตกต่างกันได้สูงสุด 4 รายการในช่วงเวลาหนึ่ง ซึ่งหมายความว่า FCM สามารถเก็บข้อความที่แตกต่างกัน 4 ข้อความต่อแอปไคลเอ็นต์ได้ในเวลาเดียวกัน หากมีจำนวนเกินนี้ เราไม่รับประกันว่าจะเก็บรักษาคีย์ยุบ 4 คีย์ที่ FCM ไว้ได้
priority	สตริง (ไม่บังคับ)	กำหนดลำดับความสำคัญของข้อความ ค่าที่ถูกต้องคือ "normal" และ "high" บนแพลตฟอร์ม Apple ค่าเหล่านี้สอดคล้องกับลำดับความสำคัญของ APN ที่ 5 และ 10 โดยค่าเริ่มต้น ระบบจะส่งข้อความแจ้งเตือนโดยมีลำดับความสำคัญสูง ส่วนข้อความข้อมูลจะส่งโดยมีลำดับความสำคัญปกติ ลำดับความสำคัญปกติจะเพิ่มประสิทธิภาพการใช้แบตเตอรี่ของแอปไคลเอ็นต์และควรใช้เว้นแต่จำเป็นต้องนำส่งทันที สำหรับข้อความที่มีลำดับความสำคัญปกติ แอปอาจได้รับข้อความที่ล่าช้าที่ไม่ระบุ เมื่อส่งข้อความที่มีลำดับความสำคัญสูง ระบบจะส่งข้อความนั้นทันทีและแอปแสดงการแจ้งเตือนได้
content_available	ไม่บังคับ บูลีน	ในแพลตฟอร์ม Apple ให้ใช้ช่องนี้เพื่อแสดง content-available ในเพย์โหลด APNs เมื่อมีการส่งการแจ้งเตือนหรือข้อความและตั้งค่าเป็น true แอปไคลเอ็นต์ที่ไม่ได้ใช้งานจะดังขึ้น และจะส่งข้อความผ่าน APN เป็นการแจ้งเตือนแบบปิดเสียง ไม่ใช่ FCM โปรดทราบว่าเราไม่รับประกันว่าการแจ้งเตือนแบบไม่มีเสียงใน APN จะแสดงและอาจขึ้นอยู่กับปัจจัยต่างๆ เช่น ผู้ใช้เปิดโหมดใช้พลังงานต่ำ การบังคับให้ปิดแอป เป็นต้น ส่วนใน Android ข้อความข้อมูลจะปลุกระบบแอปโดยค่าเริ่มต้น ขณะนี้ระบบยังไม่รองรับใน Chrome
mutable_content	ไม่บังคับ, JSON บูลีน	ในแพลตฟอร์ม Apple ให้ใช้ช่องนี้เพื่อแสดง mutable-content ในเพย์โหลด APN เมื่อส่งการแจ้งเตือนและตั้งค่าเป็น true แล้ว คุณจะแก้ไขเนื้อหาของการแจ้งเตือนก่อนที่จะแสดงได้โดยใช้ ส่วนขยายแอปบริการการแจ้งเตือน ระบบจะไม่สนใจพารามิเตอร์นี้สําหรับ Android และเว็บ
time_to_live	ไม่บังคับ หมายเลข	พารามิเตอร์นี้จะระบุระยะเวลา (เป็นวินาที) ที่ควรเก็บข้อความไว้ในพื้นที่เก็บข้อมูล FCM หากอุปกรณ์ออฟไลน์อยู่ Time to Live สูงสุดที่รองรับคือ 4 สัปดาห์และค่าเริ่มต้นคือ 4 สัปดาห์ ดูข้อมูลเพิ่มเติมได้ที่การตั้งค่าอายุการใช้งานของข้อความ
restricted_package_ name (Android เท่านั้น)	สตริง (ไม่บังคับ)	พารามิเตอร์นี้ระบุชื่อแพ็กเกจของแอปพลิเคชันที่โทเค็นการลงทะเบียนต้องตรงกันจึงจะได้รับข้อความ
dry_run	ไม่บังคับ บูลีน	เมื่อตั้งค่าเป็น true พารามิเตอร์นี้จะช่วยให้นักพัฒนาซอฟต์แวร์ทดสอบคำขอได้โดยไม่ต้องส่งข้อความจริง ค่าเริ่มต้นคือ false
เพย์โหลด
data	ไม่บังคับ ออบเจ็กต์	พารามิเตอร์นี้ระบุคู่คีย์-ค่าที่กำหนดเองของเพย์โหลดของข้อความ เช่น data:{"score":"3x1"}: ในแพลตฟอร์ม Apple หากส่งข้อความผ่าน APN ข้อความนี้จะแสดงช่องข้อมูลที่กำหนดเอง หากส่งผ่าน FCM ระบบจะแสดงเป็นพจนานุกรมคีย์-ค่าใน AppDelegate application:didReceiveRemoteNotification: ใน Android การดำเนินการนี้จะทำให้มี Intent เพิ่มเติมที่ชื่อ score ที่มีค่าสตริง 3x1 คีย์ไม่ควรเป็นคำที่สงวนไว้ ("from", "message_type" หรือคำใดๆ ที่ขึ้นต้นด้วย "google" หรือ "gcm") อย่าใช้คำที่ระบุไว้ในตารางนี้ (เช่น collapse_key) ขอแนะนำให้ใช้ค่าในประเภทสตริง คุณต้องแปลงค่าในออบเจ็กต์หรือประเภทข้อมูลที่ไม่ใช่สตริงอื่นๆ (เช่น จำนวนเต็มหรือบูลีน) เป็นสตริง
notification	ไม่บังคับ ออบเจ็กต์	พารามิเตอร์นี้ระบุคู่คีย์-ค่าที่กำหนดไว้ล่วงหน้าของเพย์โหลดการแจ้งเตือน โปรดดูรายละเอียดเกี่ยวกับการรองรับเพย์โหลดการแจ้งเตือน ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวเลือกข้อความการแจ้งเตือนและข้อความแจ้งข้อมูลได้ที่ ประเภทข้อความ หากมีเพย์โหลดการแจ้งเตือนหรือมีการตั้งค่าตัวเลือก content_available เป็น true สำหรับข้อความไปยังอุปกรณ์ Apple ระบบจะส่งผ่าน APN มิเช่นนั้นก็จะส่งผ่าน FCM

การรองรับเพย์โหลดการแจ้งเตือน

ตารางต่อไปนี้แสดงรายการคีย์ที่กำหนดไว้ล่วงหน้าซึ่งใช้สร้างข้อความแจ้งเตือนสำหรับ iOS และ Android

ตาราง 2ก. iOS — คีย์สำหรับข้อความแจ้งเตือน

พารามิเตอร์	การใช้งาน	คำอธิบาย
title	สตริง (ไม่บังคับ)	ชื่อการแจ้งเตือน ฟิลด์นี้จะไม่ปรากฏบนโทรศัพท์และแท็บเล็ต
body	สตริง (ไม่บังคับ)	ข้อความเนื้อหาของการแจ้งเตือน
sound	สตริง (ไม่บังคับ)	เสียงที่จะเล่นเมื่ออุปกรณ์ได้รับการแจ้งเตือน สตริงที่ระบุไฟล์เสียงในแพ็กเกจหลักของแอปไคลเอ็นต์หรือในโฟลเดอร์ Library/Sounds ของคอนเทนเนอร์ข้อมูลของแอป โปรดดูข้อมูลเพิ่มเติมใน ไลบรารีนักพัฒนา iOS
badge	สตริง (ไม่บังคับ)	ค่าของป้ายในไอคอนแอปหน้าจอหลัก หากไม่ระบุ ป้ายดังกล่าวจะไม่เปลี่ยนแปลง หากตั้งค่าเป็น 0 ระบบจะนำป้ายออก
click_action	สตริง (ไม่บังคับ)	การดำเนินการที่เชื่อมโยงกับผู้ใช้คลิกการแจ้งเตือน ตรงกับ category ในเพย์โหลด APNs
subtitle	สตริง (ไม่บังคับ)	คำบรรยายของการแจ้งเตือน
body_loc_key	สตริง (ไม่บังคับ)	คีย์ของสตริงเนื้อหาในทรัพยากรสตริงของแอปที่จะใช้ในการแปลเนื้อหาให้เป็นการแปลเป็นภาษาปัจจุบันของผู้ใช้ ตรงกับ loc-key ในเพย์โหลด APNs ดูข้อมูลเพิ่มเติมได้ที่ ข้อมูลอ้างอิงคีย์ของเพย์โหลดและ การแปลเนื้อหาของการแจ้งเตือนระยะไกล
body_loc_args	ไม่บังคับ อาร์เรย์ JSON เป็นสตริง	ค่าสตริงตัวแปรที่จะใช้แทนตัวระบุรูปแบบใน body_loc_key เพื่อใช้ในการแปลเนื้อหาให้เป็นการแปลปัจจุบันของผู้ใช้ ตรงกับ loc-args ในเพย์โหลด APNs ดูข้อมูลเพิ่มเติมได้ที่ ข้อมูลอ้างอิงคีย์ของเพย์โหลดและ การแปลเนื้อหาของการแจ้งเตือนระยะไกล
title_loc_key	สตริง (ไม่บังคับ)	คีย์ของสตริงชื่อในทรัพยากรสตริงของแอปเพื่อใช้ในการแปลข้อความชื่อตามการแปลเป็นภาษาปัจจุบันของผู้ใช้ ตรงกับ title-loc-key ในเพย์โหลด APNs ดูข้อมูลเพิ่มเติมได้ที่ ข้อมูลอ้างอิงคีย์ของเพย์โหลดและ การแปลเนื้อหาของการแจ้งเตือนระยะไกล
title_loc_args	ไม่บังคับ อาร์เรย์ JSON เป็นสตริง	ค่าสตริงตัวแปรที่จะใช้แทนตัวระบุรูปแบบใน title_loc_key เพื่อใช้ในการแปลข้อความชื่อตามการแปลเป็นภาษาปัจจุบันของผู้ใช้ ตรงกับ title-loc-args ในเพย์โหลด APNs ดูข้อมูลเพิ่มเติมได้ที่ ข้อมูลอ้างอิงคีย์ของเพย์โหลดและ การแปลเนื้อหาของการแจ้งเตือนระยะไกล

ตาราง 2ข. Android — กุญแจสำหรับข้อความแจ้งเตือน

พารามิเตอร์	การใช้งาน	คำอธิบาย
title	สตริง (ไม่บังคับ)	ชื่อการแจ้งเตือน
body	สตริง (ไม่บังคับ)	ข้อความเนื้อหาของการแจ้งเตือน
android_channel_id	สตริง (ไม่บังคับ)	รหัสช่องของการแจ้งเตือน (ใหม่ใน Android O) แอปต้องสร้างช่องโดยใช้รหัสช่องนี้ก่อนที่จะได้รับการแจ้งเตือนที่มีรหัสช่องนี้ หากคุณไม่ได้ส่งรหัสช่องนี้ในคำขอ หรือหากแอปยังไม่ได้สร้างรหัสช่องที่ระบุ FCM จะใช้รหัสช่องที่ระบุไว้ในไฟล์ Manifest ของแอป
icon	สตริง (ไม่บังคับ)	ไอคอนการแจ้งเตือน ตั้งค่าไอคอนการแจ้งเตือนเป็น myicon สำหรับทรัพยากรที่ถอนออกได้ myicon หากไม่ได้ส่งคีย์นี้ในคำขอ FCM จะแสดงไอคอน Launcher ที่ระบุไว้ในไฟล์ Manifest ของแอป
sound	สตริง (ไม่บังคับ)	เสียงที่จะเล่นเมื่ออุปกรณ์ได้รับการแจ้งเตือน รองรับ "default" หรือชื่อไฟล์ของทรัพยากรเสียงที่รวมอยู่ในแอป โดยไฟล์เสียงต้องอยู่ใน /res/raw/
tag	สตริง (ไม่บังคับ)	ตัวระบุที่ใช้แทนที่การแจ้งเตือนที่มีอยู่ในลิ้นชักการแจ้งเตือน หากไม่ระบุ คำขอแต่ละรายการจะสร้างการแจ้งเตือนใหม่ หากมีการระบุและการแจ้งเตือนที่มีแท็กเดียวกันอยู่แล้ว การแจ้งเตือนใหม่จะแทนที่การแจ้งเตือนที่มีอยู่ในลิ้นชักการแจ้งเตือน
color	สตริง (ไม่บังคับ)	สีไอคอนของการแจ้งเตือน ซึ่งแสดงในรูปแบบ #rrggbb
click_action	สตริง (ไม่บังคับ)	การดำเนินการที่เชื่อมโยงกับผู้ใช้คลิกการแจ้งเตือน หากระบุ ระบบจะเปิดใช้งานกิจกรรมที่มีตัวกรอง Intent ตรงกันเมื่อผู้ใช้คลิกการแจ้งเตือน
body_loc_key	สตริง (ไม่บังคับ)	คีย์ของสตริงเนื้อหาในทรัพยากรสตริงของแอปที่จะใช้ในการแปลเนื้อหาให้เป็นการแปลเป็นภาษาปัจจุบันของผู้ใช้ ดูข้อมูลเพิ่มเติมได้ที่ ทรัพยากรสตริง
body_loc_args	ไม่บังคับ อาร์เรย์ JSON เป็นสตริง	ค่าสตริงตัวแปรที่จะใช้แทนตัวระบุรูปแบบใน body_loc_key เพื่อใช้ในการแปลเนื้อหาให้เป็นการแปลปัจจุบันของผู้ใช้ ดูข้อมูลเพิ่มเติมได้ที่ การจัดรูปแบบและการจัดรูปแบบ
title_loc_key	สตริง (ไม่บังคับ)	คีย์ของสตริงชื่อในทรัพยากรสตริงของแอปเพื่อใช้ในการแปลข้อความชื่อตามการแปลเป็นภาษาปัจจุบันของผู้ใช้ ดูข้อมูลเพิ่มเติมได้ที่ ทรัพยากรสตริง
title_loc_args	ไม่บังคับ อาร์เรย์ JSON เป็นสตริง	ค่าสตริงตัวแปรที่จะใช้แทนตัวระบุรูปแบบใน title_loc_key เพื่อใช้ในการแปลข้อความชื่อตามการแปลเป็นภาษาปัจจุบันของผู้ใช้ ดูข้อมูลเพิ่มเติมได้ที่ การจัดรูปแบบและการจัดรูปแบบ

ตาราง 2ค เว็บ (JavaScript) — คีย์สำหรับข้อความแจ้งเตือน

พารามิเตอร์	การใช้งาน	คำอธิบาย
title	สตริง (ไม่บังคับ)	ชื่อการแจ้งเตือน
body	สตริง (ไม่บังคับ)	ข้อความเนื้อหาของการแจ้งเตือน
icon	สตริง (ไม่บังคับ)	URL ที่ใช้สำหรับไอคอนการแจ้งเตือน
click_action	สตริง (ไม่บังคับ)	การดำเนินการที่เชื่อมโยงกับผู้ใช้คลิกการแจ้งเตือน ค่า URL ทั้งหมดต้องใช้ HTTPS

ข้อความ HTTP ดาวน์สตรีม (ข้อความธรรมดา)

ตารางต่อไปนี้แสดงรายการไวยากรณ์สำหรับเป้าหมาย ตัวเลือก และเพย์โหลดในข้อความ HTTP ดาวน์สตรีมที่เป็นข้อความธรรมดา

ตารางที่ 3 เป้าหมาย ตัวเลือก และเพย์โหลดสำหรับข้อความ HTTP แบบข้อความธรรมดาปลายทาง

พารามิเตอร์	การใช้งาน	คำอธิบาย
เป้าหมาย
registration_id	ต้องระบุ สตริง	พารามิเตอร์นี้ระบุแอปไคลเอ็นต์ (โทเค็นการลงทะเบียน) ที่ได้รับข้อความ อนุญาตการรับส่งข้อความ Multicast (การส่งไปยังโทเค็นการลงทะเบียนมากกว่า 1 รายการ) โดยใช้รูปแบบ HTTP JSON เท่านั้น
ตัวเลือก
collapse_key	สตริง (ไม่บังคับ)	ดูรายละเอียดในตาราง 1
time_to_live	ไม่บังคับ หมายเลข	ดูรายละเอียดในตาราง 1
restricted_package_name	สตริง (ไม่บังคับ)	ดูรายละเอียดในตาราง 1
dry_run	ไม่บังคับ บูลีน	ดูรายละเอียดในตาราง 1
เพย์โหลด
data.<key>	สตริง (ไม่บังคับ)	พารามิเตอร์นี้ระบุคู่คีย์-ค่าสำหรับเพย์โหลดของข้อความ ไม่มีการจำกัดจำนวนพารามิเตอร์คีย์-ค่า แต่มีการจำกัดขนาดข้อความทั้งหมดไว้ที่ 4,096 ไบต์ ตัวอย่างเช่น ใน Android "data.score"."3x1" จะทำให้มี Intent มีชื่อพิเศษว่า score ด้วยค่าสตริง 3x1 คีย์ไม่ควรเป็นคำที่สงวนไว้ ("from", "message_type" หรือคำใดๆ ที่ขึ้นต้นด้วย "google" หรือ "gcm") อย่าใช้คำที่ระบุไว้ในตารางนี้ (เช่น collapse_key)

การแปลการตอบกลับข้อความดาวน์สตรีม

เซิร์ฟเวอร์แอปควรประเมินทั้งส่วนหัวและเนื้อความของข้อความเพื่อตีความการตอบกลับข้อความที่ส่งจาก FCM ตารางต่อไปนี้อธิบาย คำตอบที่เป็นไปได้

ตาราง 4 ส่วนหัวการตอบกลับข้อความ HTTP ดาวน์สตรีม

คำตอบ	คำอธิบาย
200	ประมวลผลข้อความเรียบร้อยแล้ว เนื้อหาการตอบกลับจะมีรายละเอียดเพิ่มเติมเกี่ยวกับสถานะข้อความ แต่รูปแบบของคำขอจะขึ้นอยู่กับว่าคำขอเป็น JSON หรือข้อความธรรมดา ดูรายละเอียดเพิ่มเติมในตาราง 5
400	ใช้กับคำขอ JSON เท่านั้น บ่งบอกว่าคำขอแยกวิเคราะห์เป็น JSON ไม่ได้ หรือมีช่องที่ไม่ถูกต้อง (เช่น การส่งสตริงที่คาดไว้ตัวเลข) สาเหตุที่แน่นอนคือมีการระบุในคำตอบ และควรแก้ไขปัญหาก่อนจึงจะส่งคำขออีกครั้งได้
401	เกิดข้อผิดพลาดในการตรวจสอบสิทธิ์บัญชีผู้ส่ง
5xx	ข้อผิดพลาดในช่วง 500-599 (เช่น 500 หรือ 503) ระบุว่ามีข้อผิดพลาดภายในในแบ็กเอนด์ FCM ขณะพยายามประมวลผลคำขอ หรือเซิร์ฟเวอร์ไม่พร้อมใช้งานชั่วคราว (เช่น เนื่องจากหมดเวลา) ผู้ส่งต้องลองอีกครั้งในภายหลัง โดยใช้ส่วนหัว Retry-After ที่รวมอยู่ในการตอบกลับ แอปพลิเคชันเซิร์ฟเวอร์ต้องใช้ Exponential Backoff

ตารางต่อไปนี้แสดงช่องในเนื้อหาการตอบกลับข้อความดาวน์สตรีม (JSON)

ตาราง 5 เนื้อหาการตอบกลับข้อความ HTTP ดาวน์สตรีม (JSON)

พารามิเตอร์	การใช้งาน	คำอธิบาย
multicast_id	ต้องระบุ หมายเลข	รหัสที่ไม่ซ้ำกัน (ตัวเลข) ที่ระบุข้อความมัลติแคสต์
success	ต้องระบุ หมายเลข	จำนวนข้อความที่ประมวลผลโดยไม่มีข้อผิดพลาด
failure	ต้องระบุ หมายเลข	จำนวนข้อความที่ประมวลผลไม่ได้
results	ต้องระบุ อาร์เรย์ของออบเจ็กต์	อาร์เรย์ของออบเจ็กต์ที่แทนสถานะของข้อความที่ประมวลผล ออบเจ็กต์แสดงในลำดับเดียวกับคำขอ (กล่าวคือ สำหรับรหัสการลงทะเบียนแต่ละรายการในคำขอ ผลลัพธ์จะแสดงในดัชนีเดียวกันในการตอบกลับ) message_id: สตริงที่ระบุรหัสที่ไม่ซ้ำกันสำหรับแต่ละข้อความที่ประมวลผลสำเร็จ error: สตริงระบุข้อผิดพลาดที่เกิดขึ้นเมื่อประมวลผลข้อความสำหรับผู้รับ ดูค่าที่เป็นไปได้ได้ในตาราง 9

ตาราง 6 เนื้อหาการตอบกลับ HTTP ของข้อความหัวข้อ (JSON)

พารามิเตอร์	การใช้งาน	คำอธิบาย
message_id	ไม่บังคับ หมายเลข	รหัสข้อความหัวข้อเมื่อ FCM ได้รับคำขอเรียบร้อยแล้วและจะพยายามส่งไปยังอุปกรณ์ที่สมัครใช้บริการทั้งหมด
error	สตริง (ไม่บังคับ)	เกิดข้อผิดพลาดขณะประมวลผลข้อความ ดูค่าที่เป็นไปได้ได้ในตาราง 9

ตารางที่ 7 การตอบกลับที่สำเร็จสำหรับเนื้อหาการตอบกลับข้อความ HTTP ดาวน์สตรีม (ข้อความธรรมดา)

พารามิเตอร์	การใช้งาน	คำอธิบาย
id	ต้องระบุ สตริง	พารามิเตอร์นี้ระบุรหัสข้อความที่ไม่ซ้ำกันที่ FCM ประมวลผลเรียบร้อยแล้ว
registration_id	สตริง (ไม่บังคับ)	พารามิเตอร์นี้ระบุโทเค็นการลงทะเบียนสำหรับแอปไคลเอ็นต์ที่มีการประมวลผลและส่งข้อความถึงแอป

ตารางที่ 8 การตอบกลับข้อผิดพลาดสำหรับเนื้อหาการตอบกลับข้อความ HTTP ดาวน์สตรีม (ข้อความธรรมดา)

พารามิเตอร์	การใช้งาน	คำอธิบาย
Error	ต้องระบุ สตริง	พารามิเตอร์นี้ระบุค่าข้อผิดพลาดขณะประมวลผลข้อความสำหรับผู้รับ ดูรายละเอียดได้ในตาราง 9

โค้ดตอบกลับข้อผิดพลาดของข้อความดาวน์สตรีม

ตารางต่อไปนี้แสดงโค้ดตอบกลับของข้อผิดพลาดสำหรับข้อความดาวน์สตรีม

ตาราง 9 รหัสการตอบกลับข้อผิดพลาดของข้อความดาวน์สตรีม

ข้อผิดพลาด	รหัส HTTP	การดำเนินการที่แนะนำ
ไม่มีโทเค็นการลงทะเบียน	200 + ข้อผิดพลาด:MissingRegistration	ตรวจสอบว่าคำขอมีโทเค็นการลงทะเบียน (ใน registration_id ในข้อความธรรมดา หรือในช่อง to หรือ registration_ids ใน JSON)
โทเค็นการลงทะเบียนไม่ถูกต้อง	200 + ข้อผิดพลาด:รหัสการลงทะเบียนไม่ถูกต้อง	ตรวจสอบรูปแบบของโทเค็นการลงทะเบียนที่คุณส่งไปยังเซิร์ฟเวอร์ ตรวจสอบว่าโทเค็นดังกล่าวตรงกับโทเค็นการลงทะเบียนที่แอปไคลเอ็นต์ได้รับจากการลงทะเบียนด้วยการแจ้งเตือนของ Firebase อย่าตัดหรือเพิ่มอักขระอื่น
อุปกรณ์ที่ไม่ได้ลงทะเบียน	200 + ข้อผิดพลาด:Notregistereded	โทเค็นการลงทะเบียนที่มีอยู่อาจใช้ไม่ได้ในบางสถานการณ์ ดังนี้ หากแอปไคลเอ็นต์ยกเลิกการลงทะเบียนกับ FCM ในกรณีที่แอปไคลเอ็นต์ยกเลิกการลงทะเบียนโดยอัตโนมัติ ซึ่งเกิดขึ้นได้หากผู้ใช้ถอนการติดตั้งแอปพลิเคชัน เช่น ใน iOS หากบริการฟีดแบ็ก APN รายงานว่าโทเค็น APN ไม่ถูกต้อง หากโทเค็นการลงทะเบียนหมดอายุ (เช่น Google อาจตัดสินใจรีเฟรชโทเค็นการลงทะเบียน หรือโทเค็น APN สําหรับอุปกรณ์ iOS หมดอายุ) หากอัปเดตแอปไคลเอ็นต์แล้ว แต่ไม่ได้กำหนดค่าเวอร์ชันใหม่ให้รับข้อความ สำหรับทุกกรณี ให้นำโทเค็นการลงทะเบียนนี้ออกจากเซิร์ฟเวอร์แอปและหยุดใช้โทเค็นดังกล่าวเพื่อส่งข้อความ
ชื่อแพ็กเกจไม่ถูกต้อง	200 + ข้อผิดพลาด:InvalidPackageName	ตรวจสอบว่าข้อความนั้นส่งถึงโทเค็นการลงทะเบียนที่มีชื่อแพ็กเกจตรงกับค่าที่ส่งไปในคำขอ
ข้อผิดพลาดในการตรวจสอบสิทธิ์	401	ไม่สามารถตรวจสอบสิทธิ์บัญชีผู้ส่งที่ใช้ส่งข้อความ สาเหตุที่เป็นไปได้มีดังนี้ ไม่มีส่วนหัวการให้สิทธิ์หรือมีไวยากรณ์ที่ไม่ถูกต้องในคำขอ HTTP โปรเจ็กต์ Firebase ที่มีคีย์เซิร์ฟเวอร์ที่ระบุไม่ถูกต้อง เฉพาะคีย์เซิร์ฟเวอร์เดิมเท่านั้น ซึ่งเป็นคำขอที่มาจากเซิร์ฟเวอร์ที่ไม่ได้อยู่ในรายการที่อนุญาตพิเศษใน IP ของคีย์เซิร์ฟเวอร์ ตรวจสอบว่าโทเค็นที่คุณส่งภายในส่วนหัวการตรวจสอบสิทธิ์เป็นคีย์เซิร์ฟเวอร์ที่ถูกต้องซึ่งเชื่อมโยงกับโปรเจ็กต์ของคุณ ดูรายละเอียดในการตรวจสอบความถูกต้องของคีย์เซิร์ฟเวอร์ หากคุณใช้คีย์เซิร์ฟเวอร์เดิม เราขอแนะนำให้อัปเกรดเป็นคีย์ใหม่ที่ไม่มีข้อจำกัด IP โปรดดูหัวข้อ ย้ายข้อมูลคีย์เซิร์ฟเวอร์เดิม
ผู้ส่งไม่ตรงกัน	200 + ข้อผิดพลาด:MismatchSenderId	โทเค็นการลงทะเบียนจะผูกกับกลุ่มผู้ส่งบางกลุ่ม เมื่อแอปไคลเอ็นต์ลงทะเบียนสำหรับ FCM แอปต้องระบุผู้ส่งที่ได้รับอนุญาตให้ส่งข้อความ คุณควรใช้รหัสผู้ส่งรหัสใดรหัสหนึ่งเมื่อส่งข้อความไปยังแอปไคลเอ็นต์ หากเปลี่ยนไปใช้ผู้ส่งรายอื่น โทเค็นการลงทะเบียนที่มีอยู่จะไม่ทำงาน
JSON ไม่ถูกต้อง	400	ตรวจสอบว่าข้อความ JSON อยู่ในรูปแบบที่ถูกต้องและมีช่องที่ถูกต้อง (เช่น ตรวจสอบว่ามีการส่งผ่านประเภทข้อมูลที่ถูกต้อง)
พารามิเตอร์ไม่ถูกต้อง	400 + ข้อผิดพลาด:invalidParameters	ตรวจสอบว่าพารามิเตอร์ที่ระบุมีชื่อและประเภทที่ถูกต้อง
ข้อความมีขนาดใหญ่เกินไป	200 + ข้อผิดพลาด:MessageTooBig	ตรวจสอบว่าขนาดข้อมูลเพย์โหลดโดยรวมในข้อความไม่เกินขีดจำกัด FCM นั่นคือ 4, 096 ไบต์สำหรับข้อความส่วนใหญ่ หรือ 2048 ไบต์ในกรณีที่ส่งข้อความถึงหัวข้อ ซึ่งจะมีทั้งคีย์และค่า
คีย์ข้อมูลไม่ถูกต้อง	200 + ข้อผิดพลาด: InvalidDataKey	ตรวจสอบว่าข้อมูลเพย์โหลดไม่มีคีย์ (เช่น from หรือ gcm หรือค่าใดๆ ที่มีคำนำหน้าเป็น google) ที่ FCM ใช้ภายใน โปรดทราบว่า FCM ก็ใช้คำบางคำ (เช่น collapse_key) ด้วยเช่นกัน แต่ใช้ในเพย์โหลดได้ ซึ่งในกรณีนี้ ค่า FCM จะลบล้างค่าเพย์โหลด
Time to Live ไม่ถูกต้อง	200 + ข้อผิดพลาด:invalidTtl	ตรวจสอบว่าค่าที่ใช้ใน time_to_live เป็นจำนวนเต็มที่แสดงระยะเวลาเป็นวินาทีระหว่าง 0 ถึง 2,419,200 (4 สัปดาห์)
ระยะหมดเวลา	5xx หรือ 200 + ข้อผิดพลาด:ไม่พร้อมใช้งาน	เซิร์ฟเวอร์ประมวลผลคำขอได้ไม่ทันเวลา ลองส่งคำขอเดิมอีกครั้ง แต่คุณต้องทำดังนี้ ทำตามส่วนหัว Retry-After หากรวมอยู่ในการตอบกลับจากเซิร์ฟเวอร์การเชื่อมต่อ FCM ใช้ Exponential Backoff ในกลไกการลองใหม่ (เช่น หากคุณรอ 1 วินาทีก่อนการลองครั้งแรกครั้งแรก ให้รออย่างน้อย 2 วินาทีก่อนเกมถัดไป จากนั้น 4 วินาที แล้วทำแบบนี้ไปเรื่อยๆ) หากส่งหลายข้อความ ให้หน่วงเวลาแต่ละข้อความแยกกันโดยการสุ่มเพิ่มเพื่อหลีกเลี่ยงการส่งคำขอใหม่สำหรับข้อความทั้งหมดในเวลาเดียวกัน ผู้ส่งที่ทำให้เกิดปัญหาเสี่ยงต่อการถูกขึ้นบัญชีดำ
ข้อผิดพลาดภายในเซิร์ฟเวอร์	500 หรือ 200 + ข้อผิดพลาด:InternalServerError	เซิร์ฟเวอร์พบข้อผิดพลาดขณะพยายามประมวลผลคำขอ คุณสามารถลองส่งคำขอเดิมอีกครั้งโดยทำตามข้อกำหนดที่ระบุไว้ใน "ระยะหมดเวลา" (ดูแถวด้านบน) หากข้อผิดพลาดยังคงอยู่ โปรดติดต่อทีมสนับสนุน Firebase
เกินอัตราข้อความในอุปกรณ์	200 + ข้อผิดพลาด: DeviceMessageRate เกิน	อัตราการส่งข้อความไปยังอุปกรณ์เครื่องใดเครื่องหนึ่งสูงเกินไป หากแอป Apple ส่งข้อความในอัตราเกินขีดจำกัดของ APN แอปอาจได้รับข้อความแสดงข้อผิดพลาดนี้ ลดจำนวนข้อความที่ส่งไปยังอุปกรณ์นี้และ ใช้ Backoff Exponential เพื่อลองส่งอีกครั้ง
เกินอัตราข้อความของหัวข้อ	200 + ข้อผิดพลาด: TopicsMessageRate เกิน	อัตราการส่งข้อความไปยังผู้ติดตามในหัวข้อใดหัวข้อหนึ่งสูงเกินไป ลดจำนวนข้อความที่ส่งสำหรับหัวข้อนี้และใช้ Exponential เพื่อลองส่งอีกครั้ง
ข้อมูลเข้าสู่ระบบ APN ไม่ถูกต้อง	200 + ข้อผิดพลาด: PermissionsApnsCredential	ส่งข้อความที่กำหนดเป้าหมายไปยังอุปกรณ์ Apple ไม่ได้เนื่องจากคีย์การตรวจสอบสิทธิ์ APN ที่จำเป็นยังไม่ได้อัปโหลดหรือหมดอายุแล้ว ตรวจสอบความถูกต้องของข้อมูลเข้าสู่ระบบสำหรับการพัฒนาและเวอร์ชันที่ใช้งานจริง

การจัดการกลุ่มอุปกรณ์

ตารางต่อไปนี้แสดงรายการคีย์สำหรับการสร้างกลุ่มอุปกรณ์ รวมถึงการเพิ่มและนำสมาชิกออก ดูข้อมูลเพิ่มเติมได้ในคำแนะนำสำหรับแพลตฟอร์ม, iOS+ หรือ Android

ตารางที่ 10 คีย์การจัดการกลุ่มอุปกรณ์

พารามิเตอร์	การใช้งาน	คำอธิบาย
operation	ต้องระบุ สตริง	การดำเนินการที่จะเรียกใช้ ค่าที่ถูกต้องคือ create, add และ remove
notification_key_name	ต้องระบุ สตริง	ชื่อที่ผู้ใช้กำหนดของกลุ่มอุปกรณ์ที่จะสร้างหรือแก้ไข
notification_key	ต้องระบุ (ยกเว้นการดำเนินการ create, สตริง	ตัวระบุที่ไม่ซ้ำกันของกลุ่มอุปกรณ์ ระบบจะแสดงค่านี้ในการตอบกลับสำหรับการดำเนินการ create ที่สำเร็จ และค่านี้จำเป็นสำหรับการดำเนินการครั้งต่อๆ ไปทั้งหมดในกลุ่มอุปกรณ์
registration_ids	ต้องระบุ อาร์เรย์ของสตริง	โทเค็นของอุปกรณ์ที่จะเพิ่มหรือนำออก หากคุณนำโทเค็นการลงทะเบียนที่มีอยู่ทั้งหมดออกจากกลุ่มอุปกรณ์ FCM จะลบกลุ่มอุปกรณ์นั้น