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

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

เมื่อใช้โปรโตคอล 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 และไม่เกิน 1000 โทเค็นการลงทะเบียน หากต้องการส่งข้อความไปยังอุปกรณ์เครื่องเดียว ให้ใช้ พารามิเตอร์ to

อนุญาตให้ใช้ข้อความ Multicast โดยใช้รูปแบบ HTTP JSON เท่านั้น

condition สตริง (ไม่บังคับ)

พารามิเตอร์นี้ระบุนิพจน์เชิงตรรกะของเงื่อนไข กำหนดเป้าหมายของข้อความ

เงื่อนไขที่รองรับ: หัวข้อ ซึ่งมีรูปแบบเป็น "yourTopic" ในหัวข้อ" ช่วงเวลานี้ ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่

โอเปอเรเตอร์ที่รองรับ: &&, || สูงสุด 2 โอเปอเรเตอร์ต่อข้อความตามหัวข้อ
notification_key
เลิกใช้งาน		 สตริง (ไม่บังคับ)

พารามิเตอร์นี้เลิกใช้งานแล้ว แต่ให้ใช้ to แทนเพื่อระบุ ผู้รับข้อความ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีส่งข้อความถึง อุปกรณ์หลายเครื่อง โปรดดูเอกสารสำหรับแพลตฟอร์มของคุณ
ตัวเลือก
collapse_key สตริง (ไม่บังคับ)

พารามิเตอร์นี้เป็นตัวระบุกลุ่มข้อความ (เช่น โดยมี collapse_key: "Updates Available") ที่สามารถยุบได้เพื่อให้มีเฉพาะ ข้อความสุดท้ายจะถูกส่งเมื่อสามารถจัดส่งต่อได้ เพื่อหลีกเลี่ยงการส่ง ข้อความเดียวกันจำนวนมากเมื่ออุปกรณ์กลับมาออนไลน์หรือเปิดใช้งาน

ทั้งนี้ เราไม่รับประกันลำดับของการส่งข้อความ

หมายเหตุ: อนุญาตให้ใช้คีย์ยุบที่แตกต่างกันได้สูงสุด 4 รายการในช่วงเวลาหนึ่ง ซึ่งหมายความว่า FCM สามารถเก็บข้อความที่แตกต่างกัน 4 ข้อความต่อแอปไคลเอ็นต์ได้ 1 แอป หากคุณ เกินตัวเลขนี้ ไม่มีการรับประกันว่าคีย์ยุบ 4 คีย์ที่ FCM จะเก็บไว้

priority สตริง (ไม่บังคับ)

กำหนดลำดับความสำคัญของข้อความ ค่าที่ถูกต้องคือ "ปกติ" และ "สูง" ในแพลตฟอร์ม Apple สิ่งเหล่านี้จะสอดคล้องกับลำดับความสำคัญของ APN ที่ 5 และ 10

โดยค่าเริ่มต้น ระบบจะส่งข้อความแจ้งเตือนที่มีลำดับความสำคัญสูง และส่งข้อความข้อมูล ส่งโดยมีลำดับความสำคัญปกติ ลำดับความสำคัญปกติจะเพิ่มประสิทธิภาพให้ สิ้นเปลืองแบตเตอรี่และควรใช้งานเว้นแต่จำเป็นต้องนำส่งทันที สำหรับข้อความที่มีลำดับความสำคัญปกติ แอปอาจได้รับข้อความที่มี ความล่าช้าที่ไม่ได้ระบุ

เมื่อคุณส่งข้อความที่มีลำดับความสำคัญสูง ระบบจะส่งข้อความนั้นทันทีและแอป แสดงการแจ้งเตือนได้

content_available ไม่บังคับ บูลีน

ในแพลตฟอร์ม Apple ให้ใช้ช่องนี้เพื่อแสดง content-available ในส่วน เพย์โหลด APNs เมื่อมีการส่งการแจ้งเตือนหรือข้อความและตั้งค่าเป็น true แอปไคลเอ็นต์ที่ไม่มีการใช้งานถูกปลุก และข้อความจะส่งผ่าน APN เป็นการแจ้งเตือนแบบไม่มีเสียง และไม่ผ่าน FCM โปรดทราบว่าการแจ้งเตือนแบบไม่มีเสียงใน APN จะไม่ รับประกันว่าจะได้รับการนำส่ง และอาจขึ้นอยู่กับปัจจัยต่างๆ เช่น ผู้ใช้เมื่อเปิดเครื่อง "พลังงานต่ำ" โหมด บังคับให้ปิดแอป ฯลฯ ใน Android ข้อความข้อมูลจะปลุกระบบแอปโดยค่าเริ่มต้น เปิด ยังไม่รองรับ Chrome ในขณะนี้
mutable_content ไม่บังคับ, JSON บูลีน

