Firebase is back at Google I/O on May 10! Register now

เกี่ยวกับข้อความ FCM

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

Firebase Cloud Messaging (FCM) มีตัวเลือกและความสามารถในการส่งข้อความที่หลากหลาย ข้อมูลในหน้านี้มีไว้เพื่อช่วยให้คุณเข้าใจประเภทต่างๆ ของข้อความ FCM และสิ่งที่คุณสามารถทำได้กับข้อความเหล่านั้น

ประเภทข้อความ

ด้วย FCM คุณสามารถส่งข้อความสองประเภทไปยังลูกค้า:

  • ข้อความแจ้งเตือน บางครั้งคิดว่าเป็น "ข้อความที่แสดง" FCM SDK จะจัดการสิ่งเหล่านี้โดยอัตโนมัติ
  • ข้อความข้อมูลซึ่งจัดการโดยแอปไคลเอนต์

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

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

  1. ในสภาพแวดล้อมที่เชื่อถือได้ เช่น Cloud Functions หรือเซิร์ฟเวอร์แอปของคุณ ให้ใช้ Admin SDK หรือ FCM Server Protocols : ตั้งค่าคีย์ notification อาจมีเพย์โหลดข้อมูลเสริม พับได้เสมอ

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

  2. ใช้ ตัวเขียนการแจ้งเตือน : ป้อนข้อความ ชื่อเรื่อง ฯลฯ แล้วส่ง เพิ่มเพย์โหลดข้อมูลเสริมโดยระบุข้อมูลที่กำหนดเอง
ข้อความข้อมูล แอปไคลเอนต์มีหน้าที่ในการประมวลผลข้อความข้อมูล ข้อความข้อมูลมีเฉพาะคู่คีย์-ค่าที่กำหนดเองโดยไม่มีชื่อคีย์ที่สงวนไว้ (ดูด้านล่าง) ในสภาพแวดล้อมที่เชื่อถือได้ เช่น Cloud Functions หรือเซิร์ฟเวอร์แอปของคุณ ให้ใช้ Admin SDK หรือ FCM Server Protocols : ตั้งค่าคีย์ data เท่านั้น

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

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

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

สำหรับการทดสอบหรือเพื่อการตลาดและการมีส่วนร่วมอีกครั้งของผู้ใช้ คุณสามารถ ส่งข้อความแจ้งเตือนโดยใช้คอนโซล Firebase คอนโซล Firebase มี การทดสอบ A/B ที่ใช้การวิเคราะห์เพื่อช่วยคุณปรับแต่งและปรับปรุงข้อความทางการตลาด

ในการส่งข้อความแจ้งเตือนทางโปรแกรมโดยใช้ Admin SDK หรือโปรโตคอล FCM ให้ตั้งค่าคีย์ notification ด้วยชุดตัวเลือกคีย์-ค่าที่กำหนดไว้ล่วงหน้าที่จำเป็นสำหรับส่วนที่ผู้ใช้มองเห็นได้ของข้อความแจ้งเตือน ตัวอย่างเช่น นี่คือข้อความแจ้งเตือนในรูปแบบ JSON ในแอป IM ผู้ใช้สามารถคาดหวังที่จะเห็นข้อความที่มีชื่อเรื่องว่า "โปรตุเกส vs. เดนมาร์ก" และข้อความ "การจับคู่ที่ยอดเยี่ยม!" บนอุปกรณ์:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

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

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

ข้อความข้อมูล

ตั้งค่าคีย์ที่เหมาะสมกับคู่คีย์-ค่าที่คุณกำหนดเองเพื่อส่งเพย์โหลดข้อมูลไปยังแอปไคลเอ็นต์

ตัวอย่างเช่น ต่อไปนี้เป็นข้อความในรูปแบบ JSON ในแอป IM เดียวกับด้านบน ซึ่งข้อมูลจะถูกห่อหุ้มไว้ในคีย์ data ทั่วไป และแอปไคลเอนต์คาดว่าจะตีความเนื้อหา:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

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

การเข้ารหัสสำหรับข้อความข้อมูล

Android Transport Layer (ดู สถาปัตยกรรม FCM ) ใช้การเข้ารหัสแบบจุดต่อจุด คุณอาจตัดสินใจเพิ่มการเข้ารหัสจากต้นทางถึงปลายทางให้กับข้อความข้อมูล ทั้งนี้ขึ้นอยู่กับความต้องการของคุณ FCM ไม่มีโซลูชันแบบครบวงจร อย่างไรก็ตาม มีโซลูชันภายนอกที่พร้อมใช้งาน เช่น Capillary หรือ DTLS

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

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

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

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

นี่คือข้อความในรูปแบบ JSON ที่มีทั้งคีย์ notification และคีย์ data :

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

ปรับแต่งข้อความข้ามแพลตฟอร์ม

ทั้ง SDK ผู้ดูแลระบบ Firebase และโปรโตคอล FCM v1 HTTP อนุญาตให้คำขอข้อความของคุณตั้งค่าฟิลด์ทั้งหมดที่มีในวัตถุ message ซึ่งรวมถึง:

  • ชุดของฟิลด์ทั่วไปที่อินสแตนซ์ของแอป ทั้งหมด ที่ได้รับข้อความจะตีความ
  • ชุดฟิลด์เฉพาะแพลตฟอร์ม เช่น AndroidConfig และ WebpushConfig ตีความโดยอินสแตนซ์ของแอปที่ทำงานบนแพลตฟอร์มที่ระบุเท่านั้น

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

