פרוטוקול HTTP של העברת הודעות בענן ב-Firebase

במסמך הזה מופיע מסמך עזר בנושא התחביר של HTTP שמשמש להעברת הודעות משרת האפליקציות לאפליקציות הלקוח דרך Firebase Cloud Messaging.

כשמשתמשים בפרוטוקול HTTP הקודם, שרת האפליקציה צריך להפנות את כל בקשות ה-HTTP לנקודת הקצה הזו:

https://fcm.googleapis.com/fcm/send

הפרמטרים והאפשרויות הזמינות מתחלקים לקטגוריות הרחבות הבאות:

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

בקטע הזה מוסבר התחביר לשליחת הודעות במורד הזרם ולפרש תגובות HTTP מ-Firebase Cloud Messaging.

הודעות HTTP במורד הזרם (JSON)

בטבלה הבאה מפורטים היעדים, האפשרויות והמטען הייעודי להודעות JSON ב-HTTP.

טבלה 1. מטרות, אפשרויות ומטען שימושי להודעות HTTP במורד הזרם (JSON).

פרמטר שימוש תיאור
יעדים
to אופציונלי, מחרוזת

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

הערך יכול להיות טוקן רישום של מכשיר, מפתח התראות של קבוצת מכשירים או נושא יחיד (עם הקידומת /topics/). כדי לשלוח לכמה נושאים, משתמשים בפרמטר condition.

registration_ids
אופציונלי, מערך של מחרוזות

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

הערך צריך להיות מערך של אסימוני רישום, שאליהם צריך לשלוח את הודעת ה-multicast. המערך חייב להכיל לפחות אסימון רישום אחד ולפחות 1,000 אסימוני רישום. כדי לשלוח הודעה למכשיר יחיד, משתמשים בפרמטר to.

מותר לשלוח הודעות Multicast רק באמצעות פורמט HTTP JSON.

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

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

תנאי נתמך: נושא, בפורמט '‎'yourTopic' in topics'‎. הערך הזה לא תלוי אותיות רישיות.

האופרטורים הנתמכים: &&, ‏ ||. אפשר להשתמש בשני אופרטורים לכל היותר בכל הודעה בנושא.
notification_key
הוצא משימוש		 אופציונלי, מחרוזת

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

הפרמטר הזה מזהה קבוצה של הודעות (למשל, עם collapse_key: "Updates Available") שאפשר לכווץ, כך שרק ההודעה האחרונה תישלח כשהעברה תתחדש. המטרה היא למנוע שליחת יותר מדי הודעות זהות כשהמכשיר חוזר לאינטרנט או הופך לפעיל.

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

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

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

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

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

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

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

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

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

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

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

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

ערך ברירת המחדל הוא false.
מטען ייעודי (payload)
data אופציונלי, אובייקט

הפרמטר הזה מציין את צמדי המפתח/ערך המותאמים אישית של עומס העבודה של ההודעה.

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

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

ב-Android, הפעולה הזו תוביל ליצירת פרמטר נוסף של כוונה בשם score עם ערך המחרוזת 3x1.

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

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

תמיכה בתוכן של ההתראות

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

טבלה 2a. iOS – מפתחות להודעות התראה

פרמטר שימוש תיאור
title אופציונלי, מחרוזת

כותרת ההתראה.

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

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

גוף הטקסט של ההתראה.

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

הצליל שיישמע כשהמכשיר יקבל את ההתראה.

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

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

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

אם לא צוין ערך, התג לא ישתנה.

אם הערך מוגדר כ-0, התג יוסר.

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

הפעולה שמשויכת לקליק של משתמש על ההתראה.

תואם ל-category במטען הייעודי (payload) של APNs.

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

כותרת המשנה של ההתראה.

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

המפתח למחרוזת הגוף במשאבי המחרוזות של האפליקציה, שמשמש להתאמה של טקסט הגוף ללוקליזציה הנוכחית של המשתמש.

תואם ל-loc-key במטען הייעודי (payload) של APNs.

למידע נוסף, ראו מידע על מפתחות של נתוני עומס (payload) ו התאמה של התוכן של ההתראות מרחוק לשוק המקומי.

body_loc_args אופציונלי, מערך JSON כמחרוזת

ערכים של מחרוזות משתנות שישמשו במקום מפרידי הפורמט ב-body_loc_key כדי להתאים את הטקסט בגוף להגדרות המקומיות הנוכחיות של המשתמש.

