פרוטוקול Firebase Cloud Messaging XMPP

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

priority אופציונלי, מחרוזת

קובע את העדיפות של ההודעה. ערכים חוקיים הם "רגיל" ו"גבוה". בפלטפורמות של אפל, אלה תואמים את סדר העדיפויות של APN 5 ו-10.

כברירת מחדל, הודעות התראה נשלחות בעדיפות גבוהה, והודעות נתונים נשלחות בעדיפות רגילה. עדיפות רגילה מייעלת את צריכת הסוללה של אפליקציית הלקוח ויש להשתמש בה אלא אם נדרשת אספקה ​​מיידית. עבור הודעות עם עדיפות רגילה, האפליקציה עשויה לקבל את ההודעה באיחור לא מוגדר.

כאשר הודעה נשלחת בעדיפות גבוהה, היא נשלחת מיד, והאפליקציה יכולה להציג התראה.

content_available אופציונלי, בוליאני

בפלטפורמות של Apple, השתמש בשדה זה כדי לייצג content-available במטען ה-APN. כאשר נשלחת התראה או הודעה וזה מוגדר כ- true , אפליקציית לקוח לא פעילה מתעוררת, וההודעה נשלחת דרך APNs כהתראה שקטה ולא דרך FCM. שים לב שהודעות שקטות ב-APNs אינן מובטחות שיימסרו, והן יכולות להיות תלויות בגורמים כמו המשתמש שמפעיל מצב צריכת חשמל נמוכה, יציאה מכוח האפליקציה וכו'. באנדרואיד, הודעות נתונים מעירות את האפליקציה כברירת מחדל. ב-Chrome, כרגע לא נתמך.

mutable_content אופציונלי, JSON בוליאני

בפלטפורמות של Apple, השתמש בשדה זה כדי לייצג mutable-content במטען ה-APN. כאשר הודעה נשלחת וזו מוגדרת כ- true , ניתן לשנות את תוכן ההודעה לפני הצגתה, באמצעות סיומת אפליקציית Notification Service . פרמטר זה יתעלם עבור אנדרואיד ואינטרנט.

time_to_live אופציונלי, מספר

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

dry_run אופציונלי, בוליאני

פרמטר זה, כאשר הוא מוגדר כ- true , מאפשר למפתחים לבדוק בקשה מבלי לשלוח הודעה.

ערך ברירת המחדל הוא false .

מטען
data אופציונלי, חפץ

פרמטר זה מציין את צמדי המפתח-ערך של מטען ההודעה.

לדוגמה, עם data:{"score":"3x1"}:

בפלטפורמות של Apple, אם ההודעה נמסרת על ידי APNs, היא מייצגת את שדות הנתונים המותאמים אישית. אם הוא מועבר על ידי FCM, הוא מיוצג כמילון ערך מפתח AppDelegate application:didReceiveRemoteNotification: .

ב-Android, זה גורם score נוסף בשם Intent עם ערך המחרוזת 3x1 .

המפתח לא צריך להיות מילה שמורה ("from", "message_type", או כל מילה שמתחילה ב-"google" או "gcm"). אל תשתמש באף אחת מהמילים המוגדרות בטבלה זו (כגון collapse_key ).

ערכים בסוגי מחרוזת מומלצים. עליך להמיר ערכים באובייקטים או בסוגי נתונים אחרים שאינם מחרוזים (למשל, מספרים שלמים או בוליאנים) למחרוזת.

notification אופציונלי, חפץ פרמטר זה מציין את צמדי המפתח-ערך המוגדרים מראש, גלויים למשתמש, של מטען ההודעות. ראה תמיכת מטען הודעות לפרטים. למידע נוסף על אפשרויות הודעות הודעה והודעות נתונים, ראה סוגי הודעות . אם מסופק מטען הודעה, או שהאפשרות content_available מוגדרת כ- true עבור הודעה למכשיר Apple, ההודעה נשלחת דרך APNs , אחרת היא נשלחת דרך FCM.

תמיכה במטען הודעות

הטבלאות הבאות מפרטות את המפתחות המוגדרים מראש הזמינים לבניית הודעות התראות עבור פלטפורמות אפל ואנדרואיד.

טבלה 2א. Apple - מקשים להודעות התראה

