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

พารามิเตอร์นี้ระบุผู้รับข้อความ

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

พารามิเตอร์นี้ระบุผู้รับข้อความมัลติแคสต์ ซึ่งเป็นข้อความที่ส่งไปยังโทเค็นการลงทะเบียนมากกว่า 1 รายการ

ค่าควรเป็นอาร์เรย์ของโทเค็นการลงทะเบียนที่จะส่งข้อความมัลติแคสต์ อาร์เรย์ต้องมีโทเค็นการลงทะเบียนอย่างน้อย 1 รายการ แต่ไม่เกิน 1,000 รายการ หากต้องการส่งข้อความไปยังอุปกรณ์เครื่องเดียว ให้ใช้พารามิเตอร์ to

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

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

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

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

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

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

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

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

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

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

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

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

ในแพลตฟอร์ม Apple ให้ใช้ช่องนี้เพื่อแสดงmutable-contentในเพย์โหลด APN เมื่อมีการแจ้งเตือนและตั้งค่าเป็น true ระบบจะแก้ไขเนื้อหาของการแจ้งเตือนได้ก่อนที่จะแสดงโดยใช้ ส่วนขยายแอปบริการแจ้งเตือน ระบบจะละเว้นพารามิเตอร์นี้สําหรับ Android และเว็บ

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

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

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

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

เช่น data:{"score":"3x1"}:

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

ใน Android การดำเนินการนี้จะส่งผลให้มีข้อมูลเพิ่มเติมของ Intent ชื่อ score ที่มีค่าสตริง 3x1

คีย์ไม่ควรเป็นคําที่สงวนไว้ ("from", "message_type" หรือคําที่ขึ้นต้นด้วย "google" หรือ "gcm") อย่าใช้คำที่ระบุไว้ในตารางนี้ (เช่น collapse_key)

เราขอแนะนำให้ใช้ค่าในประเภทสตริง คุณต้องแปลงค่าในออบเจ็กต์หรือประเภทข้อมูลอื่นๆ ที่ไม่ใช่สตริง (เช่น จำนวนเต็มหรือบูลีน) เป็นสตริง

ชื่อการแจ้งเตือน

ช่องนี้จะไม่ปรากฏในโทรศัพท์และแท็บเล็ต

ข้อความเนื้อหาของการแจ้งเตือน

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

สตริงที่ระบุไฟล์เสียงในแพ็กเกจหลักของแอปไคลเอ็นต์หรือในโฟลเดอร์ Library/Sounds ของคอนเทนเนอร์ข้อมูลของแอป ดูข้อมูลเพิ่มเติมได้ที่ ไลบรารีนักพัฒนาแอป iOS

คุณค่าของป้ายบนไอคอนแอปในหน้าจอหลัก

หากไม่ระบุไว้ เครื่องหมายจะไม่เปลี่ยนแปลง

หากตั้งค่าเป็น 0 ระบบจะนำป้ายออก

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

สอดคล้องกับ category ในเพย์โหลด APN

คำบรรยายของข้อความแจ้ง

คีย์ของสตริงเนื้อหาในทรัพยากรสตริงของแอปที่จะใช้แปลข้อความเนื้อหาเป็นภาษาที่ผู้ใช้กําลังใช้

สอดคล้องกับ loc-key ในเพย์โหลด APN

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

ค่าสตริงตัวแปรที่จะใช้แทนตัวระบุรูปแบบใน body_loc_key เพื่อใช้แปลข้อความเนื้อหาเป็นภาษาที่ผู้ใช้กําลังใช้

สอดคล้องกับ loc-args ในเพย์โหลด APN

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

คีย์ของสตริงชื่อในทรัพยากรสตริงของแอปที่จะใช้แปลข้อความชื่อเป็นภาษาที่ผู้ใช้กําลังใช้

สอดคล้องกับ title-loc-key ในเพย์โหลด APN

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

ค่าสตริงตัวแปรที่จะใช้แทนตัวระบุรูปแบบใน title_loc_key เพื่อใช้แปลข้อความชื่อเป็นภาษาที่ผู้ใช้กําลังใช้

สอดคล้องกับ title-loc-args ในเพย์โหลด APN

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

