Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

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

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

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

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

דרישות עבור סביבת השרת המהימנה

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

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

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

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

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

Firkase Admin SDK עבור FCM

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

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

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

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

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

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

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

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

  • הודעות במעלה או במורד הזרם
    • HTTP: במורד הזרם בלבד, ענן למכשיר.
    • XMPP: במעלה ובזרם (מכשיר לענן, ענן למכשיר).
  • הודעות (סינכרוני או אסינכרוני)
    • HTTP: סינכרוני. שרתי האפליקציה שולחים הודעות כבקשות HTTP POST ומחכים לתגובה. מנגנון זה סינכרוני וחוסם את השולח מלשלוח הודעה נוספת עד לקבלת התגובה.
    • XMPP: אסינכרוני. שרתי האפליקציות שולחים / מקבלים הודעות אל / מכל המכשירים שלהם במהירות קו מלאה על חיבורי XMPP מתמשכים. שרת חיבור ה- XMPP שולח הודעות אישור או כשל (בצורה של הודעות XMPP מקודדות ACK ו- NACK JSON) בצורה אסינכרונית.
  • ג'סון
    • HTTP: הודעות JSON שנשלחו כ- HTTP POST.
    • XMPP: הודעות JSON המקופלות בהודעות XMPP.
  • טקסט רגיל
    • HTTP: הודעות טקסט רגילות שנשלחו כ- HTTP POST.
    • XMPP: לא נתמך.
  • שידור מולטי-שידור במורד הזרם למספר אסימוני רישום.
    • HTTP: נתמך בפורמט הודעות JSON.
    • XMPP: לא נתמך.

הטמעת פרוטוקול שרת HTTP

כדי לשלוח הודעה, שרת האפליקציה מוציא בקשת POST עם כותרת HTTP וגוף HTTP המורכב מזוגות ערכי מפתח של JSON. לפרטים אודות אפשרויות הכותרת והגוף, ראה בניית בקשות שליחה של שרת האפליקציות

יישום פרוטוקול שרת ה- 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 יכולות להיות שלוש צורות אפשריות. הראשון הוא מסר 'ack' רגיל. אך כאשר התגובה מכילה שגיאה, ישנן שתי צורות שונות שההודעה יכולה ללבוש, המתוארות להלן.

הודעת 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 הסטטוס 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 .

טעות בבית

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

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

לדוגמה:

<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:

איור 1. זרימת הודעה / ack.

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

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