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

זהירות: ב-20 ביוני 2023 הוצאנו משימוש את האפשרות לשלוח הודעות (כולל הודעות ב-upstream) באמצעות ממשקי ה-API הקודמים של FCM XMPP ו-HTTP, והם יוסרו החל מיוני 2024. אם אתם משתמשים בממשקי ה-API הקודמים לשליחה של FCM, מומלץ מאוד לעבור ל-HTTP v1 API או להשתמש ב-Admin SDK כדי ליצור בקשות שליחה.

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

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

כשמשתמשים בפרוטוקול 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 חריגה	שיעור ההודעות שנשלחות למנויים בנושא מסוים גבוה מדי. מפחיתים את מספר ההודעות שנשלחות בנושא הזה ומשתמשים בהשהיה מעריכית לפני ניסיון חוזר כדי לנסות לשלוח שוב.
פרטי כניסה לא תקינים ל-APNs	200 + שגיאה: InvalidApnsCredential	לא ניתן היה לשלוח הודעה שמטורגטת למכשיר Apple כי מפתח האימות הנדרש של APNs לא הועלה או שתוקפו פג. בודקים את התקינות של פרטי הכניסה לפיתוח ולייצור.

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

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

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

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