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

ระบบอนุญาตให้ใช้เฉพาะข้อความมัลติแคสต์ในรูปแบบ HTTP JSON

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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