ในแพลตฟอร์ม Apple ให้ใช้ช่องนี้เพื่อแสดง mutable-content ในเพย์โหลด APNs เมื่อมีการส่งการแจ้งเตือนและมีการตั้งค่าการตั้งค่านี้ เป็น 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 Developer Library สำหรับข้อมูลเพิ่มเติม

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> สตริง (ไม่บังคับ)

พารามิเตอร์นี้ระบุคู่คีย์-ค่าสำหรับเพย์โหลดของข้อความ ไม่มีการจำกัดจำนวนพารามิเตอร์คีย์-ค่า แต่จำกัดขนาดข้อความทั้งหมดไว้ที่ 4096 ไบต์

ตัวอย่างเช่น ใน 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 บริการฟีดแบ็กรายงานว่าโทเค็น APNs ไม่ถูกต้อง
  • หากโทเค็นการลงทะเบียนหมดอายุ (เช่น Google อาจตัดสินใจรีเฟรช โทเค็นการลงทะเบียน หรือโทเค็น APNs หมดอายุสําหรับอุปกรณ์ iOS)
  • หากอัปเดตแอปไคลเอ็นต์แล้ว แต่ไม่ได้กำหนดค่าเวอร์ชันใหม่ให้รับข้อความ
สำหรับทุกกรณี ให้นำโทเค็นการลงทะเบียนนี้ออกจากแอป และหยุดใช้ในการส่งข้อความ
ชื่อแพ็กเกจไม่ถูกต้อง 200 + ข้อผิดพลาด:InvalidPackageName ตรวจสอบว่าข้อความส่งถึงโทเค็นการลงทะเบียนที่มีชื่อแพ็กเกจ ตรงกับค่าที่ส่งในคำขอ
ข้อผิดพลาดในการตรวจสอบสิทธิ์ 401 ไม่สามารถตรวจสอบสิทธิ์บัญชีผู้ส่งที่ใช้ส่งข้อความ สาเหตุที่เป็นไปได้มีดังนี้
  • ไม่มีส่วนหัวการให้สิทธิ์หรือมีไวยากรณ์ที่ไม่ถูกต้องในคำขอ HTTP
  • โปรเจ็กต์ Firebase ที่มีคีย์เซิร์ฟเวอร์ที่ระบุไม่ถูกต้อง
  • เฉพาะคีย์เซิร์ฟเวอร์เดิมเท่านั้น ซึ่งเป็นคำขอที่มาจากเซิร์ฟเวอร์ที่ไม่ได้อยู่ในรายการที่อนุญาตพิเศษใน IP ของคีย์เซิร์ฟเวอร์
ตรวจสอบว่าโทเค็นที่คุณส่งภายในส่วนหัวการตรวจสอบสิทธิ์นั้น คีย์เซิร์ฟเวอร์ที่ถูกต้องซึ่งเชื่อมโยงกับโปรเจ็กต์ของคุณ โปรดดู การตรวจสอบความถูกต้องของคีย์เซิร์ฟเวอร์ เพื่อดูรายละเอียด หากคุณใช้คีย์เซิร์ฟเวอร์เดิม เราขอแนะนำให้คุณอัปเกรดเป็นคีย์ใหม่ที่ไม่มีข้อจำกัด IP โปรดดู ย้ายข้อมูลคีย์เซิร์ฟเวอร์เดิม
ผู้ส่งไม่ตรงกัน 200 + ข้อผิดพลาด:MismatchSenderId โทเค็นการลงทะเบียนจะผูกกับกลุ่มผู้ส่งบางกลุ่ม เมื่อแอปของไคลเอ็นต์ลงทะเบียน สำหรับ FCM ต้องระบุผู้ส่งที่ได้รับอนุญาตให้ส่งข้อความ คุณควรใช้ข้อมูลโค้ด ของรหัสผู้ส่งเหล่านั้นเมื่อส่งข้อความถึงแอปไคลเอ็นต์ หากเปลี่ยนไปใช้ ผู้ส่ง โทเค็นการลงทะเบียนที่มีอยู่จะไม่ทำงาน
JSON ไม่ถูกต้อง 400 ตรวจสอบว่าข้อความ JSON อยู่ในรูปแบบที่ถูกต้องและมีช่องที่ถูกต้อง (เช่น การส่งประเภทข้อมูลที่ถูกต้อง)
พารามิเตอร์ไม่ถูกต้อง 400 + ข้อผิดพลาด:invalidParameters ตรวจสอบว่าพารามิเตอร์ที่ระบุมีชื่อและประเภทที่ถูกต้อง
ข้อความมีขนาดใหญ่เกินไป 200 + ข้อผิดพลาด:MessageTooBig ตรวจสอบว่าขนาดรวมของข้อมูลเพย์โหลดที่รวมอยู่ในข้อความ ไม่เกินขีดจำกัดของ FCM: 4096 ไบต์สำหรับข้อความส่วนใหญ่ หรือ 2048 ไบต์ในกรณีที่ ของข้อความไปยังหัวข้อ ซึ่งรวมทั้ง คีย์และค่า
คีย์ข้อมูลไม่ถูกต้อง 200 + ข้อผิดพลาด:
คีย์ข้อมูลไม่ถูกต้อง		 ตรวจสอบว่าข้อมูลเพย์โหลดไม่มีคีย์ (เช่น from, หรือ gcm หรือค่าใดก็ได้ นำหน้าด้วย google) ที่ใช้ภายในโดย FCM โปรดทราบว่าคำบางคำ (เช่น collapse_key) ก็ใช้โดย FCM เช่นกัน แต่ ได้รับอนุญาตให้อยู่ในเพย์โหลด ในกรณีนี้ ค่าเพย์โหลดจะถูกลบล้างโดยค่า FCM
Time to Live ไม่ถูกต้อง 200 + ข้อผิดพลาด:invalidTtl ตรวจสอบว่าค่าที่ใช้ใน time_to_live เป็นจำนวนเต็มที่แสดง ระยะเวลาเป็นวินาทีระหว่าง 0 ถึง 2,419,200 (4 สัปดาห์)
ระยะหมดเวลา 5xx หรือ 200 + ข้อผิดพลาด:ไม่พร้อมใช้งาน