เมื่อใดควรใช้ฟิลด์ทั่วไป

ใช้ฟิลด์ทั่วไปเมื่อคุณ:

  • การกำหนดเป้าหมายอินสแตนซ์ของแอปใน ทุก แพลตฟอร์ม — Apple, Android และเว็บ
  • การส่งข้อความไปยังหัวข้อ

อินสแตนซ์ของแอปทั้งหมด โดยไม่คำนึงถึงแพลตฟอร์ม สามารถตีความฟิลด์ทั่วไปต่อไปนี้:

เมื่อใดควรใช้ฟิลด์เฉพาะแพลตฟอร์ม

ใช้ฟิลด์เฉพาะแพลตฟอร์มเมื่อคุณต้องการ:

  • ส่งฟิลด์ไปยังแพลตฟอร์มเฉพาะเท่านั้น
  • ส่งฟิลด์เฉพาะแพลตฟอร์ม นอกเหนือจาก ฟิลด์ทั่วไป

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

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

ตัวอย่าง: ข้อความแจ้งเตือนพร้อมตัวเลือกการส่งเฉพาะแพลตฟอร์ม

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

  • กำหนดระยะเวลาในการใช้งานที่ยาวนานสำหรับแพลตฟอร์ม Android และเว็บ ในขณะที่ตั้งค่าลำดับความสำคัญของข้อความ APN (แพลตฟอร์ม Apple) เป็นการตั้งค่าต่ำ
  • ตั้งค่าคีย์ที่เหมาะสมเพื่อกำหนดผลลัพธ์ที่ผู้ใช้แตะบนการแจ้งเตือนบน Android และ Apple — click_action และ category ตามลำดับ
{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

ดู เอกสารอ้างอิง HTTP v1 สำหรับรายละเอียดทั้งหมดเกี่ยวกับคีย์ที่มีอยู่ในบล็อกเฉพาะแพลตฟอร์มในเนื้อหาข้อความ สำหรับข้อมูลเพิ่มเติมเกี่ยวกับการสร้างคำขอส่งที่มีเนื้อหาข้อความ ดู ที่การสร้างคำขอส่ง

ตัวเลือกการจัดส่ง

FCM จัดเตรียมชุดตัวเลือกการส่งเฉพาะสำหรับข้อความที่ส่งไปยังอุปกรณ์ Android และอนุญาตให้ใช้ตัวเลือกที่คล้ายกันบนแพลตฟอร์มและเว็บของ Apple ตัวอย่างเช่น พฤติกรรมข้อความแบบ "พับได้" ได้รับการสนับสนุนบน Android ผ่านทาง FCM's collapse_key , บน Apple ผ่านทาง apns-collapse-id , และบน JavaScript/เว็บ ผ่าน Topic สำหรับรายละเอียด โปรดดูคำอธิบายในส่วนนี้และเอกสารอ้างอิงที่เกี่ยวข้อง

ข้อความที่ไม่สามารถยุบตัวและยุบได้

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

กรณีการใช้งานทั่วไปของข้อความที่ไม่สามารถยุบได้ ได้แก่ ข้อความแชทหรือข้อความสำคัญ ตัวอย่างเช่น ในแอป IM คุณต้องการส่งทุกข้อความ เนื่องจากทุกข้อความมีเนื้อหาที่แตกต่างกัน

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

ข้อความที่ยุบได้ คือข้อความที่อาจถูกแทนที่ด้วยข้อความใหม่หากยังไม่ได้ส่งไปยังอุปกรณ์

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

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

ข้อความหัวข้อที่ไม่มีเพย์โหลดสามารถยุบได้ตามค่าเริ่มต้น ข้อความแจ้งเตือนจะยุบได้เสมอและจะไม่สนใจพารามิเตอร์ collapse_key

ฉันควรใช้อันไหน

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

ใช้สถานการณ์ วิธีส่ง
ไม่ยุบตัว ทุกข้อความมีความสำคัญต่อแอปไคลเอนต์และจำเป็นต้องส่ง ยกเว้นข้อความแจ้งเตือน ข้อความทั้งหมดจะไม่ยุบตามค่าเริ่มต้น
พับได้ เมื่อมีข้อความที่ใหม่กว่าซึ่งแสดงข้อความที่เก่ากว่าซึ่งเกี่ยวข้องกับแอปไคลเอนต์ FCM จะแทนที่ข้อความที่เก่ากว่า ตัวอย่างเช่น: ข้อความที่ใช้ในการเริ่มต้นการซิงค์ข้อมูลจากเซิร์ฟเวอร์ หรือข้อความแจ้งเตือนที่ล้าสมัย ตั้งค่าพารามิเตอร์ที่เหมาะสมในคำขอข้อความของคุณ:
  • collapseKey บน Android
  • apns-collapse-id บน Apple
  • Topic บนเว็บ
  • collapse_key ในโปรโตคอลเดิม (ทุกแพลตฟอร์ม)

การตั้งค่าลำดับความสำคัญของข้อความ

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

  • ลำดับความสำคัญปกติ ข้อความสำคัญปกติจะถูกส่งทันทีเมื่อแอปอยู่เบื้องหน้า สำหรับแอปที่อยู่เบื้องหลัง การจัดส่งอาจล่าช้า สำหรับข้อความที่มีเวลาน้อย เช่น การแจ้งเตือนอีเมลใหม่ การซิงค์ UI ของคุณ หรือการซิงค์ข้อมูลแอปในเบื้องหลัง ให้เลือกลำดับความสำคัญการส่งตามปกติ

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

ต่อไปนี้คือตัวอย่างข้อความลำดับความสำคัญปกติที่ส่งผ่านโปรโตคอล FCM HTTP v1 เพื่อแจ้งสมาชิกนิตยสารว่ามีเนื้อหาใหม่ให้ดาวน์โหลด:

{
  "message":{
    "topic":"subscriber-updates",
    "notification":{
      "body" : "This week's edition is now available.",
      "title" : "NewsMagazine.com",
    },
    "data" : {
      "volume" : "3.21.15",
      "contents" : "http://www.news-magazine.com/world-week/21659772"
    },
    "android":{
      "priority":"normal"
    },
    "apns":{
      "headers":{
        "apns-priority":"5"
      }
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      }
    }
  }
}

