Join us for Firebase Summit on November 10, 2021. Tune in to learn how Firebase can help you accelerate app development, release with confidence, and scale with ease. Register

סביבת השרת שלך ו- FCM

צד השרת של Firebase Cloud Messaging מורכב משני רכיבים:

  • על החלק העורפי FCM שמספקת גוגל.
  • שרת האפליקציה שלך או סביבת שרת מהימן אחרת שבם פועלים היגיון השרת שלך, כגון פונקציות ענן עבור Firebase או סביבות ענן אחרות המנוהלת על ידי גוגל.

שרת האפליקציות שלך או סביבת השרת המהימן שולח בקשות הודעות לקצה האחורי של ה- FCM, המנתב הודעות לאפליקציות לקוח הפועלות במכשירי משתמשים.

דרישות לסביבת השרת המהימן

סביבת שרת האפליקציות שלך חייבת לעמוד בקריטריונים הבאים:

  • מסוגל לשלוח בקשות הודעה מעוצבות כראוי למערך האחורי של ה- FCM.
  • מסוגל להתמודד עם בקשות ולשלוח אותם שוב באמצעות גב-off מעריכים.
  • מסוגל לאחסן בצורה מאובטחת אישורי הרשאות שרת ואסימוני רישום לקוח.
  • עבור פרוטוקול XMPP (אם נעשה בו שימוש), השרת חייב להיות מסוגל ליצור מזהי הודעות כדי לזהות באופן ייחודי כל הודעה שהוא שולח (הקצה האחורי של ה- FCM HTTP יוצר מזהי הודעות ומחזיר אותם בתגובה). מזהי הודעות XMPP צריכים להיות ייחודיים לכל מזהה שולח.

בחירת אופציית שרת

תצטרך להחליט על דרך אינטראקציה עם שרתי FCM: או באמצעות SDK של ניהול Firebase או פרוטוקולי גלם. בגלל התמיכה שלה בשפות תכנות פופולריות ושיטות הנוחות שלה לטיפול באימות והרשאה, ה- SDK Admin SDB הוא השיטה המומלצת.

האפשרויות לאינטראקציה עם שרתי FCM כוללות את הדברים הבאים:
  • ה- SDK Admin Firebase, אשר יש תמיכה צומת , Java , Python , C # , ו Go .
  • FCM HTTP v1 API , המהווה את רוב מעודכן של אפשרויות פרוטוקול, באישור יותר בטוחה וגמישה יכולות העברת הודעות חוצה פלטפורמות (SDK של מנהל המערכת Firebase מבוססת על פרוטוקול זה מספק את כל היתרונות הגלומים).
  • המורשת HTTP פרוטוקול.
  • XMPP פרוטוקול בשרת. שים לב שאם אתה רוצה להשתמש בהודעות במעלה הזרם מיישומי הלקוח שלך, עליך להשתמש ב- XMPP.

מנהל SDK לניהול Firebase עבור FCM

ה- Admin FCM API מטפל באימות עם ה backend ומאפשר שליחת הודעות וניהול מנויים לנושאים. בעזרת ה- SDK לניהול Firebase תוכל:

  • שלח הודעות למכשירים בודדים
  • שלח הודעות לנושאים והצהרות תנאי התואמות נושא אחד או יותר.
  • הרשמה והתנתק ממכשירים לנושאים וממנה
  • בנה מטענים בהודעות המותאמים לפלטפורמות יעד שונות

ה- SDK Admin Node.js מספק שיטות לשליחת הודעות לקבוצות מכשירים.

כדי להגדיר את ה- SDK Admin Firebase, לראות מוסיפים את SDK של ניהול Firebase לשרת שלך . אם כבר יש לך פרויקט Firebase, להתחיל עם הוספת ה- SDK . ואז, ברגע SDK של ניהול Firebase מותקן, אתה יכול להתחיל היגיון בכתב בקשות שליחה לבנות .

פרוטוקולי שרת FCM

נכון לעכשיו, FCM מספקת את פרוטוקולי השרת הגולמיים הבאים:

שרת האפליקציות שלך יכול להשתמש בפרוטוקולים אלה בנפרד או במקביל. מכיוון שהוא המעודכן והגמיש ביותר לשליחת הודעות למספר פלטפורמות, מומלץ להשתמש ב- FCM HTTP v1 API בכל מקום אפשרי. אם הדרישות שלך כוללות הודעות במעלה הזרם ממכשירים לשרת, יהיה עליך ליישם את פרוטוקול XMPP.

הודעות XMPP שונות מהודעות HTTP בדרכים הבאות:

  • הודעות במעלה/במורד הזרם
    • HTTP: רק במורד הזרם, ענן למכשיר.
    • XMPP: במעלה הזרם והמורד (מכשיר לענן, ענן למכשיר).
  • העברת הודעות (סינכרוני או אסינכרוני)
    • 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. לפרטים על אפשרויות בכותרת ובגוף, לראות בקשות לשלוח לשרת App Build

יישום פרוטוקול שרת XMPP

מטען ה- JSON להודעות FCM דומה לפרוטוקול HTTP, למעט יוצאים מן הכלל הבאים:

  • אין תמיכה במספר נמענים.
  • FCM מוסיף בתחום message_id , אשר נדרש. מזהה זה מזהה באופן ייחודי את ההודעה בחיבור XMPP. ACK או נאק מ FCM משתמש message_id לזהות הודעה שנשלחה משרתי אפליקציה כדי FCM. לכן, חשוב כי זה message_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

שגיאה ב- נאק הוא מסר XMPP קבוע שבו message_type הודעת המצב הוא "נאק". הודעת 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>

ראה הפניה לשרת לקבלת רשימה מלאה של קודי השגיאה נאק. אלא אם צוין אחרת, אין לנסות שוב הודעה NACKed. קודי שגיאה נאק צפוי להתייחס אליהם זהה INTERNAL_SERVER_ERROR .

שגיאת בית

אתה יכול גם לקבל שגיאת בית במקרים מסוימים. שגיאת בית מכילה:

  • קוד שגיאה של בית.
  • תיאור שגיאת בית (טקסט חופשי).

לדוגמה:

<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, פתיחת חיבור חדש במידת הצורך. עם זאת, עליך להשאיר את החיבור המקורי פתוח ולהמשיך לקבל הודעות שעלולות להגיע דרך החיבור (ולגשת אותן) - 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. מסר / ack לזרום.

לעומת זאת, כדי להימנע מעומס על שרת האפליקציות, FCM מפסיקה לשלוח אם יש יותר מדי הודעות לא מוכרות. לכן, שרת האפליקציות צריך "ACK" הודעות במעלה הזרם, המתקבלות מאפליקציית הלקוח באמצעות FCM, בהקדם האפשרי כדי לשמור על זרימה קבועה של הודעות נכנסות. מגבלת ההודעות הממתינות לעיל אינה חלה על ACK אלה. גם אם מספר ההודעות הממתינות יגיע ל -100, שרת האפליקציות צריך להמשיך לשלוח הודעות ACK עבור הודעות שהתקבלו מ- FCM כדי למנוע חסימת מסירה של הודעות חדשות במעלה הזרם.

ACK תקפים רק בהקשר של חיבור אחד. אם החיבור נסגר לפני שניתן יהיה להעביר הודעה ל- ACK, שרת האפליקציות צריך לחכות עד ש- FCM ישלח שוב את ההודעה במעלה הזרם לפני שיחזור אליה. באופן דומה, יש לשלוח שוב את כל ההודעות הממתינות שעבורן לא התקבל ACK/NACK מ- FCM לפני סגירת החיבור.