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

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

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

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

เมื่อใช้โปรโตคอล 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 อนุญาตให้ใช้ข้อความมัลติแคสต์โดยใช้รูปแบบ HTTP JSON เท่านั้น
condition	สตริง (ไม่บังคับ)	พารามิเตอร์นี้จะระบุนิพจน์เชิงตรรกะของเงื่อนไขที่กำหนดเป้าหมายของข้อความ เงื่อนไขที่รองรับ: หัวข้อในรูปแบบ "หัวข้อของคุณ" ในหัวข้อ" ค่านี้ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ โอเปอเรเตอร์ที่รองรับ: &&, || รองรับโอเปอเรเตอร์สูงสุด 2 รายการต่อข้อความหัวข้อ
notification_key เลิกใช้งานแล้ว	สตริง (ไม่บังคับ)	พารามิเตอร์นี้เลิกใช้งานแล้ว โปรดใช้ to เพื่อระบุผู้รับข้อความแทน ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีส่งข้อความไปยังอุปกรณ์หลายเครื่องได้ในเอกสารประกอบของแพลตฟอร์มที่คุณใช้
ตัวเลือก
collapse_key	สตริง (ไม่บังคับ)	พารามิเตอร์นี้จะระบุกลุ่มข้อความ (เช่น collapse_key: "Updates Available") ที่สามารถยุบได้ เพื่อให้ระบบส่งเฉพาะข้อความสุดท้ายเมื่อทำให้การนำส่งกลับมาทำงานอีกครั้ง ทั้งนี้เพื่อหลีกเลี่ยงการส่งข้อความเดิมมากเกินไปเมื่ออุปกรณ์กลับมาออนไลน์หรือมีการใช้งานอยู่ โปรดทราบว่าไม่สามารถรับประกันลำดับการส่งข้อความได้ หมายเหตุ: อนุญาตให้มีคีย์ยุบที่แตกต่างกันได้สูงสุด 4 คีย์ในช่วงเวลาที่กำหนด ซึ่งหมายความว่า FCM สามารถจัดเก็บข้อความที่แตกต่างกัน 4 ข้อความต่อแอปไคลเอ็นต์ได้พร้อมกัน หากมีเกินจำนวนสูงสุดนี้ เราไม่รับประกันว่าคีย์ยุบ 4 คีย์ที่ FCM จะเก็บไว้ได้
priority	สตริง (ไม่บังคับ)	ตั้งค่าลำดับความสำคัญของข้อความ ค่าที่ถูกต้องคือ "ปกติ" และ "สูง" ในแพลตฟอร์ม Apple ทั้งหมดนี้ จะสอดคล้องกับลำดับความสำคัญ APN 5 และ 10 โดยค่าเริ่มต้น ระบบจะส่งข้อความแจ้งเตือนที่มีลำดับความสำคัญสูง และข้อความข้อมูลจะส่งโดยมีลำดับความสำคัญปกติ ลำดับความสำคัญปกติจะเพิ่มประสิทธิภาพการใช้แบตเตอรี่ของแอปไคลเอ็นต์ และควรใช้เว้นแต่จะต้องนำส่งทันที สำหรับข้อความที่มีลำดับความสำคัญปกติ แอปอาจได้รับข้อความล่าช้าโดยไม่ได้ระบุ เมื่อมีการส่งข้อความที่มีลำดับความสำคัญสูง ระบบจะส่งข้อความนั้นทันทีและแอปจะแสดงการแจ้งเตือนได้
content_available	ไม่บังคับ บูลีน	บนแพลตฟอร์ม Apple ให้ใช้ช่องนี้เพื่อแสดง content-available ในเพย์โหลด APN เมื่อมีการส่งการแจ้งเตือนหรือข้อความและตั้งค่าเป็น 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 ในเพย์โหลด APN
subtitle	สตริง (ไม่บังคับ)	คำบรรยายของการแจ้งเตือน
body_loc_key	สตริง (ไม่บังคับ)	คีย์ไปยังสตริงเนื้อหาในทรัพยากรสตริงของแอปเพื่อใช้ในการปรับข้อความเนื้อหาให้เข้ากับการแปลในปัจจุบันของผู้ใช้ สอดคล้องกับ loc-key ในเพย์โหลด APN ดูข้อมูลเพิ่มเติมได้ที่ การอ้างอิงคีย์เพย์โหลดและ การแปลเนื้อหาของการแจ้งเตือนระยะไกล
body_loc_args	(ไม่บังคับ) มีอาร์เรย์ JSON เป็นสตริง	ค่าสตริงตัวแปรที่จะใช้แทนตัวระบุรูปแบบใน body_loc_key เพื่อใช้ในการแปลเนื้อหาตามการแปลเป็นภาษาปัจจุบันของผู้ใช้ สอดคล้องกับ loc-args ในเพย์โหลด APN ดูข้อมูลเพิ่มเติมได้ที่ การอ้างอิงคีย์เพย์โหลดและ การแปลเนื้อหาของการแจ้งเตือนระยะไกล
title_loc_key	สตริง (ไม่บังคับ)	คีย์สำหรับสตริงชื่อในทรัพยากรสตริงของแอปเพื่อใช้ในการแปลข้อความชื่อตามการแปลปัจจุบันของผู้ใช้ สอดคล้องกับ title-loc-key ในเพย์โหลด APN ดูข้อมูลเพิ่มเติมได้ที่ การอ้างอิงคีย์เพย์โหลดและ การแปลเนื้อหาของการแจ้งเตือนระยะไกล
title_loc_args	(ไม่บังคับ) มีอาร์เรย์ JSON เป็นสตริง	ค่าสตริงตัวแปรที่จะใช้แทนตัวระบุรูปแบบใน title_loc_key เพื่อใช้ในการแปลข้อความชื่อให้เป็นภาษาปัจจุบันของผู้ใช้ สอดคล้องกับ title-loc-args ในเพย์โหลด APN ดูข้อมูลเพิ่มเติมได้ที่ การอ้างอิงคีย์เพย์โหลดและ การแปลเนื้อหาของการแจ้งเตือนระยะไกล