สำหรับรายละเอียดเฉพาะแพลตฟอร์มเพิ่มเติมเกี่ยวกับการตั้งค่าลำดับความสำคัญของข้อความ:

การกำหนดอายุการใช้งานของข้อความ

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

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

บน Android และ Web/JavaScript คุณสามารถระบุอายุการใช้งานสูงสุดของข้อความได้ ค่าต้องเป็นระยะเวลาตั้งแต่ 0 ถึง 2,419,200 วินาที (28 วัน) และสอดคล้องกับระยะเวลาสูงสุดที่ FCM จัดเก็บและพยายามส่งข้อความ คำขอที่ไม่มีฟิลด์นี้เริ่มต้นเป็นระยะเวลาสูงสุดสี่สัปดาห์

ต่อไปนี้คือการใช้งานที่เป็นไปได้สำหรับคุณสมบัตินี้:

  • สายเรียกเข้าวิดีโอแชท
  • เหตุการณ์คำเชิญที่หมดอายุ
  • กิจกรรมในปฏิทิน

ข้อดีอีกประการของการระบุอายุการใช้งานของข้อความคือ FCM จะไม่ควบคุมข้อความโดยมีค่าเวลาถึงเป็น 0 วินาที กล่าวอีกนัยหนึ่ง FCM รับประกันความพยายามอย่างเต็มที่สำหรับข้อความที่ต้องส่ง "ทันทีหรือไม่เลย" โปรดทราบว่าค่า time_to_live เป็น 0 หมายความว่าข้อความที่ไม่สามารถส่งได้ทันทีจะถูกยกเลิก อย่างไรก็ตาม เนื่องจากไม่เคยจัดเก็บข้อความดังกล่าวไว้ จึงมีเวลาแฝงที่ดีที่สุดสำหรับการส่งข้อความแจ้งเตือน

ตัวอย่างคำขอที่มี TTL มีดังนี้

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    },
    "apns":{
      "headers":{
        "apns-expiration":"1604750400"
      }
    },
    "android":{
      "ttl":"4500s"
    },
    "webpush":{
      "headers":{
        "TTL":"4500"
      }
    }
  }
}

อายุการใช้งานของข้อความ

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

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

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

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

หากต้องการข้อมูลเชิงลึกเพิ่มเติมเกี่ยวกับการส่งข้อความ:

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

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

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

การควบคุมและปรับขนาด

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

การควบคุมปริมาณข้อความที่ยุบได้

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

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

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

เราจำกัดข้อความที่ยุบได้ไว้ที่ 20 ข้อความต่อแอปต่ออุปกรณ์ โดยเติม 1 ข้อความทุก 3 นาที

การควบคุมเซิร์ฟเวอร์ XMPP

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

สำหรับแต่ละโครงการ FCM อนุญาตการเชื่อมต่อแบบขนาน 2,500 รายการ

อัตราข้อความสูงสุดไปยังอุปกรณ์เครื่องเดียว

สำหรับ Android คุณสามารถส่งข้อความได้สูงสุด 240 ข้อความ/นาที และ 5,000 ข้อความ/ชั่วโมง ไปยังอุปกรณ์เดียว เกณฑ์ที่สูงนี้มีขึ้นเพื่อให้มีการเข้าชมอย่างรวดเร็วในระยะสั้น เช่น เมื่อผู้ใช้โต้ตอบอย่างรวดเร็วผ่านการแชท ขีดจำกัดนี้ป้องกันข้อผิดพลาดในการส่งลอจิกจากการที่แบตเตอรี่ในอุปกรณ์หมดโดยไม่ตั้งใจ

สำหรับ iOS เราจะส่งคืนข้อผิดพลาดเมื่ออัตราเกินขีดจำกัด APN

ขีด จำกัด ข้อความอัปสตรีม

เราจำกัด ข้อความอัปสตรีมไว้ ที่ 1,500,000/นาทีต่อโปรเจ็กต์ เพื่อหลีกเลี่ยงไม่ให้เซิร์ฟเวอร์ปลายทางอัปสตรีมโอเวอร์โหลด

