Check out what’s new from Firebase at Google I/O 2022. Learn more

สภาพแวดล้อมเซิร์ฟเวอร์และ FCM . ของคุณ

ฝั่งเซิร์ฟเวอร์ของ Firebase Cloud Messaging ประกอบด้วยสององค์ประกอบ:

  • แบ็กเอนด์ FCM ที่ให้บริการโดย Google
  • เซิร์ฟเวอร์แอป ของคุณหรือ สภาพแวดล้อมเซิร์ฟเวอร์ที่เชื่อถือได้ อื่นๆ ที่ตรรกะของเซิร์ฟเวอร์ทำงาน เช่น Cloud Functions for Firebase หรือสภาพแวดล้อมระบบคลาวด์อื่นๆ ที่จัดการโดย Google

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

ข้อกำหนดสำหรับสภาพแวดล้อมเซิร์ฟเวอร์ที่เชื่อถือได้

สภาพแวดล้อมเซิร์ฟเวอร์แอปของคุณต้องเป็นไปตามเกณฑ์ต่อไปนี้:

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

การเลือกตัวเลือกเซิร์ฟเวอร์

คุณจะต้องตัดสินใจวิธีโต้ตอบกับเซิร์ฟเวอร์ FCM ไม่ว่าจะเป็นการใช้ Firebase Admin SDK หรือโปรโตคอลดิบ เนื่องจากมีการรองรับในภาษาการเขียนโปรแกรมยอดนิยมและวิธีการอำนวยความสะดวกในการจัดการการตรวจสอบสิทธิ์และการให้สิทธิ์ Firebase Admin SDK จึงเป็นวิธีที่แนะนำ

ตัวเลือกสำหรับการโต้ตอบกับเซิร์ฟเวอร์ FCM มีดังต่อไปนี้:
  • Firebase Admin SDK ซึ่งรองรับ Node , Java , Python , C# และ Go
  • FCM HTTP v1 API ซึ่งเป็นตัวเลือกโปรโตคอลที่ทันสมัยที่สุด พร้อมการอนุญาตที่ปลอดภัยยิ่งขึ้นและความ สามารถในการส่งข้อความข้ามแพลตฟอร์มที่ ยืดหยุ่น (Firebase Admin SDK ใช้โปรโตคอลนี้และให้ข้อดีทั้งหมดโดยธรรมชาติ) เนื่องจากโดยทั่วไปแล้ว คุณลักษณะใหม่จะถูกเพิ่มไปยัง HTTP v1 API เท่านั้น เราจึงแนะนำให้ใช้ API นี้สำหรับกรณีการใช้งานส่วนใหญ่
  • โปรโตคอล HTTP ดั้งเดิม
  • โปรโตคอลเซิร์ฟเวอร์ XMPP โปรดทราบว่าหากคุณต้องการใช้การรับส่งข้อความอัปสตรีมจากแอปพลิเคชันไคลเอนต์ของคุณ คุณต้องใช้ XMPP

Firebase Admin SDK สำหรับ FCM

Admin FCM API จัดการการตรวจสอบสิทธิ์กับแบ็กเอนด์และอำนวยความสะดวกในการส่งข้อความและจัดการการสมัครรับข้อมูลหัวข้อ ด้วย Firebase Admin SDK คุณสามารถ:

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

Admin Node.js SDK จัดเตรียมวิธีการส่งข้อความไปยังกลุ่มอุปกรณ์

ในการตั้งค่า Firebase Admin SDK โปรดดู ที่ เพิ่ม Firebase Admin SDK ไปยังเซิร์ฟเวอร์ของคุณ หากคุณมีโปรเจ็กต์ Firebase อยู่แล้ว ให้เริ่มด้วย Add the SDK จากนั้น เมื่อติดตั้ง Firebase Admin SDK แล้ว คุณสามารถเริ่มเขียนตรรกะเพื่อ สร้างคำขอส่ง

โปรโตคอลเซิร์ฟเวอร์ FCM

ปัจจุบัน FCM มีโปรโตคอลเซิร์ฟเวอร์ดิบเหล่านี้:

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

