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

เอกสารนี้ให้ข้อมูลอ้างอิงเกี่ยวกับไวยากรณ์ XMPP ที่ใช้ส่งข้อความระหว่างเซิร์ฟเวอร์แอป แอปไคลเอ็นต์ และ Firebase Cloud Messaging (FCM) เซิร์ฟเวอร์แอปต้องเชื่อมต่อกับปลายทางต่อไปนี้

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

พารามิเตอร์และตัวเลือกที่ใช้ได้มีดังนี้

ไวยากรณ์ข้อความขาลง

ส่วนนี้จะแสดงไวยากรณ์สําหรับการส่งข้อความดาวน์สตรีม

ข้อความ XMPP ขาลง (JSON)

ตารางต่อไปนี้แสดงเป้าหมาย ตัวเลือก และเพย์โหลดสําหรับข้อความ XMPP JSON

ตารางที่ 1 เป้าหมาย ตัวเลือก และเพย์โหลดสําหรับข้อความ XMPP ดาวน์สตรีม (JSON)

พารามิเตอร์ การใช้งาน คำอธิบาย
เป้าหมาย
to ไม่บังคับ, สตริง

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

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

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

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

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

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

พารามิเตอร์นี้จะระบุข้อความในการเชื่อมต่อ XMPP อย่างไม่ซ้ำกัน
collapse_key ไม่บังคับ, สตริง

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

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

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

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

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

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

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

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

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

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

time_to_live ไม่บังคับ, ตัวเลข

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

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

การรองรับเพย์โหลดการแจ้งเตือน

ตารางต่อไปนี้แสดงรายการคีย์ที่กําหนดไว้ล่วงหน้าสําหรับการสร้างข้อความแจ้งเตือนสําหรับแพลตฟอร์ม Apple และ Android

ตาราง 2ก Apple — คีย์สําหรับข้อความการแจ้งเตือน

พารามิเตอร์ การใช้งาน คำอธิบาย
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

ตีความการตอบกลับข้อความ XMPP ดาวน์สตรีม

ตารางต่อไปนี้แสดงช่องที่ปรากฏในการตอบกลับข้อความ XMPP ดาวน์สตรีม

ตารางที่ 3 เนื้อหาการตอบกลับ XMPP ของข้อความดาวน์สตรีม

พารามิเตอร์ การใช้งาน คำอธิบาย
from ต้องระบุ, สตริง

พารามิเตอร์นี้จะระบุผู้ที่ส่งคำตอบนี้

ค่านี้คือโทเค็นการลงทะเบียนของแอปไคลเอ็นต์
message_id ต้องระบุ, สตริง พารามิเตอร์นี้จะระบุข้อความในการเชื่อมต่อ XMPP อย่างไม่ซ้ำกัน ค่าคือสตริงที่ระบุข้อความที่เกี่ยวข้องโดยไม่ซ้ำกัน
message_type ต้องระบุ, สตริง

พารามิเตอร์นี้ระบุข้อความ ack หรือ nack จาก FCM ไปยังเซิร์ฟเวอร์แอป

หากตั้งค่าเป็น nack เซิร์ฟเวอร์แอปควรดูที่ error และ error_description เพื่อรับข้อมูลการไม่ผ่าน

error ไม่บังคับ, สตริง พารามิเตอร์นี้ระบุข้อผิดพลาดที่เกี่ยวข้องกับข้อความดาวน์สตรีม ระบบจะตั้งค่าเมื่อ message_type เป็น nack ดูรายละเอียดได้ในตารางที่ 4
error_description ไม่บังคับ, สตริง พารามิเตอร์นี้จะให้ข้อมูลอธิบายเกี่ยวกับข้อผิดพลาด การตั้งค่าจะดำเนินการเมื่อ message_type เป็น nack

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

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

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