เราจำกัดข้อความอัปสตรีมต่ออุปกรณ์ที่ 1,000/นาที เพื่อป้องกันแบตเตอรี่หมดจากพฤติกรรมของแอพที่ไม่ดี

ขีดจำกัดข้อความหัวข้อ

อัตราการเพิ่ม/ลบการสมัครรับข้อมูลหัวข้อจำกัดอยู่ที่ 3,000 QPS ต่อโครงการ

สำหรับอัตราการส่งข้อความ โปรดดู Fanout Throttling

การควบคุม Fanout

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

การกระจายของข้อความไม่ได้เกิดขึ้นทันที ดังนั้นบางครั้งคุณจึงมีการกระจายของข้อความหลายรายการพร้อมกัน เราจำกัดจำนวน fanouts ข้อความพร้อมกันต่อโครงการที่ 1,000 หลังจากนั้น เราอาจปฏิเสธคำขอเพิ่มเติมหรือเลื่อนเวลาออกไปจนกว่าคำขอบางส่วนที่กำลังดำเนินการอยู่จะเสร็จสิ้น

อัตรา fanout ที่ทำได้จริงจะขึ้นอยู่กับจำนวนโปรเจกต์ที่ร้องขอ fanout ในเวลาเดียวกัน อัตรา Fanout 10,000 QPS สำหรับแต่ละโครงการไม่ใช่เรื่องแปลก แต่ตัวเลขดังกล่าวไม่ได้รับประกัน และเป็นผลมาจากโหลดทั้งหมดในระบบ สิ่งสำคัญคือต้องทราบว่าความสามารถในการกระจายที่มีอยู่นั้นถูกแบ่งตามโปรเจ็กต์ ไม่ใช่จากคำขอการกระจายทั้งหมด ดังนั้น หากโปรเจกต์ของคุณมี fanouts สองรายการที่กำลังดำเนินการอยู่ แต่ละ fanout จะเห็นเพียงครึ่งหนึ่งของอัตราการ fanout ที่มี วิธีที่แนะนำในการเพิ่มความเร็ว fanout สูงสุดคือให้ fanout ที่กำลังดำเนินการอยู่เพียง 1 รายการต่อครั้ง

พอร์ต FCM และไฟร์วอลล์ของคุณ

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

สำหรับอุปกรณ์ที่เชื่อมต่อบนเครือข่ายของคุณ FCM ไม่ได้ให้ IP ที่เฉพาะเจาะจง เนื่องจากช่วง IP ของเราเปลี่ยนแปลงบ่อยเกินไป และกฎไฟร์วอลล์ของคุณอาจล้าสมัย ซึ่งส่งผลต่อประสบการณ์ของผู้ใช้ ตามหลักการแล้ว รายการพอร์ตที่อนุญาต 5228-5230 & 443 โดยไม่มีข้อจำกัด IP อย่างไรก็ตาม หากคุณต้องมีการจำกัด IP คุณควรอนุญาตรายการที่อยู่ IP ทั้งหมดที่อยู่ใน goog.json รายการขนาดใหญ่นี้ได้รับการอัปเดตเป็นประจำ และขอแนะนำให้คุณอัปเดตกฎของคุณเป็นประจำทุกเดือน ปัญหาที่เกิดจากข้อจำกัด IP ของไฟร์วอลล์มักไม่ต่อเนื่องและวินิจฉัยได้ยาก

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

พอร์ต TCP ที่จะเปิด:

  • 5228
  • 5229
  • 5230
  • 443

ชื่อโฮสต์ที่จะเปิด:

  • mtalk.google.com
  • mtalk4.google.com
  • mtalk-staging.google.com
  • mtalk-dev.google.com
  • alt1-mtalk.google.com
  • alt2-mtalk.google.com
  • alt3-mtalk.google.com
  • alt4-mtalk.google.com
  • alt5-mtalk.google.com
  • alt6-mtalk.google.com
  • alt7-mtalk.google.com
  • alt8-mtalk.google.com
  • android.apis.google.com
  • device-provisioning.googleapis.com
  • firebaseinstallations.googleapis.com

การแปลที่อยู่เครือข่ายและ/หรือไฟร์วอลล์ Stateful Packet Inspection:

หากเครือข่ายของคุณใช้ Network Address Translation (NAT) หรือ Stateful Packet Inspection (SPI) ให้ใช้งานการเชื่อมต่อของเราผ่านพอร์ต 5228-5230 โดยใช้เวลา 30 นาทีขึ้นไป สิ่งนี้ช่วยให้เราสามารถเชื่อมต่อที่เชื่อถือได้ในขณะที่ลดการใช้แบตเตอรี่ของอุปกรณ์เคลื่อนที่ของผู้ใช้

ข้อมูลรับรอง

คุณอาจต้องใช้ข้อมูลรับรองต่อไปนี้จากโปรเจ็กต์ Firebase ทั้งนี้ขึ้นอยู่กับฟีเจอร์ FCM ที่คุณใช้:

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

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