เซิร์ฟเวอร์ประมวลผลคำขอได้ไม่ทันเวลา ลองส่งคำขอเดิมอีกครั้ง แต่คุณต้องทำดังนี้

  • ทำตามส่วนหัว Retry-After หากรวมอยู่ในการตอบกลับจาก เซิร์ฟเวอร์การเชื่อมต่อ FCM
  • ใช้ Exponential Backoff ในกลไกการลองใหม่ (เช่น ถ้าคุณรอ 1 วินาที ก่อนการลองใหม่ครั้งแรก ให้รออย่างน้อย 2 วินาทีก่อนรายการถัดไป จากนั้น 4 วินาที และเช่นนี้อีก 4 วินาที) หากส่งข้อความหลายข้อความ ให้หน่วงเวลาข้อความแต่ละรายการทีละข้อความด้วยการสุ่มเพิ่ม เพื่อหลีกเลี่ยงการออกคำขอใหม่สำหรับข้อความทั้งหมดพร้อมกัน

ผู้ส่งที่ทำให้เกิดปัญหาเสี่ยงต่อการถูกขึ้นบัญชีดำ
ข้อผิดพลาดภายในเซิร์ฟเวอร์ 500 หรือ 200 + ข้อผิดพลาด:InternalServerError เซิร์ฟเวอร์พบข้อผิดพลาดขณะพยายามประมวลผลคำขอ คุณลองอีกครั้งได้ คำขอเดียวกันที่เป็นไปตามข้อกำหนดที่ระบุไว้ใน "ระยะหมดเวลา" (ดูแถวด้านบน) หากข้อผิดพลาด ยังคงอยู่ โปรดติดต่อทีมสนับสนุน Firebase
เกินอัตราข้อความในอุปกรณ์ 200 + ข้อผิดพลาด:
อัตราข้อความของอุปกรณ์
เกินขีดจำกัด

อัตราการส่งข้อความไปยังอุปกรณ์เครื่องใดเครื่องหนึ่งสูงเกินไป หากแอป Apple ส่งข้อความในอัตราที่เกินขีดจำกัด APN ข้อความนี้อาจได้รับข้อความแสดงข้อผิดพลาดนี้

ลด จำนวนข้อความที่ส่งไปยังอุปกรณ์นี้ ใช้ exponential Backoff เพื่อลองส่งอีกครั้ง
เกินอัตราข้อความของหัวข้อ 200 + ข้อผิดพลาด:
อัตราข้อความหัวข้อ
เกินขีดจำกัด		 อัตราการส่งข้อความไปยังผู้ติดตามในหัวข้อใดหัวข้อหนึ่งสูงเกินไป ลด จำนวนข้อความที่ส่งสำหรับหัวข้อนี้และ ใช้ exponential Backoff เพื่อลองส่งอีกครั้ง
ข้อมูลเข้าสู่ระบบ APN ไม่ถูกต้อง 200 + ข้อผิดพลาด:
ไม่ถูกต้องApnsCredential 		ส่งข้อความที่กำหนดเป้าหมายไปยังอุปกรณ์ Apple ไม่ได้เนื่องจาก APN ที่จำเป็น คีย์การตรวจสอบสิทธิ์ไม่ได้อัปโหลดหรือหมดอายุแล้ว ตรวจสอบความถูกต้องของการพัฒนา และข้อมูลรับรองการผลิต

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

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

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

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