ข้อผิดพลาด รหัส XMPP การดำเนินการที่แนะนำ
ไม่มีโทเค็นการลงทะเบียน INVALID_JSON ตรวจสอบว่าคําขอมีโทเค็นการลงทะเบียน (ใน registration_id ในข้อความแบบธรรมดา หรือในช่อง to หรือ registration_ids ใน JSON)
การลงทะเบียน APNs ไม่ถูกต้อง INVALID_JSON สําหรับการลงทะเบียน iOS ให้ตรวจสอบว่าคําขอลงทะเบียนจากไคลเอ็นต์มีโทเค็น APNs และรหัสแอปพลิเคชันที่ถูกต้อง
โทเค็นการลงทะเบียนไม่ถูกต้อง BAD_REGISTRATION ตรวจสอบรูปแบบของโทเค็นการลงทะเบียนที่คุณส่งไปยังเซิร์ฟเวอร์ ตรวจสอบว่าตรงกับโทเค็นการลงทะเบียนที่แอปไคลเอ็นต์ได้รับจากการลงทะเบียนกับ FCM อย่าตัดให้สั้นลงหรือเพิ่มอักขระ
อุปกรณ์ที่ไม่ได้ลงทะเบียน DEVICE_UNREGISTERED โทเค็นการลงทะเบียนที่มีอยู่อาจใช้งานไม่ได้ในบางกรณี ซึ่งรวมถึง
  • ในกรณีที่แอปไคลเอ็นต์ยกเลิกการลงทะเบียนกับ FCM
  • หากแอปไคลเอ็นต์ไม่ได้ลงทะเบียนโดยอัตโนมัติ ซึ่งอาจเกิดขึ้นได้หากผู้ใช้ถอนการติดตั้งแอปพลิเคชัน ตัวอย่างเช่น ใน iOS หาก APNs รายงานว่าโทเค็น APNs ไม่ถูกต้อง
  • หากโทเค็นการลงทะเบียนหมดอายุ (เช่น Google อาจตัดสินใจรีเฟรชโทเค็นการลงทะเบียน หรือโทเค็น APNs ของอุปกรณ์หมดอายุ)
  • หากแอปไคลเอ็นต์ได้รับการอัปเดต แต่เวอร์ชันใหม่ไม่ได้กำหนดค่าให้รับข้อความ
ในทุกกรณีเหล่านี้ ให้นำโทเค็นการลงทะเบียนนี้ออกจากเซิร์ฟเวอร์แอปและหยุดใช้โทเค็นดังกล่าวเพื่อส่งข้อความ
ผู้ส่งไม่ตรงกัน SENDER_ID_MISMATCH โทเค็นการลงทะเบียนจะเชื่อมโยงกับผู้ส่งบางกลุ่ม เมื่อแอปไคลเอ็นต์ลงทะเบียนสำหรับ FCM จะต้องระบุผู้ส่งที่ได้รับอนุญาตให้ส่งข้อความ คุณควรใช้รหัสผู้ส่งดังกล่าวเมื่อส่งข้อความไปยังแอปไคลเอ็นต์ หากเปลี่ยนผู้ส่งเป็นบุคคลอื่น โทเค็นการลงทะเบียนที่มีอยู่จะไม่ทำงาน
JSON ไม่ถูกต้อง INVALID_JSON ตรวจสอบว่าข้อความ JSON อยู่ในรูปแบบที่ถูกต้องและมีช่องที่ถูกต้อง (เช่น ตรวจสอบว่าได้ส่งประเภทข้อมูลที่ถูกต้อง)
ข้อความใหญ่เกินไป INVALID_JSON ตรวจสอบว่าขนาดรวมของข้อมูลเพย์โหลดที่รวมอยู่ในข้อความไม่เกินขีดจำกัด FCM: 4096 ไบต์สำหรับข้อความส่วนใหญ่ หรือ 2048 ไบต์สำหรับข้อความไปยังหัวข้อ ซึ่งรวมถึงทั้งคีย์และค่า
คีย์ข้อมูลไม่ถูกต้อง INVALID_JSON ตรวจสอบว่าข้อมูลเพย์โหลดไม่มีคีย์ (เช่น from, gcm หรือค่าใดๆ ที่มี google นำหน้า) ที่ FCM ใช้ภายใน โปรดทราบว่า FCM ใช้คําบางคํา (เช่น collapse_key) ด้วย แต่อนุญาตให้ใช้ในเพย์โหลดได้ ในกรณีนี้ ค่าเพย์โหลดจะถูกลบล้างโดยค่า FCM
Time To Live ไม่ถูกต้อง INVALID_JSON ตรวจสอบว่าค่าที่ใช้ใน time_to_live เป็นจํานวนเต็มที่แสดงระยะเวลาเป็นวินาทีระหว่าง 0 ถึง 2,419,200 (4 สัปดาห์)
ข้อความ ACK ไม่ถูกต้อง BAD_ACK ตรวจสอบว่าข้อความ ack อยู่ในรูปแบบที่ถูกต้องก่อนลองอีกครั้ง ดูรายละเอียดได้ในตาราง 6
ระยะหมดเวลา SERVICE_UNAVAILABLE

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

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