פָּרָמֶטֶר נוֹהָג תיאור
title אופציונלי, מחרוזת

כותרת ההודעה.

שדה זה אינו גלוי בטלפונים ובטאבלטים.

body אופציונלי, מחרוזת

גוף ההודעה.

sound אופציונלי, מחרוזת

הצליל שיש לנגן כאשר המכשיר מקבל את ההתראה.

מחרוזת המציינת קובצי קול בחבילה הראשית של אפליקציית הלקוח או בתיקיית Library/Sounds של מיכל הנתונים של האפליקציה. עיין בספריית המפתחים של iOS למידע נוסף.

badge אופציונלי, מחרוזת

ערך התג בסמל האפליקציה במסך הבית.

אם לא צוין, התג לא משתנה.

אם מוגדר ל 0 , התג יוסר.

click_action אופציונלי, מחרוזת

הפעולה המשויכת למשתמש לחץ על ההודעה.

מתאים category במטען ה-APNs.

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ב. אנדרואיד - מקשים להודעות התראה

פָּרָמֶטֶר נוֹהָג תיאור
title אופציונלי, מחרוזת

כותרת ההודעה.

body אופציונלי, מחרוזת

גוף ההודעה.

android_channel_id אופציונלי, מחרוזת

מזהה הערוץ של ההתראה (חדש באנדרואיד O).

האפליקציה חייבת ליצור ערוץ עם מזהה ערוץ זה לפני שמתקבלת התראה עם מזהה ערוץ זה.

אם לא תשלח את מזהה הערוץ הזה בבקשה, או אם מזהה הערוץ שסופק עדיין לא נוצר על ידי האפליקציה, FCM משתמש במזהה הערוץ שצוין במניפסט האפליקציה.

icon אופציונלי, מחרוזת

סמל ההודעה.

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

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 אופציונלי, מחרוזת

כתובת האתר לשימוש עבור סמל ההודעה.

click_action אופציונלי, מחרוזת

הפעולה המשויכת למשתמש לחץ על ההודעה.

עבור כל ערכי כתובת האתר, יש צורך ב-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, בדוק שבקשת הרישום מהלקוח מכילה אסימון APNs ומזהה אפליקציה חוקיים.
אסימון רישום לא חוקי BAD_REGISTRATION בדוק את הפורמט של אסימון הרישום שאתה מעביר לשרת. ודא שהוא תואם את אסימון הרישום שאפליקציית הלקוח מקבלת מההרשמה ל-FCM. אין לקטוע או להוסיף תווים נוספים.
מכשיר לא רשום DEVICE_UNREGISTERED אסימון רישום קיים עשוי להפסיק להיות תקף במספר תרחישים, כולל:
  • אם אפליקציית הלקוח מבטלת את הרישום ב-FCM.
  • אם אפליקציית הלקוח בוטלה באופן אוטומטי, מה שיכול לקרות אם המשתמש מסיר את ההתקנה של האפליקציה. לדוגמה, ב-iOS, אם APNs דיווחו על אסימון APNs כלא חוקי.
  • אם תוקף אסימון הרישום פג (לדוגמה, Google עשויה להחליט לרענן אסימוני רישום, או שתוקף ה-APNs פג עבור מכשירים).
  • אם אפליקציית הלקוח מעודכנת, אך הגרסה החדשה אינה מוגדרת לקבלת הודעות.