รหัสผู้ส่ง ค่าตัวเลขที่ไม่ซ้ำกันที่สร้างขึ้นเมื่อคุณสร้างโปรเจ็กต์ Firebase ซึ่งมีอยู่ในแท็บ Cloud Messaging ของแผง การตั้งค่า คอนโซล Firebase รหัสผู้ส่งใช้เพื่อระบุผู้ส่งแต่ละรายที่สามารถส่งข้อความไปยังแอปไคลเอนต์ได้
โทเค็นการเข้าถึง โทเค็น OAuth 2.0 อายุสั้นที่อนุญาตคำขอไปยัง HTTP v1 API โทเค็นนี้เชื่อมโยงกับบัญชีบริการที่เป็นของโครงการ Firebase ของคุณ หากต้องการสร้างและหมุนเวียนโทเค็นการเข้าถึง ให้ทำตามขั้นตอนที่อธิบายไว้ใน Authorize Send Requests
รหัสเซิร์ฟเวอร์ (สำหรับโปรโตคอลดั้งเดิม)

คีย์เซิร์ฟเวอร์ที่อนุญาตให้เซิร์ฟเวอร์แอปของคุณเข้าถึงบริการของ Google รวมถึงการส่งข้อความผ่านโปรโตคอลดั้งเดิมของ Firebase Cloud Messaging คุณได้รับรหัสเซิร์ฟเวอร์เมื่อคุณสร้างโปรเจ็กต์ Firebase คุณสามารถดูได้ในแท็บ Cloud Messaging ของแผง การตั้งค่า คอนโซล Firebase

ข้อสำคัญ: อย่ารวมรหัสเซิร์ฟเวอร์ไว้ที่ใดก็ได้ในรหัสไคลเอนต์ของคุณ นอกจากนี้ ตรวจสอบให้แน่ใจว่าใช้คีย์เซิร์ฟเวอร์เท่านั้นในการอนุญาตเซิร์ฟเวอร์แอปของคุณ คีย์ Android, แพลตฟอร์ม Apple และเบราว์เซอร์ถูกปฏิเสธโดย FCM

,

Firebase Cloud Messaging (FCM) มีตัวเลือกและความสามารถในการส่งข้อความที่หลากหลาย ข้อมูลในหน้านี้มีไว้เพื่อช่วยให้คุณเข้าใจประเภทต่างๆ ของข้อความ FCM และสิ่งที่คุณสามารถทำได้กับข้อความเหล่านั้น

ประเภทข้อความ

ด้วย FCM คุณสามารถส่งข้อความสองประเภทไปยังลูกค้า:

  • ข้อความแจ้งเตือน บางครั้งคิดว่าเป็น "ข้อความที่แสดง" FCM SDK จะจัดการสิ่งเหล่านี้โดยอัตโนมัติ
  • ข้อความข้อมูลซึ่งจัดการโดยแอปไคลเอนต์

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

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

  1. ในสภาพแวดล้อมที่เชื่อถือได้ เช่น Cloud Functions หรือเซิร์ฟเวอร์แอปของคุณ ให้ใช้ Admin SDK หรือ FCM Server Protocols : ตั้งค่าคีย์ notification อาจมีเพย์โหลดข้อมูลเสริม พับได้เสมอ

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

  2. ใช้ ตัวเขียนการแจ้งเตือน : ป้อนข้อความ ชื่อเรื่อง ฯลฯ แล้วส่ง เพิ่มเพย์โหลดข้อมูลเสริมโดยระบุข้อมูลที่กำหนดเอง
ข้อความข้อมูล แอปไคลเอนต์มีหน้าที่ในการประมวลผลข้อความข้อมูล ข้อความข้อมูลมีเฉพาะคู่คีย์-ค่าที่กำหนดเองโดยไม่มีชื่อคีย์ที่สงวนไว้ (ดูด้านล่าง) ในสภาพแวดล้อมที่เชื่อถือได้ เช่น Cloud Functions หรือเซิร์ฟเวอร์แอปของคุณ ให้ใช้ Admin SDK หรือ FCM Server Protocols : ตั้งค่าคีย์ data เท่านั้น

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

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

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

สำหรับการทดสอบหรือเพื่อการตลาดและการมีส่วนร่วมอีกครั้งของผู้ใช้ คุณสามารถ ส่งข้อความแจ้งเตือนโดยใช้คอนโซล Firebase คอนโซล Firebase มี การทดสอบ A/B ที่ใช้การวิเคราะห์เพื่อช่วยคุณปรับแต่งและปรับปรุงข้อความทางการตลาด

ในการส่งข้อความแจ้งเตือนทางโปรแกรมโดยใช้ Admin SDK หรือโปรโตคอล FCM ให้ตั้งค่าคีย์ notification ด้วยชุดตัวเลือกคีย์-ค่าที่กำหนดไว้ล่วงหน้าที่จำเป็นสำหรับส่วนที่ผู้ใช้มองเห็นได้ของข้อความแจ้งเตือน ตัวอย่างเช่น นี่คือข้อความแจ้งเตือนในรูปแบบ JSON ในแอป IM ผู้ใช้สามารถคาดหวังที่จะเห็นข้อความที่มีชื่อเรื่องว่า "โปรตุเกส vs. เดนมาร์ก" และข้อความ "การจับคู่ที่ยอดเยี่ยม!" บนอุปกรณ์:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

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

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

ข้อความข้อมูล

ตั้งค่าคีย์ที่เหมาะสมกับคู่คีย์-ค่าที่คุณกำหนดเองเพื่อส่งเพย์โหลดข้อมูลไปยังแอปไคลเอ็นต์

