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

ข้อความมัลติคาสต์ได้รับอนุญาตโดยใช้รูปแบบ HTTP JSON เท่านั้น

condition ไม่จำเป็น สตริง

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

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

โอเปอเรเตอร์ที่รองรับ: && , || . รองรับตัวดำเนินการสูงสุดสองตัวต่อข้อความหัวข้อ

notification_key
เลิกใช้แล้ว
ไม่จำเป็น สตริง

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

ตัวเลือก
collapse_key ไม่จำเป็น สตริง

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

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

หมายเหตุ: อนุญาตให้ใช้คีย์การยุบที่แตกต่างกันได้สูงสุด 4 รายการในช่วงเวลาที่กำหนด ซึ่งหมายความว่า FCM สามารถจัดเก็บข้อความที่แตกต่างกัน 4 ข้อความต่อแอปไคลเอ็นต์ได้พร้อมกัน หากคุณเกินจำนวนนี้ ไม่มีการรับประกันว่า 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 ในเพย์โหลด APN เมื่อมีการส่งการแจ้งเตือนและตั้งค่าเป็น true เนื้อหาของการแจ้งเตือนจะสามารถแก้ไขได้ก่อนที่จะแสดง โดยใช้ ส่วนขยายแอปบริการการแจ้งเตือน พารามิเตอร์นี้จะถูกละเว้นสำหรับ Android และเว็บ

time_to_live ไม่บังคับ, หมายเลข

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

restricted_package_
name
(Android เท่านั้น)
ไม่จำเป็น สตริง พารามิเตอร์นี้ระบุชื่อแพ็คเกจของแอปพลิเคชันซึ่งโทเค็นการลงทะเบียนต้องตรงกันจึงจะสามารถรับข้อความได้
dry_run ไม่จำเป็น, บูลีน

เมื่อตั้งค่าเป็น true พารามิเตอร์นี้จะช่วยให้นักพัฒนาทดสอบคำขอได้โดยไม่ต้องส่งข้อความจริงๆ

ค่าเริ่มต้นคือ false

เพย์โหลด
data ไม่จำเป็น วัตถุ

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

ตัวอย่างเช่น ด้วย data:{"score":"3x1"}:

บนแพลตฟอร์ม Apple หากข้อความถูกส่งผ่าน APN ข้อความนั้นจะแสดงถึงช่องข้อมูลที่กำหนดเอง หากถูกส่งผ่าน FCM ก็จะแสดงเป็นพจนานุกรมค่าคีย์ใน AppDelegate application:didReceiveRemoteNotification:

บน Android สิ่งนี้จะส่งผลให้มีการระบุชื่อ 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 จะใช้รหัสช่องที่ระบุในรายการแอป

icon ไม่จำเป็น สตริง

ไอคอนการแจ้งเตือน

ตั้งค่าไอคอนการแจ้งเตือนเป็น myicon สำหรับทรัพยากรที่วาดได้ myicon หากคุณไม่ส่งคีย์นี้ในคำขอ FCM จะแสดงไอคอน Launcher ที่ระบุในรายการแอปของคุณ

sound ไม่จำเป็น สตริง

เสียงที่จะเล่นเมื่ออุปกรณ์ได้รับการแจ้งเตือน

รองรับ "default" หรือชื่อไฟล์ของทรัพยากรเสียงที่รวมอยู่ในแอป ไฟล์เสียงจะต้องอยู่ใน /res/raw/

tag ไม่จำเป็น สตริง

ตัวระบุที่ใช้แทนที่การแจ้งเตือนที่มีอยู่ในลิ้นชักการแจ้งเตือน

หากไม่ได้ระบุ แต่ละคำขอจะสร้างการแจ้งเตือนใหม่

หากระบุและมีการแสดงการแจ้งเตือนที่มีแท็กเดียวกันอยู่แล้ว การแจ้งเตือนใหม่จะแทนที่การแจ้งเตือนที่มีอยู่ในลิ้นชักการแจ้งเตือน

color ไม่จำเป็น สตริง

สีไอคอนการแจ้งเตือน ซึ่งแสดงในรูปแบบ #rrggbb

click_action ไม่จำเป็น สตริง

การกระทำที่เกี่ยวข้องกับการคลิกของผู้ใช้ในการแจ้งเตือน

หากระบุไว้ กิจกรรมที่มีตัวกรองเจตนาที่ตรงกันจะถูกเปิดใช้งานเมื่อผู้ใช้คลิกที่การแจ้งเตือน

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 จำเป็น, สตริง

