โปรโตคอล 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 ไม่จำเป็น สตริง

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

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

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

ตัวเลือก
message_id จำเป็น, สตริง

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

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 สัปดาห์ สำหรับข้อมูลเพิ่มเติม โปรดดู การตั้งค่าอายุการใช้งานของข้อความ

dry_run ไม่จำเป็น, บูลีน

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

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

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

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

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

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

บน Android ผลลัพธ์ที่ได้คือ score Intent ที่มีชื่อพิเศษด้วยค่าสตริง 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 จะใช้รหัสช่องที่ระบุในรายการแอป

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

ตีความการตอบกลับข้อความ 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)
การลงทะเบียน APN ไม่ถูกต้อง INVALID_JSON สำหรับการลงทะเบียน iOS ให้ตรวจสอบว่าคำขอลงทะเบียนจากไคลเอนต์มีโทเค็น APN และรหัสแอปพลิเคชันที่ถูกต้อง
โทเค็นการลงทะเบียนไม่ถูกต้อง BAD_REGISTRATION ตรวจสอบรูปแบบของโทเค็นการลงทะเบียนที่คุณส่งไปยังเซิร์ฟเวอร์ ตรวจสอบให้แน่ใจว่าตรงกับโทเค็นการลงทะเบียนที่แอปไคลเอ็นต์ได้รับจากการลงทะเบียนกับ FCM อย่าตัดทอนหรือเพิ่มอักขระเพิ่มเติม
อุปกรณ์ที่ไม่ได้ลงทะเบียน DEVICE_UNREGISTERED โทเค็นการลงทะเบียนที่มีอยู่อาจหยุดใช้ไม่ได้ในหลายสถานการณ์ รวมถึง:
  • หากแอปไคลเอ็นต์ยกเลิกการลงทะเบียนกับ FCM
  • หากแอปไคลเอ็นต์ยกเลิกการลงทะเบียนโดยอัตโนมัติ ซึ่งอาจเกิดขึ้นได้หากผู้ใช้ถอนการติดตั้งแอปพลิเคชัน ตัวอย่างเช่น บน iOS หาก APN รายงานว่าโทเค็น APN ไม่ถูกต้อง
  • หากโทเค็นการลงทะเบียนหมดอายุ (เช่น Google อาจตัดสินใจรีเฟรชโทเค็นการลงทะเบียน หรือโทเค็น APN สำหรับอุปกรณ์หมดอายุ)
  • หากแอปไคลเอนต์ได้รับการอัปเดต แต่ไม่ได้กำหนดค่าเวอร์ชันใหม่ให้รับข้อความ
ในกรณีทั้งหมดเหล่านี้ ให้ลบโทเค็นการลงทะเบียนนี้ออกจากเซิร์ฟเวอร์แอปและหยุดใช้เพื่อส่งข้อความ
ผู้ส่งไม่ตรงกัน 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 ในกลไกการลองใหม่ของคุณ (เช่น หากคุณรอหนึ่งวินาทีก่อนลองอีกครั้งครั้งแรก ให้รออย่างน้อยสองวินาทีก่อนครั้งถัดไป จากนั้นสี่วินาที และอื่นๆ) หากคุณส่งข้อความหลายข้อความ ให้หน่วงเวลาแต่ละข้อความแยกกันด้วยจำนวนสุ่มเพิ่มเติมเพื่อหลีกเลี่ยงการออกคำขอใหม่สำหรับข้อความทั้งหมดในเวลาเดียวกัน
  • ควรตั้งค่าความล่าช้าในการลองใหม่ครั้งแรกเป็นหนึ่งวินาที

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

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

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

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

การตีความข้อความ XMPP อัปสตรีม

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

ตารางที่ 5 ข้อความ XMPP อัพสตรีม

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

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

ค่านี้คือโทเค็นการลงทะเบียนของแอปไคลเอนต์

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