ตัวอย่างเช่น ต่อไปนี้เป็นข้อความในรูปแบบ JSON ในแอป IM เดียวกับด้านบน ซึ่งข้อมูลจะถูกห่อหุ้มไว้ในคีย์ data ทั่วไป และแอปไคลเอนต์คาดว่าจะตีความเนื้อหา:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

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

การเข้ารหัสสำหรับข้อความข้อมูล

Android Transport Layer (ดู สถาปัตยกรรม FCM ) ใช้การเข้ารหัสแบบจุดต่อจุด คุณอาจตัดสินใจเพิ่มการเข้ารหัสจากต้นทางถึงปลายทางให้กับข้อความข้อมูล ทั้งนี้ขึ้นอยู่กับความต้องการของคุณ FCM ไม่มีโซลูชันแบบครบวงจร อย่างไรก็ตาม มีโซลูชันภายนอกที่พร้อมใช้งาน เช่น Capillary หรือ DTLS

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

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

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

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

นี่คือข้อความในรูปแบบ JSON ที่มีทั้งคีย์ notification และคีย์ data :

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

ปรับแต่งข้อความข้ามแพลตฟอร์ม

ทั้ง SDK ผู้ดูแลระบบ Firebase และโปรโตคอล FCM v1 HTTP อนุญาตให้คำขอข้อความของคุณตั้งค่าฟิลด์ทั้งหมดที่มีในวัตถุ message ซึ่งรวมถึง:

  • ชุดของฟิลด์ทั่วไปที่อินสแตนซ์ของแอป ทั้งหมด ที่ได้รับข้อความจะตีความ
  • ชุดฟิลด์เฉพาะแพลตฟอร์ม เช่น AndroidConfig และ WebpushConfig ตีความโดยอินสแตนซ์ของแอปที่ทำงานบนแพลตฟอร์มที่ระบุเท่านั้น

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

เมื่อใดควรใช้ฟิลด์ทั่วไป

ใช้ฟิลด์ทั่วไปเมื่อคุณ:

  • การกำหนดเป้าหมายอินสแตนซ์ของแอปใน ทุก แพลตฟอร์ม — Apple, Android และเว็บ
  • การส่งข้อความไปยังหัวข้อ

อินสแตนซ์ของแอปทั้งหมด โดยไม่คำนึงถึงแพลตฟอร์ม สามารถตีความฟิลด์ทั่วไปต่อไปนี้:

เมื่อใดควรใช้ฟิลด์เฉพาะแพลตฟอร์ม

ใช้ฟิลด์เฉพาะแพลตฟอร์มเมื่อคุณต้องการ:

  • ส่งฟิลด์ไปยังแพลตฟอร์มเฉพาะเท่านั้น
  • ส่งฟิลด์เฉพาะแพลตฟอร์ม นอกเหนือจาก ฟิลด์ทั่วไป

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

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

Example: notification message with platform-specific delivery options

The following v1 send request sends a common notification title and content to all platforms, but also sends some platform-specific overrides. Specifically, the request:

  • sets a long time-to-live for Android and Web platforms, while setting the APNs (Apple platforms) message priority to a low setting
  • sets the appropriate keys to define the result of a user tap on the notification on Android and Apple — click_action , and category , respectively.
{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body. For more information about building send requests that contain the message body, see Build Send Requests .

Delivery options

FCM provides a specific set of delivery options for messages sent to Android devices, and allows for similar options on Apple platforms and web. For example, "collapsible" message behavior is supported on Android via FCM's collapse_key , on Apple via apns-collapse-id , and on JavaScript/Web via Topic . For details, see descriptions in this section and related reference documentation.

Non-collapsible and collapsible messages

A non-collapsible message denotes that each individual message is delivered to the device. A non-collapsible message delivers some useful content, as opposed to a collapsible message like a content-free "ping" to the mobile app to contact the server to fetch data.

Some typical use cases of non-collapsible messages are chat messages or critical messages. For example, in an IM app, you would want to deliver every message, because every message has different content.

For Android there is a limit of 100 messages that can be stored without collapsing. If the limit is reached, all stored messages are discarded. When the device is back online, it receives a special message indicating that the limit was reached. The app can then handle the situation properly, typically by requesting a full sync from the app server.

A collapsible message is a message that may be replaced by a new message if it has yet to be delivered to the device.

A common use cases of collapsible messages are messages used to tell a mobile app to sync data from the server. An example would be a sports app that updates users with the latest score. Only the most recent message is relevant.

To mark a message as collapsible on Android, include the collapse_key parameter in the message payload. By default, the collapse key is the app package name registered in the Firebase console. The FCM server can simultaneously store four different collapsible messages per device, each with a different collapse key. If you exceed this number, FCM only keeps four collapse keys, with no guarantees about which ones are kept.

Topic messages with no payload are collapsible by default. Notification messages are always collapsible and will ignore the collapse_key parameter.

Which should I use?

Collapsible messages are a better choice from a performance standpoint, provided your app doesn't need to use non-collapsible messages. However, if you use collapsible messages, remember that FCM only allows a maximum of four different collapse keys to be used by FCM per registration token at any given time. You must not exceed this number, or it could cause unpredictable consequences.

Use scenario How to send
Non-collapsible Every message is important to the client app and needs to be delivered. Except for notification messages, all messages are non-collapsible by default.
Collapsible When there is a newer message that renders an older, related message irrelevant to the client app, FCM replaces the older message. For example: messages used to initiate a data sync from the server, or outdated notification messages. Set the appropriate parameter in your message request:
  • collapseKey on Android
  • apns-collapse-id on Apple
  • Topic on Web
  • collapse_key in legacy protocols (all platforms)

Setting the priority of a message

You have two options for assigning delivery priority to downstream messages: normal and high priority. Though the behavior differs slightly across platforms, delivery of normal and high priority messages works like this:

  • Normal priority. Normal priority messages are delivered immediately when the app is in the foreground. For backgrounded apps, delivery may be delayed. For less time-sensitive messages, such as notifications of new email, keeping your UI in sync, or syncing app data in the background, choose normal delivery priority.

  • High priority. FCM attempts to deliver high priority messages immediately even if the device is in Doze mode. High priority messages are for time-sensitive, user visible content.

Here is an example of a normal priority message sent via the FCM HTTP v1 protocol to notify a magazine subscriber that new content is available to download:

{
  "message":{
    "topic":"subscriber-updates",
    "notification":{
      "body" : "This week's edition is now available.",
      "title" : "NewsMagazine.com",
    },
    "data" : {
      "volume" : "3.21.15",
      "contents" : "http://www.news-magazine.com/world-week/21659772"
    },
    "android":{
      "priority":"normal"
    },
    "apns":{
      "headers":{
        "apns-priority":"5"
      }
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      }
    }
  }
}