พารามิเตอร์นี้ระบุแอปไคลเอ็นต์ (โทเค็นการลงทะเบียน) ที่ได้รับข้อความ

การส่งข้อความแบบหลายผู้รับ (ส่งไปยังโทเค็นการลงทะเบียนมากกว่าหนึ่งรายการ) ได้รับอนุญาตโดยใช้รูปแบบ HTTP JSON เท่านั้น

ตัวเลือก
collapse_key ไม่จำเป็น สตริง ดู ตารางที่ 1 สำหรับรายละเอียด
time_to_live ไม่บังคับ, หมายเลข ดู ตารางที่ 1 สำหรับรายละเอียด
restricted_package_name ไม่จำเป็น สตริง ดู ตารางที่ 1 สำหรับรายละเอียด
dry_run ไม่จำเป็น, บูลีน ดู ตารางที่ 1 สำหรับรายละเอียด
เพย์โหลด
data.<key> ไม่จำเป็น สตริง

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

ตัวอย่างเช่น ใน Android "data.score"."3x1" จะส่งผลให้มีชื่อ score พิเศษของ Intent ที่มีค่าสตริง 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 ใดๆ ที่รวมอยู่ในการตอบกลับ แอปพลิเคชันเซิร์ฟเวอร์ต้องใช้การถอยกลับแบบเอ็กซ์โปเนนเชียล

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

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

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

ตารางที่ 6. ข้อความหัวข้อเนื้อหาการตอบสนอง HTTP (JSON)

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

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

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

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

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

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

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

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

ข้อผิดพลาด รหัส HTTP การดำเนินการที่แนะนำ
โทเค็นการลงทะเบียนหายไป 200 + ข้อผิดพลาด: การลงทะเบียนหายไป ตรวจสอบว่าคำขอมีโทเค็นการลงทะเบียน (ใน registration_id ในข้อความธรรมดา หรือในช่อง to หรือ registration_ids ใน JSON)
โทเค็นการลงทะเบียนไม่ถูกต้อง 200 + ข้อผิดพลาด: การลงทะเบียนไม่ถูกต้อง ตรวจสอบรูปแบบของโทเค็นการลงทะเบียนที่คุณส่งไปยังเซิร์ฟเวอร์ ตรวจสอบให้แน่ใจว่าตรงกับโทเค็นการลงทะเบียนที่แอปไคลเอนต์ได้รับจากการลงทะเบียนกับการแจ้งเตือน Firebase อย่าตัดทอนหรือเพิ่มอักขระเพิ่มเติม
อุปกรณ์ที่ไม่ได้ลงทะเบียน 200 + ข้อผิดพลาด: ไม่ได้ลงทะเบียน โทเค็นการลงทะเบียนที่มีอยู่อาจหยุดใช้ไม่ได้ในหลายสถานการณ์ รวมถึง:
  • หากแอปไคลเอ็นต์ยกเลิกการลงทะเบียนกับ FCM
  • หากแอปไคลเอ็นต์ยกเลิกการลงทะเบียนโดยอัตโนมัติ ซึ่งอาจเกิดขึ้นได้หากผู้ใช้ถอนการติดตั้งแอปพลิเคชัน ตัวอย่างเช่น บน iOS หาก APN Feedback Service รายงานว่าโทเค็น APN ไม่ถูกต้อง
  • หากโทเค็นการลงทะเบียนหมดอายุ (เช่น Google อาจตัดสินใจรีเฟรชโทเค็นการลงทะเบียน หรือโทเค็น APN สำหรับอุปกรณ์ iOS หมดอายุ)
  • หากแอปไคลเอ็นต์ได้รับการอัปเดตแต่ไม่ได้กำหนดค่าเวอร์ชันใหม่ให้รับข้อความ