ชื่อการแจ้งเตือน

ข้อความเนื้อหาของการแจ้งเตือน

รหัสช่องของการแจ้งเตือน (ใหม่ใน Android O)

แอปต้องสร้างแชแนลที่มีรหัสช่องนี้ก่อนจึงจะได้รับการแจ้งเตือนที่มีรหัสช่องนี้

หากคุณไม่ได้ส่งรหัสแชแนลนี้ในคำขอ หรือแอปยังไม่ได้สร้างรหัสแชแนลที่ระบุไว้ FCM จะใช้รหัสแชแนลที่ระบุไว้ในไฟล์ Manifest ของแอป

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

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

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

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

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

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

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

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

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

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

คีย์ของสตริงเนื้อหาในทรัพยากรสตริงของแอปที่จะใช้แปลข้อความเนื้อหาเป็นภาษาที่ผู้ใช้กําลังใช้

ดูข้อมูลเพิ่มเติมได้ใน แหล่งข้อมูลสตริง

ค่าสตริงตัวแปรที่จะใช้แทนตัวระบุรูปแบบใน body_loc_key เพื่อใช้แปลข้อความเนื้อหาเป็นภาษาที่ผู้ใช้กําลังใช้

ดูข้อมูลเพิ่มเติมได้ในหัวข้อ การจัดรูปแบบและการจัดสไตล์

คีย์ของสตริงชื่อในทรัพยากรสตริงของแอปที่จะใช้แปลข้อความชื่อเป็นภาษาที่ผู้ใช้กําลังใช้

ดูข้อมูลเพิ่มเติมได้ใน แหล่งข้อมูลสตริง

ค่าสตริงตัวแปรที่จะใช้แทนตัวระบุรูปแบบใน title_loc_key เพื่อใช้แปลข้อความชื่อเป็นภาษาที่ผู้ใช้กําลังใช้

ดูข้อมูลเพิ่มเติมได้ในหัวข้อ การจัดรูปแบบและการจัดสไตล์

ชื่อการแจ้งเตือน

ข้อความเนื้อหาของการแจ้งเตือน

URL ที่จะใช้เป็นไอคอนของการแจ้งเตือน

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

ค่า URL ทั้งหมดต้องใช้ HTTPS

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

การรับส่งข้อความมัลติแคสต์ (การส่งไปยังโทเค็นการลงทะเบียนมากกว่า 1 รายการ) ใช้ได้เฉพาะในรูปแบบ HTTP JSON เท่านั้น

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

ตัวอย่างเช่น ใน Android "data.score"."3x1" จะส่งผลให้มีข้อมูลเพิ่มเติมของ Intent ที่มีชื่อว่า score ซึ่งมีค่าสตริงเป็น 3x1

คีย์ไม่ควรเป็นคําที่สงวนไว้ ("from", "message_type" หรือคําที่ขึ้นต้นด้วย "google" หรือ "gcm") อย่าใช้คำที่ระบุไว้ในตารางนี้ (เช่น collapse_key)

• message_id: สตริงที่ระบุรหัสที่ไม่ซ้ำกันสำหรับข้อความที่ประมวลผลสำเร็จแต่ละรายการ
• error: สตริงที่ระบุข้อผิดพลาดที่เกิดขึ้นเมื่อประมวลผลข้อความสำหรับผู้รับ ดูค่าที่เป็นไปได้ได้ในตาราง 9

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

• ไม่มีส่วนหัวการให้สิทธิ์หรือมีไวยากรณ์ที่ไม่ถูกต้องในคำขอ HTTP
• โปรเจ็กต์ Firebase ที่คีย์เซิร์ฟเวอร์ที่ระบุเป็นของโปรเจ็กต์นั้นไม่ถูกต้อง
• คีย์เซิร์ฟเวอร์เดิมเท่านั้น - คำขอมาจากเซิร์ฟเวอร์ที่ไม่ได้อยู่ในรายการที่อนุญาตใน IP ของคีย์เซิร์ฟเวอร์

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

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

ผู้ส่งที่ทำให้เกิดปัญหาอาจถูกเพิ่มลงในรายการที่ไม่ได้รับอนุญาตให้ส่ง

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

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