ตารางที่ 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	ต้องระบุ สตริง	พารามิเตอร์นี้ระบุแอปไคลเอ็นต์ (โทเค็นการลงทะเบียน) ที่ได้รับข้อความ อนุญาตให้ส่งข้อความมัลติแคสต์ (ส่งไปยังโทเค็นการลงทะเบียนมากกว่า 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 + ข้อผิดพลาด:ไม่มีการลงทะเบียน	ตรวจสอบว่าคำขอมีโทเค็นการลงทะเบียน (ใน registration_id เป็นข้อความธรรมดา หรือในช่อง to หรือ registration_ids ใน JSON)
โทเค็นการลงทะเบียนไม่ถูกต้อง	200 + ข้อผิดพลาด:รหัสการลงทะเบียนไม่ถูกต้อง	ตรวจสอบรูปแบบของโทเค็นการลงทะเบียนที่คุณส่งไปยังเซิร์ฟเวอร์ ตรวจสอบว่ารหัสตรงกับโทเค็นการลงทะเบียนที่แอปไคลเอ็นต์ได้รับจากการลงทะเบียนด้วยการแจ้งเตือนของ Firebase อย่าตัดหรือเพิ่มอักขระอีก
อุปกรณ์ที่ไม่ได้ลงทะเบียน	200 + ข้อผิดพลาด:ไม่ได้ลงทะเบียน	โทเค็นการลงทะเบียนที่มีอยู่อาจใช้งานไม่ได้ในบางสถานการณ์ เช่น หากแอปไคลเอ็นต์ยกเลิกการลงทะเบียนกับ FCM หากแอปไคลเอ็นต์ถูกยกเลิกการลงทะเบียนโดยอัตโนมัติ ซึ่งอาจเกิดขึ้นได้หากผู้ใช้ถอนการติดตั้งแอปไคลเอ็นต์ เช่น ใน iOS หากบริการความคิดเห็น APNs รายงานว่าโทเค็น APN ไม่ถูกต้อง หากโทเค็นการลงทะเบียนหมดอายุ (เช่น Google อาจตัดสินใจรีเฟรชโทเค็นการลงทะเบียน หรือโทเค็น APN หมดอายุสำหรับอุปกรณ์ iOS) หากมีการอัปเดตแอปไคลเอ็นต์ แต่เวอร์ชันใหม่ไม่ได้รับการกำหนดค่าให้รับข้อความ สำหรับทุกกรณีเหล่านี้ ให้นำโทเค็นการลงทะเบียนนี้ออกจากเซิร์ฟเวอร์แอปและหยุดใช้โทเค็นเพื่อส่งข้อความ
ชื่อแพ็กเกจไม่ถูกต้อง	200 + ข้อผิดพลาด:invalidPackageName	ตรวจสอบว่าข้อความส่งถึงโทเค็นการลงทะเบียนที่ชื่อแพ็กเกจตรงกับค่าที่ส่งในคำขอ
ข้อผิดพลาดในการตรวจสอบสิทธิ์	401	ตรวจสอบสิทธิ์บัญชีผู้ส่งที่ใช้ส่งข้อความไม่ได้ โดยสาเหตุที่เป็นไปได้มีดังนี้ ไม่มีส่วนหัวการให้สิทธิ์หรือมีไวยากรณ์ที่ไม่ถูกต้องในคำขอ HTTP โปรเจ็กต์ Firebase ที่มีคีย์เซิร์ฟเวอร์ที่ระบุไม่ถูกต้อง คีย์เซิร์ฟเวอร์เดิมเท่านั้น - คำขอมาจากเซิร์ฟเวอร์ที่ไม่อยู่ในรายการ IP ของคีย์เซิร์ฟเวอร์ที่อนุญาตพิเศษ ตรวจสอบว่าโทเค็นที่ส่งภายในส่วนหัวการตรวจสอบสิทธิ์เป็นคีย์เซิร์ฟเวอร์ที่ถูกต้องซึ่งเชื่อมโยงกับโปรเจ็กต์ ดูรายละเอียดได้ที่การตรวจสอบความถูกต้องของคีย์เซิร์ฟเวอร์ หากใช้คีย์เซิร์ฟเวอร์เดิม เราขอแนะนำให้อัปเกรดเป็นคีย์ใหม่ที่ไม่มีข้อจำกัด IP โปรดดูหัวข้อ ย้ายข้อมูลคีย์เซิร์ฟเวอร์เดิม
ผู้ส่งไม่ตรงกัน	200 ขึ้นไป ข้อผิดพลาด:MismatchSenderId	โทเค็นการลงทะเบียนจะเชื่อมโยงกับกลุ่มผู้ส่งบางกลุ่ม เมื่อแอปไคลเอ็นต์ลงทะเบียนสำหรับ FCM แอปต้องระบุผู้ส่งที่ได้รับอนุญาตให้ส่งข้อความ คุณควรใช้รหัสผู้ส่งอย่างใดอย่างหนึ่งเมื่อส่งข้อความไปยังแอปไคลเอ็นต์ หากเปลี่ยนเป็นผู้ส่งรายอื่น โทเค็นการลงทะเบียนที่มีอยู่จะไม่ทำงาน
JSON ไม่ถูกต้อง	400	ตรวจสอบว่าข้อความ JSON ได้รับการจัดรูปแบบอย่างถูกต้องและมีช่องที่ถูกต้อง (เช่น ตรวจสอบว่ามีการส่งประเภทข้อมูลที่ถูกต้อง)
พารามิเตอร์ไม่ถูกต้อง	400 + ข้อผิดพลาด:validParameters	ตรวจสอบว่าพารามิเตอร์ที่ระบุมีชื่อและประเภทที่ถูกต้อง
ข้อความมีขนาดใหญ่เกินไป	200 + ข้อผิดพลาด:ข้อความขนาดใหญ่เกินไป	ตรวจสอบว่าขนาดรวมของข้อมูลเพย์โหลดที่รวมอยู่ในข้อความไม่เกินขีดจำกัด FCM: 4096 ไบต์สำหรับข้อความส่วนใหญ่ หรือ 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 วินาทีก่อนถึงอีก 1 วินาที จากนั้นให้รออย่างน้อย 4 วินาที และเรียงตามลำดับไปเรื่อยๆ) หากคุณส่งข้อความจำนวนมาก ให้หน่วงเวลาแต่ละข้อความไว้อย่างเป็นอิสระต่อกันด้วยจำนวนเงินที่สุ่มเพิ่ม เพื่อหลีกเลี่ยงการส่งคำขอใหม่สำหรับข้อความทั้งหมดพร้อมกัน ผู้ส่งที่ทำให้เกิดปัญหาจะเสี่ยงต่อการถูกขึ้นบัญชีดำ
เซิร์ฟเวอร์เกิดข้อผิดพลาดภายใน	ข้อผิดพลาด 500 หรือ 200 +:InternalServerError	เซิร์ฟเวอร์พบข้อผิดพลาดขณะพยายามประมวลผลคำขอ คุณสามารถลองส่งคำขอเดิมอีกครั้งโดยทำตามข้อกำหนดที่ระบุไว้ใน "หมดเวลา" (ดูแถวด้านบน) หากข้อผิดพลาดยังคงอยู่ โปรดติดต่อทีมสนับสนุน Firebase
เกินอัตราข้อความของอุปกรณ์แล้ว	200 + ข้อผิดพลาด: DeviceMessageRate เกิน	อัตราการส่งข้อความไปยังอุปกรณ์ใดอุปกรณ์หนึ่งสูงเกินไป หากแอป Apple ส่งข้อความในอัตราที่เกินขีดจำกัด APN แอปอาจได้รับข้อความแสดงข้อผิดพลาดนี้ ลดจำนวนข้อความที่ส่งไปยังอุปกรณ์นี้และใช้ Exponential Backoff เพื่อลองส่งอีกครั้ง
อัตราข้อความในหัวข้อเกินขีดจำกัดแล้ว	200 + ข้อผิดพลาด: TopicsMessageRate เกิน	อัตราข้อความที่ส่งไปยังสมาชิกของหัวข้อใดหัวข้อหนึ่งสูงเกินไป ลดจำนวนข้อความที่ส่งสำหรับหัวข้อนี้และใช้ Exponential Backoff เพื่อลองส่งอีกครั้ง
ข้อมูลเข้าสู่ระบบ APN ไม่ถูกต้อง	200+ ข้อผิดพลาด: InvalidApnsCredential	ส่งข้อความที่กำหนดเป้าหมายไปยังอุปกรณ์ Apple ไม่ได้เนื่องจากไม่ได้อัปโหลดคีย์การตรวจสอบสิทธิ์ APN ที่จำเป็นหรือคีย์หมดอายุแล้ว ตรวจสอบความถูกต้องของข้อมูลเข้าสู่ระบบสำหรับการพัฒนาและข้อมูลที่ใช้งานจริง

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

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

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

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