ในกรณีทั้งหมดเหล่านี้ ให้ลบโทเค็นการลงทะเบียนนี้ออกจากเซิร์ฟเวอร์แอปและหยุดใช้เพื่อส่งข้อความ
ชื่อแพ็คเกจไม่ถูกต้อง 200 + ข้อผิดพลาด: InvalidPackageName ตรวจสอบให้แน่ใจว่าข้อความถูกส่งไปยังโทเค็นการลงทะเบียนซึ่งมีชื่อแพ็คเกจตรงกับค่าที่ส่งในคำขอ
ข้อผิดพลาดในการรับรองความถูกต้อง 401 บัญชีผู้ส่งที่ใช้ในการส่งข้อความไม่สามารถตรวจสอบสิทธิ์ได้ สาเหตุที่เป็นไปได้คือ:
  • ส่วนหัวการอนุญาตหายไปหรือมีไวยากรณ์ไม่ถูกต้องในคำขอ HTTP
  • โครงการ Firebase ที่มีรหัสเซิร์ฟเวอร์ที่ระบุไม่ถูกต้อง
  • คีย์เซิร์ฟเวอร์เดิมเท่านั้น - คำขอมาจากเซิร์ฟเวอร์ที่ไม่อยู่ในรายการที่อนุญาตพิเศษใน IP ของคีย์เซิร์ฟเวอร์
ตรวจสอบว่าโทเค็นที่คุณส่งภายในส่วนหัวการตรวจสอบสิทธิ์เป็นรหัสเซิร์ฟเวอร์ที่ถูกต้องซึ่งเชื่อมโยงกับโปรเจ็กต์ของคุณ ดู การตรวจสอบความถูกต้องของรหัสเซิร์ฟเวอร์ สำหรับรายละเอียด หากคุณใช้คีย์เซิร์ฟเวอร์เดิม ขอแนะนำให้อัปเกรดเป็นคีย์ใหม่ที่ไม่มีข้อจำกัด IP ดู การย้ายข้อมูลคีย์เซิร์ฟเวอร์เดิม
ผู้ส่งไม่ตรงกัน 200 + ข้อผิดพลาด: MismatchSenderId โทเค็นการลงทะเบียนเชื่อมโยงกับกลุ่มผู้ส่งบางกลุ่ม เมื่อแอปไคลเอ็นต์ลงทะเบียน FCM ต้องระบุผู้ส่งที่ได้รับอนุญาตให้ส่งข้อความ คุณควรใช้หนึ่งในรหัสผู้ส่งเหล่านั้นเมื่อส่งข้อความไปยังแอปไคลเอ็นต์ หากคุณเปลี่ยนไปใช้ผู้ส่งรายอื่น โทเค็นการลงทะเบียนที่มีอยู่จะไม่ทำงาน
JSON ไม่ถูกต้อง 400 ตรวจสอบว่าข้อความ JSON มีรูปแบบที่ถูกต้องและมีช่องที่ถูกต้อง (เช่น ตรวจสอบว่ามีการส่งประเภทข้อมูลที่ถูกต้อง)
พารามิเตอร์ไม่ถูกต้อง 400 + ข้อผิดพลาด: พารามิเตอร์ไม่ถูกต้อง ตรวจสอบว่าพารามิเตอร์ที่ให้มามีชื่อและประเภทที่ถูกต้อง
ข้อความใหญ่เกินไป 200 + ข้อผิดพลาด: MessageTooBig ตรวจสอบว่าขนาดรวมของข้อมูลเพย์โหลดที่รวมอยู่ในข้อความไม่เกินขีดจำกัด FCM: 4096 ไบต์สำหรับข้อความส่วนใหญ่ หรือ 2048 ไบต์ในกรณีของข้อความไปยังหัวข้อ ซึ่งรวมถึงทั้งคีย์และค่า
คีย์ข้อมูลไม่ถูกต้อง 200+ ข้อผิดพลาด:
DataKey ไม่ถูกต้อง
ตรวจสอบว่าข้อมูลเพย์โหลดไม่มีคีย์ (เช่น 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
  • ใช้การถอยกลับแบบเอ็กซ์โพเนนเชียลในกลไกการลองใหม่ของคุณ (เช่น หากคุณรอหนึ่งวินาทีก่อนลองอีกครั้งครั้งแรก ให้รออย่างน้อยสองวินาทีก่อนครั้งถัดไป จากนั้นรอ 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 string ตัวระบุเฉพาะของกลุ่มอุปกรณ์ ค่านี้จะถูกส่งกลับเพื่อตอบสนองต่อการดำเนินการ create ที่สำเร็จ และจำเป็นสำหรับการดำเนินการภายหลังทั้งหมดในกลุ่มอุปกรณ์
registration_ids จำเป็นต้องมี อาร์เรย์ของสตริง โทเค็นอุปกรณ์ที่จะเพิ่มหรือลบ หากคุณลบโทเค็นการลงทะเบียนที่มีอยู่ทั้งหมดออกจากกลุ่มอุปกรณ์ FCM จะลบกลุ่มอุปกรณ์นั้น