תואם ל-loc-args במטען הייעודי (payload) של APNs.

למידע נוסף, ראו מידע על מפתחות של נתוני עומס (payload) ו התאמה של התוכן של ההתראות מרחוק לשוק המקומי.

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

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

תואם ל-title-loc-key במטען הייעודי (payload) של APNs.

למידע נוסף, ראו מידע על מפתחות של נתוני עומס (payload) ו התאמה של התוכן של ההתראות מרחוק לשוק המקומי.

title_loc_args אופציונלי, מערך JSON כמחרוזת

ערכים של מחרוזות משתנות שישמשו במקום מפרידי הפורמט ב-title_loc_key כדי להתאים את טקסט השם ללוקאל הנוכחי של המשתמש.

תואם ל-title-loc-args במטען הייעודי (payload) של APNs.

למידע נוסף, ראו מידע על מפתחות של נתוני עומס (payload) ו התאמה של התוכן של ההתראות מרחוק לשוק המקומי.

טבלה 2ב. Android – מפתחות להודעות התראה

פרמטר שימוש תיאור
title אופציונלי, מחרוזת

כותרת ההתראה.

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

גוף הטקסט של ההתראה.

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

מזהה הערוץ של ההתראה (חדש ב-Android 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 אופציונלי, מחרוזת

כתובת ה-URL שתשמש לסמל ההתראה.

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

הפעולה שמשויכת לקליק של משתמש על ההתראה.

חובה להשתמש ב-HTTPS בכל ערכי כתובות ה-URL.

הודעות HTTP במורד הזרם (טקסט פשוט)

בטבלה הבאה מפורט התחביר של יעדים, אפשרויות ועומס שימושי בהודעות HTTP ב-downstream בטקסט ללא הצפנה.

טבלה 3 מטרות, אפשרויות ועומס שימושי להודעות HTTP בטקסט פשוט במורד הזרם.

פרמטר שימוש תיאור
יעדים
registration_id חובה, מחרוזת

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

שליחת הודעות לקבוצה (שליחת הודעה ליותר מאסימון רישום אחד) מותרת רק בפורמט HTTP JSON.
אפשרויות
collapse_key אופציונלי, מחרוזת פרטים נוספים זמינים בטבלה 1.
time_to_live אופציונלי, מספר פרטים נוספים זמינים בטבלה 1.
restricted_package_name אופציונלי, מחרוזת פרטים נוספים זמינים בטבלה 1.
dry_run אופציונלי, בוליאני פרטים נוספים זמינים בטבלה 1.
מטען ייעודי (payload)
data.<key> אופציונלי, מחרוזת

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

לדוגמה, ב-Android, הערך "data.score"."3x1" יניב פרמטר נוסף של כוונה בשם score עם ערך המחרוזת 3x1.

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

פרשנות של תגובה להודעה במורד הזרם

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

טבלה 4. כותרת התגובה להודעת HTTP במורד הזרם.

תגובה תיאור
200 ההודעה טופלה בהצלחה. גוף התגובה יכיל פרטים נוספים על סטטוס ההודעה, אבל הפורמט שלו יהיה תלוי בפורמט הבקשה – JSON או טקסט פשוט. פרטים נוספים זמינים בטבלה 5.
400 רלוונטי רק לבקשות JSON. הקוד הזה מציין שלא ניתן היה לנתח את הבקשה כ-JSON, או שהיא הכילה שדות לא חוקיים (לדוגמה, העברה של מחרוזת במקום מספר). הסיבה המדויקת לכישלון מתוארת בתגובה, וצריך לטפל בבעיה לפני שאפשר לנסות שוב את הבקשה.
401 אירעה שגיאה באימות חשבון השולח.
5xx שגיאות בטווח 500-599 (למשל 500 או 503) מציינות שאירעה שגיאה פנימית בקצה העורפי של FCM בזמן הניסיון לעבד את הבקשה, או שהשרת לא זמין באופן זמני (למשל בגלל תפוגת זמן). השולח צריך לנסות שוב מאוחר יותר, תוך שמירה על כל כותרת Retry-After שכלולה בתגובה. שרתי אפליקציות חייבים להטמיע השהיה מעריכית לפני ניסיון חוזר (exponential backoff).

בטבלה הבאה מפורטים השדות בגוף התגובה להודעה במורד הזרם (JSON).

טבלה 5. גוף התגובה של הודעת HTTP במורד הזרם (JSON).

פרמטר שימוש תיאור
multicast_id חובה, מספר מזהה (מספר) ייחודי שמזהה את הודעת ה-multicast.
success חובה, מספר מספר ההודעות שעברו עיבוד ללא שגיאה.
failure חובה, מספר מספר ההודעות שלא ניתן היה לעבד.
results חובה, מערך של אובייקטים מערך של אובייקטים שמייצגים את הסטטוס של ההודעות שעברו עיבוד. האובייקטים מפורטים באותו סדר כמו בבקשה (כלומר, לכל מזהה רישום בבקשה, התוצאה שלו מופיעה באותו אינדקס בתגובה).
  • message_id: מחרוזת שמציינת מזהה ייחודי לכל הודעה שעברה עיבוד בהצלחה.
  • error: מחרוזת שמציינת את השגיאה שהתרחשה במהלך עיבוד ההודעה לנמען. הערכים האפשריים מפורטים בטבלה 9.

טבלה 6. גוף התגובה של הודעת הנושא ב-HTTP (JSON).

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

טבלה 7. תגובת הצלחה לגוף התגובה של הודעת HTTP במורד הזרם (טקסט רגיל).

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

טבלה 8. תגובת שגיאה לגוף התגובה של הודעת HTTP במורד הזרם (טקסט רגיל).

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

קודי תגובה לשגיאות בהודעות במורד הזרם

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

טבלה 9. קודי תגובה לשגיאות בהודעות במורד הזרם.

שגיאה קוד HTTP מה מומלץ לעשות?
טוקן הרישום חסר 200 + error:MissingRegistration בודקים שהבקשה מכילה אסימון רישום (בשדה registration_id בהודעת טקסט פשוט, או בשדה to או registration_ids ב-JSON).
Invalid Registration Token 200 + error:InvalidRegistration בודקים את הפורמט של אסימון הרישום ששולחים לשרת. חשוב לוודא שהוא תואם לאסימון הרישום שאפליקציית הלקוח מקבלת מהרישום ב-Firebase Notifications. אין לקצר את השם או להוסיף תווים נוספים.
מכשיר לא רשום 200 + error:NotRegistered אסימון רישום קיים עשוי להפסיק להיות בתוקף בכמה תרחישים, כולל:
  • אם אפליקציית הלקוח מבטלת את הרישום ב-FCM.
  • אם אפליקציית הלקוח לא רשומה באופן אוטומטי, מה שיכול לקרות אם המשתמש מסיר את האפליקציה. לדוגמה, ב-iOS, אם שירות המשוב של APNs דיווח שהאסימון של APNs לא חוקי.
  • אם פג התוקף של אסימון הרישום (לדוגמה, Google עשויה להחליט לרענן את אסימוני הרישום, או שפג התוקף של אסימון APNs במכשירי iOS).
  • אם אפליקציית הלקוח עודכנה אבל הגרסה החדשה לא מוגדרת לקבל הודעות.
בכל המקרים האלה, צריך להסיר את טוקן הרישום הזה משרת האפליקציה ולהפסיק להשתמש בו כדי לשלוח הודעות.
שם חבילה לא חוקי 200 + error:InvalidPackageName מוודאים שההודעה נשלחה לאסימון רישום ששם החבילה שלו תואם לערך שהוענק בבקשה.
שגיאת אימות 401 לא ניתן היה לאמת את חשבון השולח ששימש לשליחת ההודעה. סיבות אפשריות:
  • כותרת ההרשאה חסרה או מכילה תחביר לא חוקי בבקשת ה-HTTP.
  • פרויקט Firebase שאליו שייך מפתח השרת שצוין שגוי.
  • מפתחות שרת מדור קודם בלבד – הבקשה הגיעה משרת שלא נכלל ברשימת ההיתרים של כתובות ה-IP של מפתחות השרת.
בודקים שהאסימון שאתם שולחים בכותרת האימות הוא מפתח השרת הנכון שמשויך לפרויקט. פרטים נוספים זמינים במאמר בדיקת התוקף של מפתח שרת . אם אתם משתמשים במפתח שרת מדור קודם, מומלץ לשדרג למפתח חדש ללא הגבלות IP. העברת מפתחות שרת מדור קודם
שולח לא תואם 200 + error:MismatchSenderId אסימון רישום מקושר לקבוצה מסוימת של שולחים. כשאפליקציית לקוח נרשמת ל-FCM, היא צריכה לציין אילו שולחים מורשים לשלוח הודעות. צריך להשתמש באחד ממזהי השולח האלה כששולחים הודעות לאפליקציית הלקוח. אם עוברים לשולח אחר, אסימוני ההרשמה הקיימים לא יפעלו.
JSON לא תקין 400 בודקים שההודעה בפורמט JSON תקינה ושהיא מכילה שדות חוקיים (למשל, מוודאים שסוג הנתונים הנכון מועבר).
פרמטרים לא חוקיים 400 + error:InvalidParameters בודקים שהשם והסוג של הפרמטרים שצוינו נכונים.
ההודעה גדולה מדי 200 + error:MessageTooBig חשוב לוודא שהגודל הכולל של נתוני עומס העבודה (payload) שכלולים בהודעה לא חורג מהמגבלות של FCM: 4096 בייטים ברוב ההודעות, או 2048 בייטים במקרה של הודעות לנושאים. כולל גם את המפתחות וגם את הערכים.
מפתח נתונים לא תקין 200 + שגיאה:
InvalidDataKey		 בודקים שנתוני המטען הייעודי לא מכילים מפתח (כמו from או gcm, או כל ערך שמתחיל ב-google) ש-FCM משתמש בו באופן פנימי. שימו לב שחלק מהמילים (כמו collapse_key) משמשות גם את FCM, אבל הן מותרות במטען הייעודי. במקרה כזה, הערך של המטען הייעודי יוחלף בערך של FCM.
זמן חיים לא חוקי 200 + error:InvalidTtl בודקים שהערך שצוין ב-time_to_live הוא מספר שלם שמייצג משך זמן בשניות בין 0 ל-2,419,200 (4 שבועות).
זמן קצוב לתפוגה 5xx או 200 + error:Unavailable

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

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

שולחים שגורמים לבעיות עלולים להיכלל ברשימת ההסרה.
שגיאת שרת פנימית 500 או 200 + error:InternalServerError השרת נתקל בשגיאה במהלך הניסיון לעבד את הבקשה. אפשר לנסות שוב את אותה בקשה בהתאם לדרישות שמפורטות בקטע 'זמן קצוב לתפוגה' (ראו שורה למעלה). אם השגיאה נמשכת, צריך לפנות לתמיכה של Firebase.
חרגת מהשיעור המרבי של שליחת הודעות מהמכשיר 200 + שגיאה:
DeviceMessageRate
Exceeded

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

כדאי לצמצם את מספר ההודעות שנשלחות למכשיר הזה ולהשתמש בהשהיה מעריכית לפני ניסיון חוזר לשליחה.
חריגה מקצב שליחת ההודעות בנושאים 200 + שגיאה:
TopicsMessageRate
Exceeded		 שיעור ההודעות שנשלחות למנויים בנושא מסוים גבוה מדי. מפחיתים את מספר ההודעות שנשלחות בנושא הזה ומשתמשים בהשהיה מעריכית לפני ניסיון חוזר כדי לנסות לשלוח שוב.
פרטי כניסה לא תקינים ל-APNs 200 + שגיאה:
InvalidApnsCredential 		לא ניתן היה לשלוח הודעה שמטורגטת למכשיר Apple כי מפתח האימות הנדרש של APNs לא הועלה או שתוקפו פג. בודקים את התקינות של פרטי הכניסה לפיתוח ולייצור.

ניהול קבוצות מכשירים

בטבלה הבאה מפורטים המפתחות ליצירת קבוצות של מכשירים, להוספת חברים ולהסרת חברים. למידע נוסף, אפשר לעיין במדריך לפלטפורמה שלכם: iOS+ או Android.

טבלה 10. מפתחות ניהול של קבוצות מכשירים.

פרמטר שימוש תיאור
operation חובה, מחרוזת הפעולה להרצה.הערכים החוקיים הם create,‏ add ו-remove.
notification_key_name חובה, מחרוזת השם שהמשתמש נתן לקבוצת המכשירים שיוצרים או משנים.
notification_key חובה (למעט הפעולה create, מחרוזת המזהה הייחודי של קבוצת המכשירים. הערך הזה מוחזר בתגובה לפעולת create מוצלחת, והוא נדרש לכל הפעולות הבאות בקבוצת המכשירים.
registration_ids חובה, מערך של מחרוזות האסימונים של המכשיר שרוצים להוסיף או להסיר. אם תסירו את כל אסימוני ההרשמה הקיימים מקבוצת מכשירים, מערכת FCM תמחק את קבוצת המכשירים.