การส่งข้อความ XMPP แตกต่างจากการส่งข้อความ HTTP ในลักษณะต่อไปนี้:

  • ข้อความต้นน้ำ/ปลายน้ำ
    • HTTP: ดาวน์สตรีมเท่านั้น ระบบคลาวด์ต่ออุปกรณ์
    • XMPP: ต้นน้ำและปลายน้ำ (device-to-cloud, cloud-to-device)
  • ข้อความ (ซิงโครนัสหรืออะซิงโครนัส)
    • HTTP: ซิงโครนัส เซิร์ฟเวอร์แอปส่งข้อความเป็นคำขอ HTTP POST และรอการตอบกลับ กลไกนี้เป็นแบบซิงโครนัสและบล็อกผู้ส่งจากการส่งข้อความอื่นจนกว่าจะได้รับการตอบกลับ
    • XMPP: อะซิงโครนัส เซิร์ฟเวอร์แอปส่ง/รับข้อความไปยัง/จากอุปกรณ์ทั้งหมดด้วยความเร็วเต็มบรรทัดผ่านการเชื่อมต่อ XMPP แบบถาวร เซิร์ฟเวอร์การเชื่อมต่อ XMPP ส่งการตอบรับหรือการแจ้งเตือนความล้มเหลว (ในรูปแบบของข้อความ XMPP ที่เข้ารหัส ACK และ NACK JSON พิเศษ) แบบอะซิงโครนัส
  • JSON
    • HTTP: ข้อความ JSON ที่ส่งเป็น HTTP POST
    • XMPP: ข้อความ JSON ที่ห่อหุ้มในข้อความ XMPP
  • ข้อความธรรมดา
    • HTTP: ข้อความธรรมดาที่ส่งเป็น HTTP POST
    • XMPP: ไม่รองรับ
  • ดาวน์สตรีมแบบหลายผู้รับส่งไปยังโทเค็นการลงทะเบียนหลายรายการ
    • HTTP: รองรับในรูปแบบข้อความ JSON
    • XMPP: ไม่รองรับ

การใช้โปรโตคอลเซิร์ฟเวอร์ HTTP

ในการส่งข้อความ เซิร์ฟเวอร์แอปจะออกคำขอ POST ด้วยส่วนหัว HTTP และเนื้อหา HTTP ที่ประกอบด้วยคู่ค่าคีย์ JSON สำหรับรายละเอียดเกี่ยวกับตัวเลือกส่วนหัวและเนื้อหา โปรดดูที่ Build App Server ส่งคำขอ

การใช้โปรโตคอลเซิร์ฟเวอร์ XMPP

เพย์โหลด JSON สำหรับข้อความ FCM นั้นคล้ายกับโปรโตคอล HTTP โดยมีข้อยกเว้นดังต่อไปนี้:

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

นอกจากข้อความ FCM ปกติแล้ว ข้อความควบคุมยังถูกส่ง ซึ่งระบุโดยฟิลด์ message_type ในออบเจ็กต์ JSON ค่าสามารถเป็นได้ทั้ง 'ack' หรือ 'nack' หรือ 'control' (ดูรูปแบบด้านล่าง) เซิร์ฟเวอร์ของคุณสามารถละเว้นข้อความ FCM ใดๆ ที่มี message_type ที่ไม่รู้จักได้

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

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

ดูการ อ้างอิงโปรโตคอล สำหรับรายการพารามิเตอร์ข้อความทั้งหมด

แบบคำขอ

ข้อความพร้อมเพย์โหลด — ข้อความแจ้งเตือน

นี่คือบท XMPP สำหรับข้อความแจ้งเตือน:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
     "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
     "notification": {
        "title": "Portugal vs. Denmark”,
        "body”: "5 to 1”
      },
      "time_to_live":"600"
  }
  </gcm>
</message>

ข้อความพร้อมเพย์โหลด — ข้อความข้อมูล

นี่คือบท XMPP ที่มีข้อความ JSON จากเซิร์ฟเวอร์แอปถึง FCM:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
      "message_id":"m-1366082849205" // new required field
      "data":
      {
          "hello":"world",
      }
      "time_to_live":"600",
  }
  </gcm>
</message>

รูปแบบการตอบกลับ

การตอบสนองของ FCM สามารถมีได้สามรูปแบบ อันแรกคือข้อความ 'แอก' ปกติ แต่เมื่อการตอบกลับมีข้อผิดพลาด ข้อความสามารถใช้รูปแบบต่างๆ ได้ 2 รูปแบบ ดังอธิบายด้านล่าง

ข้อความ ACK

นี่คือบท XMPP ที่มีข้อความ ACK/NACK จาก FCM ไปยังเซิร์ฟเวอร์แอป:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

ข้อความ NACK

ข้อผิดพลาด NACK คือข้อความ XMPP ปกติซึ่งข้อความสถานะ message_type คือ "nack" ข้อความ NACK ประกอบด้วย:

  • รหัสข้อผิดพลาด NACK
  • คำอธิบายข้อผิดพลาด NACK