หมายเหตุ: ผู้ส่งที่ทำให้เกิดปัญหาอาจถูกเพิ่มลงในรายการที่ไม่ได้รับอนุญาตให้ส่ง
ข้อผิดพลาดภายในเซิร์ฟเวอร์ INTERNAL_SERVER_
ERROR		 เซิร์ฟเวอร์พบข้อผิดพลาดขณะพยายามประมวลผลคำขอ คุณลองส่งคำขอเดิมอีกครั้งได้โดยทำตามข้อกำหนดที่ระบุไว้ใน "หมดเวลา" (ดูแถวด้านบน)
อัตราการส่งข้อความของอุปกรณ์เกินขีดจำกัด DEVICE_MESSAGE_RATE
_EXCEEDED		 อัตราการส่งข้อความไปยังอุปกรณ์หนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งไปยังอุปกรณ์นี้ และอย่าลองส่งไปยังอุปกรณ์นี้อีกครั้งในทันที
อัตราการส่งข้อความ Topics เกินขีดจำกัด TOPICS_MESSAGE_RATE
_EXCEEDED		 อัตราข้อความที่ส่งไปยังผู้ติดตามหัวข้อหนึ่งๆ สูงเกินไป ลดจำนวนข้อความที่ส่งสำหรับหัวข้อนี้ และอย่าลองส่งอีกครั้งในทันที
การระบายการเชื่อมต่อ CONNECTION_DRAINING ระบบประมวลผลข้อความไม่ได้เนื่องจากการเชื่อมต่อหมด ปัญหานี้เกิดขึ้นเนื่องจาก FCM ต้องปิดการเชื่อมต่อเป็นระยะๆ เพื่อดำเนินการปรับสมดุลภาระ ลองส่งข้อความอีกครั้งผ่านการเชื่อมต่อ XMPP อื่น
ข้อมูลเข้าสู่ระบบ APNs ไม่ถูกต้อง INVALID_APNS_CREDENTIAL ส่งข้อความที่กำหนดเป้าหมายไปยังอุปกรณ์ iOS ไม่ได้เนื่องจากไม่ได้อัปโหลดคีย์การตรวจสอบสิทธิ์ APNs ที่จำเป็นหรือคีย์ดังกล่าวหมดอายุแล้ว ตรวจสอบความถูกต้องของข้อมูลเข้าสู่ระบบสำหรับการพัฒนาและข้อมูลเข้าสู่ระบบสำหรับเวอร์ชันที่ใช้งานจริง
การตรวจสอบสิทธิ์ไม่สำเร็จ AUTHENTICATION_FAILED ตรวจสอบสิทธิ์กับบริการ Push ภายนอกไม่สำเร็จ ตรวจสอบว่าคุณใช้ใบรับรอง Web Push ที่ถูกต้องหรือไม่

ไวยากรณ์ข้อความขาขึ้น