For more platform-specific detail on setting message priority:

Setting the lifespan of a message

FCM usually delivers messages immediately after they are sent. However, this might not always be possible. For example, if the platform is Android, the device could be turned off, offline, or otherwise unavailable. Or FCM might intentionally delay messages to prevent an app from consuming excessive resources and negatively affecting battery life.

When this happens, FCM stores the message and delivers it as soon as it's feasible. While this is fine in most cases, there are some apps for which a late message might as well never be delivered. For example, if the message is an incoming call or video chat notification, it is meaningful only for a short period of time before the call is terminated. Or if the message is an invitation to an event, it is useless if received after the event has ended.

On Android and Web/JavaScript, you can specify the maximum lifespan of a message. The value must be a duration from 0 to 2,419,200 seconds (28 days), and it corresponds to the maximum period of time for which FCM stores and attempts to deliver the message. Requests that don't contain this field default to the maximum period of four weeks.

Here are some possible uses for this feature:

  • Video chat incoming calls
  • Expiring invitation events
  • Calendar events

Another advantage of specifying the lifespan of a message is that FCM never throttles messages with a time-to-live value of 0 seconds. In other words, FCM guarantees best effort for messages that must be delivered "now or never." Keep in mind that a time_to_live value of 0 means messages that can't be delivered immediately are discarded. However, because such messages are never stored, this provides the best latency for sending notification messages.

Here is an example of a request that includes TTL:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    },
    "apns":{
      "headers":{
        "apns-expiration":"1604750400"
      }
    },
    "android":{
      "ttl":"4500s"
    },
    "webpush":{
      "headers":{
        "TTL":"4500"
      }
    }
  }
}

Lifetime of a message

When an app server posts a message to FCM and receives a message ID back, it does not mean that the message was already delivered to the device. Rather, it means that it was accepted for delivery. What happens to the message after it is accepted depends on many factors.

In the best-case scenario, if the device is connected to FCM, the screen is on and there are no throttling restrictions, the message is delivered right away.

If the device is connected but in Doze, a low priority message is stored by FCM until the device is out of Doze. And that's where the collapse_key flag plays a role: if there is already a message with the same collapse key (and registration token) stored and waiting for delivery, the old message is discarded and the new message takes its place (that is, the old message is collapsed by the new one). However, if the collapse key is not set, both the new and old messages are stored for future delivery.

If the device is not connected to FCM, the message is stored until a connection is established (again respecting the collapse key rules). When a connection is established, FCM delivers all pending messages to the device. If the device never gets connected again (for instance, if it was factory reset), the message eventually times out and is discarded from FCM storage. The default timeout is four weeks, unless the time_to_live flag is set.

To get more insight into the delivery of a message:

    To get more insight into the delivery of messages on Android or Apple platforms, see the FCM reporting dashboard , which records the number of messages sent and opened on Apple and Android devices, along with data for "impressions" (notifications seen by users) for Android apps.

For Android devices with direct channel messaging enabled, if the device has not connected to FCM for more than one month, FCM still accepts the message but immediately discards it. If the device connects within four weeks of the last data message you sent to it, your client receives the onDeletedMessages() callback. The app can then handle the situation properly, typically by requesting a full sync from the app server.

Finally, when FCM attempts to deliver a message to the device and the app was uninstalled, FCM discards that message right away and invalidates the registration token. Future attempts to send a message to that device results in a NotRegistered error.

Throttling and scaling

Our goal is to always deliver every message sent via FCM. However, delivering every message sometimes results in a poor overall user experience. In other cases, we need to provide boundaries to ensure that FCM provides a scalable service for all senders.

Collapsible message throttling

As described above, collapsible messages are content-free notifications designed to collapse on top of each other. In the event that a developer is repeating the same message to an app too frequently, we delay (throttle) messages to reduce the impact on a user's battery.