ด้านล่างนี้เป็นตัวอย่างบางส่วน

การลงทะเบียนไม่ถูกต้อง:

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationToken",
    "error":"BAD_REGISTRATION",
    "error_description":"Invalid token on 'to' field: SomeInvalidRegistrationId"
  }
  </gcm>
</message>

JSON ไม่ถูกต้อง:

<message>
 <gcm xmlns="google:mobile:data">
 {
   "message_type":"nack",
   "message_id":"msgId1",
   "from":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
   "error":"INVALID_JSON",
   "error_description":"InvalidJson: JSON_TYPE_ERROR : Field \"time_to_live\" must be a JSON java.lang.Number: abc"
 }
 </gcm>
</message>

เกินอัตราข้อความของอุปกรณ์:

<message id="...">
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"REGID",
    "error":"DEVICE_MESSAGE_RATE_EXCEEDED",
    "error_description":"Downstream message rate exceeded for this registration id"
  }
  </gcm>
</message>

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

ข้อผิดพลาดของบท

คุณอาจได้รับข้อผิดพลาดของบทในบางกรณี ข้อผิดพลาดของบทประกอบด้วย:

  • รหัสข้อผิดพลาด Stanza
  • คำอธิบายข้อผิดพลาดของ Stanza (ข้อความฟรี)

ตัวอย่างเช่น:

<message id="3" type="error" to="123456789@fcm.googleapis.com/ABC">
  <gcm xmlns="google:mobile:data">
     {"random": "text"}
  </gcm>
  <error code="400" type="modify">
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
      InvalidJson: JSON_PARSING_ERROR : Missing Required Field: message_id\n
    </text>
  </error>
</message>

ควบคุมข้อความ

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

ข้อความ CONNECTION_DRAINING มีลักษณะดังนี้:

<message>
  <data:gcm xmlns:data="google:mobile:data">
  {
    "message_type":"control"
    "control_type":"CONNECTION_DRAINING"
  }
  </data:gcm>
</message>

CONNECTION_DRAINING เป็น control_type เดียวที่ได้รับการสนับสนุนในขณะนี้

การควบคุมการไหล

ทุกข้อความที่ส่งไปยัง FCM จะได้รับการตอบสนอง ACK หรือ NACK ข้อความที่ไม่ได้รับการตอบกลับอย่างใดอย่างหนึ่งเหล่านี้ถือว่ารอดำเนินการ หากจำนวนข้อความที่รอดำเนินการถึง 100 เซิร์ฟเวอร์แอปควรหยุดส่งข้อความใหม่และรอให้ FCM รับทราบข้อความที่รอดำเนินการที่มีอยู่บางส่วนดังแสดงในรูปที่ 1:

ไดอะแกรมโดยละเอียดของโฟลว์การควบคุมระหว่าง FCM และเซิร์ฟเวอร์แอป

รูปที่ 1. กระแสข้อความ/แอก

ในทางกลับกัน เพื่อหลีกเลี่ยงไม่ให้เซิร์ฟเวอร์แอปทำงานหนักเกินไป FCM จะหยุดส่งหากมีข้อความที่ไม่ได้รับการตอบรับมากเกินไป ดังนั้น เซิร์ฟเวอร์แอปควร "ACK" ข้อความอัปสตรีมที่ได้รับจากแอปพลิเคชันไคลเอ็นต์ผ่าน FCM โดยเร็วที่สุดเพื่อรักษากระแสข้อความขาเข้าอย่างต่อเนื่อง ขีดจำกัดข้อความที่รอดำเนินการดังกล่าวใช้ไม่ได้กับ ACK เหล่านี้ แม้ว่าจำนวนข้อความที่รอดำเนินการจะถึง 100 ก็ตาม เซิร์ฟเวอร์แอปควรส่ง ACK ต่อไปสำหรับข้อความที่ได้รับจาก FCM เพื่อหลีกเลี่ยงการบล็อกการส่งข้อความอัปสตรีมใหม่

ACK ใช้ได้เฉพาะในบริบทของการเชื่อมต่อเดียวเท่านั้น หากการเชื่อมต่อถูกปิดก่อนที่จะสามารถ ACKed ข้อความได้ เซิร์ฟเวอร์แอปควรรอให้ FCM ส่งข้อความอัปสตรีมอีกครั้งก่อนที่จะทำ ACK อีกครั้ง ในทำนองเดียวกัน ข้อความที่รอดำเนินการทั้งหมดที่ไม่ได้รับ ACK/NACK จาก FCM ก่อนปิดการเชื่อมต่อ ควรส่งอีกครั้ง