בכל המקרים הללו, הסר את אסימון הרישום הזה משרת האפליקציה והפסק להשתמש בו לשליחת הודעות.
השולח לא תואם SENDER_ID_MISMATCH אסימון רישום קשור לקבוצה מסוימת של שולחים. כאשר אפליקציית לקוח נרשמה ל-FCM, עליה לציין אילו שולחים מורשים לשלוח הודעות. עליך להשתמש באחד מאותם מזהי שולח בעת שליחת הודעות לאפליקציית הלקוח. אם תעבור לשולח אחר, אסימוני הרישום הקיימים לא יפעלו.
JSON לא חוקי INVALID_JSON בדוק שהודעת ה-JSON מעוצבת כהלכה ומכילה שדות חוקיים (לדוגמה, וודא שסוג הנתונים הנכון מועבר).
הודעה גדולה מדי INVALID_JSON בדוק שהגודל הכולל של נתוני המטען הכלולים בהודעה אינו חורג ממגבלות FCM: 4096 בתים עבור רוב ההודעות או 2048 בתים במקרה של הודעות לנושאים. זה כולל גם את המפתחות וגם את הערכים.
מפתח נתונים לא חוקי INVALID_JSON ודא שנתוני המטען אינם מכילים מפתח (כגון from , gcm או כל ערך עם קידומת google ) שנמצא בשימוש פנימי על ידי FCM. שים לב שמילים מסוימות (כגון collapse_key ) נמצאות בשימוש גם על ידי FCM אך מותרות במטען, ובמקרה זה ערך המטען מוחלף על ידי ערך FCM.
זמן לא חוקי לחיות INVALID_JSON בדוק שהערך המשמש ב- time_to_live הוא מספר שלם המייצג משך בשניות בין 0 ל-2,419,200 (4 שבועות).
הודעת ACK גרועה BAD_ACK בדוק שהודעת ack מעוצבת כהלכה לפני שתנסה שוב. ראה טבלה 6 לפרטים.
פסק זמן SERVICE_UNAVAILABLE

השרת לא הצליח לעבד את הבקשה בזמן. נסה שוב את אותה בקשה, אך עליך:

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

הערה: שולחים שגורמים לבעיות מסתכנים ברשימה השחורה.

שגיאת שרת פנימית INTERNAL_SERVER_
ERROR
השרת נתקל בשגיאה בעת ניסיון לעבד את הבקשה. תוכל לנסות שוב את אותה בקשה בהתאם לדרישות המפורטות ב"זמן קצוב" (ראה שורה למעלה).
קצב הודעת ההתקן חרג DEVICE_MESSAGE_RATE
_EXCEEDED
קצב ההודעות למכשיר מסוים גבוה מדי. צמצם את מספר ההודעות שנשלחו למכשיר זה, ואל תנסה לשלוח מחדש מיד למכשיר זה.
קצב הודעות נושאים חרג TOPICS_MESSAGE_RATE
_EXCEEDED
שיעור ההודעות למנויים לנושא מסוים גבוה מדי. צמצם את מספר ההודעות שנשלחו עבור נושא זה, ואל תנסה לשלוח מחדש מיד.
ניקוז חיבור CONNECTION_DRAINING לא ניתן היה לעבד את ההודעה כי החיבור מתרוקן. זה קורה כי מעת לעת, FCM צריך לסגור חיבור כדי לבצע איזון עומסים. נסה שוב את ההודעה דרך חיבור XMPP אחר.
אישורי APN לא חוקיים INVALID_APNS_CREDENTIAL לא ניתן לשלוח הודעה המיועדת למכשיר iOS מכיוון שמפתח האימות הנדרש של APNs לא הועלה או שפג תוקפו. בדוק את תקפות אישורי הפיתוח והייצור שלך.
אימות נכשל AUTHENTICATION_FAILED נכשל האימות עם שירותי דחיפה חיצוניים. בדוק אם אתה משתמש בתעודות הדחיפה הנכונות באינטרנט.

תחביר הודעות במעלה הזרם

הודעה במעלה הזרם היא הודעה שאפליקציית הלקוח שולחת לשרת האפליקציה. נכון לעכשיו רק XMPP תומך בהעברת הודעות במעלה הזרם. עיין בתיעוד של הפלטפורמה שלך למידע נוסף על שליחת הודעות מאפליקציות לקוח.

פירוש הודעת XMPP במעלה הזרם

הטבלה הבאה מתארת ​​את השדות ב-XMPP שיוצר על ידי FCM בתגובה לבקשות הודעות במעלה הזרם מיישומי לקוח.

טבלה 5 הודעות XMPP במעלה הזרם.

פָּרָמֶטֶר נוֹהָג תיאור
from חובה, מחרוזת

פרמטר זה מציין מי שלח את ההודעה.

הערך הוא אסימון הרישום של אפליקציית הלקוח.

category חובה, מחרוזת פרמטר זה מציין את שם חבילת האפליקציה של אפליקציית הלקוח ששלחה את ההודעה.
message_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 , ההודעה כוללת control_type כדי לציין את סוג הודעת הבקרה.

control_type אופציונלי, מחרוזת

פרמטר זה מציין את סוג הודעת הבקרה שנשלחה מ-FCM.

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