ข้อความขาต้นคือข้อความที่แอปไคลเอ็นต์ส่งไปยังเซิร์ฟเวอร์แอป ปัจจุบันมีเพียง XMPP เท่านั้นที่รองรับการรับส่งข้อความจากต้นทาง ดูข้อมูลเพิ่มเติมเกี่ยวกับการส่งข้อความจากแอปไคลเอ็นต์ได้ในเอกสารประกอบของแพลตฟอร์ม

การตีความข้อความ XMPP ขาเข้า

ตารางต่อไปนี้อธิบายช่องในบท XMPP ที่ FCM สร้างขึ้นเพื่อตอบสนองคําขอข้อความจากแอปไคลเอ็นต์

ตารางที่ 5 ข้อความ XMPP ขาขึ้น

พารามิเตอร์ การใช้งาน คำอธิบาย
from ต้องระบุ, สตริง

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

ค่านี้คือโทเค็นการลงทะเบียนของแอปไคลเอ็นต์
category ต้องระบุ, สตริง พารามิเตอร์นี้ระบุชื่อแพ็กเกจแอปพลิเคชันของแอปไคลเอ็นต์ที่ส่งข้อความ
message_id ต้องระบุ, สตริง พารามิเตอร์นี้จะระบุรหัสที่ไม่ซ้ำกันของข้อความ
data ไม่บังคับ, สตริง พารามิเตอร์นี้ระบุคู่คีย์-ค่าของเพย์โหลดข้อความ

กำลังส่งข้อความ ACK

ตารางต่อไปนี้อธิบายการตอบกลับ ACK ที่เซิร์ฟเวอร์แอปคาดว่าจะส่งไปยัง FCM เพื่อตอบสนองต่อข้อความจากฝั่งต้นทางที่เซิร์ฟเวอร์แอปได้รับ

ตาราง 6 การตอบกลับข้อความ XMPP ขาขึ้น

พารามิเตอร์ การใช้งาน คำอธิบาย
to ต้องระบุ, สตริง

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

ค่าต้องเป็นโทเค็นการลงทะเบียนของแอปไคลเอ็นต์ที่ส่งข้อความขาเข้า
message_id ต้องระบุ, สตริง พารามิเตอร์นี้ระบุข้อความที่การตอบกลับมีไว้สำหรับ ค่าต้องเป็นค่า message_id จากข้อความขาเข้าที่เกี่ยวข้อง
message_type ต้องระบุ, สตริง พารามิเตอร์นี้ระบุข้อความ ack จากเซิร์ฟเวอร์แอปไปยัง CCS สำหรับข้อความขาเข้า ควรตั้งค่าเป็น ack เสมอ

FCM ข้อความเซิร์ฟเวอร์ (XMPP)

ข้อความนี้ส่งจาก FCM ไปยังเซิร์ฟเวอร์แอป ข้อความประเภทหลักที่ FCM ส่งไปยังเซิร์ฟเวอร์แอปมีดังนี้

  • การควบคุม: ข้อความที่ CCS สร้างขึ้นเหล่านี้บ่งบอกว่าต้องมีการดำเนินการจากเซิร์ฟเวอร์แอป

ตารางต่อไปนี้อธิบายช่องต่างๆ ที่รวมอยู่ในข้อความที่ CCS ส่งไปยังเซิร์ฟเวอร์แอป

ตาราง 7 FCM ข้อความควบคุม (XMPP)

พารามิเตอร์ การใช้งาน คำอธิบาย
ฟิลด์ทั่วไป
message_type ต้องระบุ, สตริง

พารามิเตอร์นี้ระบุประเภทของข้อความ: การควบคุม

เมื่อตั้งค่าเป็น control ข้อความจะมี control_type เพื่อระบุประเภทของข้อความควบคุม
control_type ไม่บังคับ, สตริง

พารามิเตอร์นี้ระบุประเภทข้อความควบคุมที่ส่งจาก FCM

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