For example, if you send large numbers of new email sync requests to a single device, we might delay the next email sync request a few minutes so that the device can sync at a lower average rate. This throttling is done strictly to limit the battery impact experienced by the user.

If your use case requires high burst send patterns, then non-collapsible messages may be the right choice. For such messages, make sure to include the content in such messages in order to reduce the battery cost.

We limit collapsible messages to a burst of 20 messages per app per device, with a refill of 1 message every 3 minutes.

XMPP server throttling

We limit the rate that you can connect to FCM XMPP servers to 400 connections per minute per project. This shouldn't be an issue for message delivery, but it is important for ensuring the stability of our system.

For each project, FCM allows 2500 connections in parallel.

Maximum message rate to a single device

For Android, you can send up to 240 messages/minute and 5,000 messages/hour to a single device. This high threshold is meant to allow for short term bursts of traffic, such as when users are interacting rapidly over chat. This limit prevents errors in sending logic from inadvertently draining the battery on a device.

For iOS, we return an error when the rate exceeds APNs limits.

Upstream message limit

We limit upstream messages at 1,500,000/minute per project to avoid overloading upstream destination servers.

We limit upstream messages per device at 1,000/minute to protect against battery drain from bad app behavior.

Topic message limit

The topic subscription add/remove rate is limited to 3,000 QPS per project.

For message sending rates, see Fanout Throttling .

Fanout throttling

Message fanout is the process of sending a message to multiple devices, such as when you target topics and groups, or when you use the Notifications composer to target audiences or user segments.

Message fanout is not instantaneous and so occasionally you have multiple fanouts in progress concurrently. We limit the number of concurrent message fanouts per project to 1,000. After that, we may reject additional fanout requests or defer the fanout of the requests until some of the already in progress fanouts complete.

The actual achievable fanout rate is influenced by the number of projects requesting fanouts at the same time. A fanout rate of 10,000 QPS for an individual project is not uncommon, but that number is not a guarantee and is a result of the total load on the system. It is important to note that the available fanout capacity is divided among projects and not across fanout requests. So, if your project has two fanouts in progress, then each fanout will only see half of the available fanout rate. The recommended way to maximize your fanout speed is to only have one active fanout in progress at a time.

FCM ports and your firewall

If your organization has a firewall to restrict traffic to or from the Internet, you need to configure it to allow mobile devices to connect with FCM in order for devices on your network to receive messages. FCM typically uses port 5228, but it sometimes uses 443, 5229, and 5230.

For devices connecting on your network, FCM doesn't provide specific IPs because our IP range changes too frequently and your firewall rules could get out of date, impacting your users' experience. Ideally, allowlist ports 5228-5230 & 443 with no IP restrictions. However, if you must have an IP restriction, you should allowlist all of the IP addresses listed in goog.json . This large list is updated regularly, and you are recommended to update your rules on a monthly basis. Problems caused by firewall IP restrictions are often intermittent and difficult to diagnose.

We do offer a set of domain names that can be allowlisted instead of IP addresses. Those hostnames are listed below. If we start using additional hostnames, we will update the list here. Using domain names for your firewall rule may or may not be functional in your firewall device.

TCP ports to open:

  • 5228
  • 5229
  • 5230
  • 443

Hostnames to open:

  • mtalk.google.com
  • mtalk4.google.com
  • mtalk-staging.google.com
  • mtalk-dev.google.com
  • alt1-mtalk.google.com
  • alt2-mtalk.google.com
  • alt3-mtalk.google.com
  • alt4-mtalk.google.com
  • alt5-mtalk.google.com
  • alt6-mtalk.google.com
  • alt7-mtalk.google.com
  • alt8-mtalk.google.com
  • android.apis.google.com
  • device-provisioning.googleapis.com
  • firebaseinstallations.googleapis.com

Network Address Translation and/or Stateful Packet Inspection firewalls:

If your network implements Network Address Translation (NAT) or Stateful Packet Inspection (SPI), implement a 30 minute or larger timeout for our connections over ports 5228-5230. This enables us to provide reliable connectivity while reducing the battery consumption of your users' mobile devices.

Credentials

Depending on which FCM features you implement, you may need the following credentials from your Firebase project:

Project ID A unique identifier for your Firebase project, used in requests to the FCM v1 HTTP endpoint. This value is available in the Firebase console Settings pane.
Registration token

A unique token string that identifies each client app instance. The registration token is required for single device and device group messaging. Note that registration tokens must be kept secret.

Sender ID A unique numerical value created when you create your Firebase project, available in the Cloud Messaging tab of the Firebase console Settings pane. The sender ID is used to identify each sender that can send messages to the client app.
Access token A short-lived OAuth 2.0 token that authorizes requests to the HTTP v1 API. This token is associated with a service account that belongs to your Firebase project. To create and rotate access tokens, follow the steps described in Authorize Send Requests .
Server key (for legacy protocols)

A server key that authorizes your app server for access to Google services, including sending messages via the Firebase Cloud Messaging legacy protocols. You obtain the server key when you create your Firebase project. You can view it in the Cloud Messaging tab of the Firebase console Settings pane.

Important: Do not include the server key anywhere in your client code. Also, make sure to use only server keys to authorize your app server. Android, Apple platform, and browser keys are rejected by FCM.