פרוטוקול 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. לצפייה מידע נוסף זמין במדריך להעברת נתונים (מיגרציה) על היתרונות של גרסה 1 API ועל הוראות העברה.

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

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

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

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

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

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

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

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

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

פרמטר	שימוש	תיאור
יעדים
to	אופציונלי, מחרוזת	הפרמטר הזה מציין את הנמען של ההודעה. הערך יכול להיות אסימון רישום של מכשיר, מקש התראה או נושא יחיד (עם קידומת /topics/). כדי לשלוח בכמה נושאים, משתמשים condition.
registration_ids	אופציונלי, מערך של מחרוזות	הפרמטר הזה מציין את הנמען של הודעת multicast, הודעה שנשלחת ליותר מאסימון רישום אחד. הערך צריך להיות מערך של אסימוני רישום שאליהם צריך לשלוח את הודעת ה-multicast. המערך חייב להכיל לפחות 1 ולא יותר מ-1,000 אסימוני רישום. כדי לשלוח הודעה למכשיר אחד, משתמשים הפרמטר to. מותר לשלוח הודעות Multicast רק באמצעות פורמט HTTP JSON.
condition	אופציונלי, מחרוזת	הפרמטר הזה מציין ביטוי לוגי של תנאים שקובעים את היעד של ההודעה. תנאי נתמך: נושא, בפורמט 'yourTopic' בנושאים". הערך הזה לא תלוי רישיות. אופרטורים נתמכים: &&, ||. אפשר להשתמש בשני אופרטורים לכל היותר בכל הודעה בנושא.
notification_key הוצא משימוש	אופציונלי, מחרוזת	הפרמטר הזה הוצא משימוש. במקום זאת, צריך להשתמש ב-to כדי לציין לנמענים. למידע נוסף על שליחת הודעות אל במכשירים שונים, יש לעיין במסמכי התיעוד של הפלטפורמה.
אפשרויות
collapse_key	אופציונלי, מחרוזת	הפרמטר הזה מזהה קבוצה של הודעות (למשל, collapse_key: "Updates Available"), שניתן לכווץ, כך שרק ההודעה האחרונה נשלחת כשניתן להמשיך את השליחה. המטרה היא למנוע שליחת יותר מדי הודעות זהות כשהמכשיר יחזור לאינטרנט או יהפוך לפעיל. לתשומת ליבכם: אין התחייבות לסדר שבו ההודעות נשלחות. הערה: בכל רגע נתון מותר להשתמש ב-4 מקשי כיווץ שונים לכל היותר. המשמעות היא אפליקציית FCM יכולה לשמור בו-זמנית 4 הודעות שונות בכל אפליקציית לקוח. אם תחרוג מהמספר הזה, אי אפשר להבטיח אילו 4 מפתחות כיווץ יישמרו ב-FCM.
priority	אופציונלי, מחרוזת	הגדרת העדיפות של ההודעה. הערכים החוקיים הם 'רגילים' ו-"high". בפלטפורמות של Apple, הן תואמות לעדיפויות 5 ו-10 של ה-APN. כברירת מחדל, הודעות התראה נשלחות בעדיפות גבוהה והודעות נתונים נשלחים בעדיפות רגילה. עדיפות רגילה מבצעת אופטימיזציה של אפליקציית הלקוח צריכת הסוללה ויש להשתמש בה אלא אם נדרשת שליחה מיידית. הודעות בעדיפות רגילה עשויות להגיע לאפליקציה עם עיכוב לא ידוע. כששולחים הודעה בעדיפות גבוהה, היא נשלחת באופן מיידי והאפליקציה יכולה להציג התראה.
content_available	אופציונלי, בוליאני	בפלטפורמות של Apple, משתמשים בשדה הזה כדי לייצג את content-available בחיוב של APNs. כששולחים התראה או הודעה והערך מוגדר ל-true, אפליקציית לקוח לא פעילה מופעלת וההודעה נשלחת דרך APNs כהודעה שקטה ולא דרך FCM. חשוב לזכור שלא בטוח שההתראות השקטות ב-APN יישלחו, והן עשויות להשתנות בהתאם לגורמים כמו הפעלת מצב צריכת אנרגיה נמוכה על ידי המשתמש, סגירה בכוח של האפליקציה וכו'. ב-Android, הודעות נתונים מעוררות את האפליקציה כברירת מחדל. במצב מופעל אין תמיכה ב-Chrome כרגע.
mutable_content	אופציונלי, בוליאני מסוג JSON	בפלטפורמות של Apple, משתמשים בשדה הזה כדי לייצג mutable-content במטען הייעודי (payload) של ה-APN. כששולחים התראה והערך הזה מוגדר ל-true, אפשר לשנות את תוכן ההתראה לפני שהיא מוצגת באמצעות תוסף לאפליקציית Notification Service. המערכת תתעלם מהפרמטר הזה ב-Android ובאינטרנט.
time_to_live	אופציונלי, מספר	הפרמטר הזה מציין את משך הזמן (בשניות) שבו ההודעה תישמר באחסון של FCM אם המכשיר במצב אופליין. משך החיים המקסימלי הנתמך הוא 4 שבועות, וערך ברירת המחדל הוא 4 שבועות. מידע נוסף זמין במאמר הגדרת משך החיים של הודעה.
restricted_package_ name (Android בלבד)	אופציונלי, מחרוזת	הפרמטר הזה מציין את שם החבילה של האפליקציה שבה אסימוני הרישום חייבים להתאים כדי לקבל את ההודעה.
dry_run	אופציונלי, בוליאני	כשהפרמטר הזה מוגדר ל-true, הוא מאפשר למפתחים לבדוק בלי לשלוח הודעה בפועל. ערך ברירת המחדל הוא false.
מטען ייעודי (Payload)
data	אופציונלי, אובייקט	הפרמטר הזה מציין את צמדי המפתח/ערך המותאמים אישית של המטען הייעודי (Payload) של ההודעה. לדוגמה, באמצעות data:{"score":"3x1"}: בפלטפורמות של Apple, אם ההודעה נשלחת דרך APN, היא מייצגת את שדות הנתונים בהתאמה אישית. אם הוא נשלח דרך FCM, הוא יוצג כמילון של מפתחות וערכים ב-AppDelegate application:didReceiveRemoteNotification:. ב-Android, הפעולה הזו תוביל להוספת Intent בשם score, עם ערך המחרוזת 3x1. המפתח לא יכול להיות מילה שמורה ('from', 'message_type' או כל מילה שמתחילה ב-) "google" או 'gcm'). לא להשתמש באף אחת מהמילים שהוגדרו בטבלה (למשל collapse_key). מומלץ להשתמש בערכים מסוג מחרוזת. עליכם להמיר ערכים באובייקטים או בסוגי נתונים אחרים שאינם מחרוזות (למשל, מספרים שלמים או ערכים בוליאניים) למחרוזת.
notification	אופציונלי, אובייקט	הפרמטר הזה מציין את צמד המפתח/ערך המוגדר מראש שגלוי למשתמש, שנמצא בעומס העבודה של ההתראה. פרטים נוספים זמינים במאמר בנושא תמיכה במטען הייעודי של ההתראות. למידע נוסף על האפשרויות של הודעות התראה ונתונים על הודעות, לראות סוגי הודעות. אם סופק מטען ייעודי (payload) של התראה, או האפשרות content_available מוגדרת ל-true עבור הודעה ל-Apple במכשיר, ההודעה נשלחת דרך נקודות APN, אחרת היא נשלחת באמצעות FCM

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

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

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

פרמטר	שימוש	תיאור
title	אופציונלי, מחרוזת	כותרת ההתראה. השדה הזה לא גלוי בטלפונים ובטאבלטים.
body	אופציונלי, מחרוזת	גוף ההודעה.
sound	אופציונלי, מחרוזת	הצליל שיושמע כשהמכשיר יקבל את ההתראה. מחרוזת שציינה קובצי אודיו בחבילה הראשית של אפליקציית הלקוח או בתיקייה Library/Sounds של מאגר הנתונים של האפליקציה. מידע נוסף זמין בספריית המפתחים של iOS.
badge	אופציונלי, מחרוזת	הערך שמופיע בתג של סמל האפליקציה במסך הבית. אם לא מציינים זאת, התג לא ישתנה. אם הערך מוגדר כ-0, התג יוסר.
click_action	אופציונלי, מחרוזת	הפעולה שמשויכת לקליק של משתמש על ההתראה. תואם ל-category במטען הייעודי (payload) של ה-APN.
subtitle	אופציונלי, מחרוזת	כותרת המשנה של ההתראה.
body_loc_key	אופציונלי, מחרוזת	המפתח למחרוזת ה-body במשאבי המחרוזת של האפליקציה, שבו יש להשתמש כדי תרגום הטקסט בגוף הטקסט להתאמה לשוק המקומי הנוכחי של המשתמש. תואם ל-loc-key במטען הייעודי (payload) של APNs. צפייה סימוכין למפתחות מטען ייעודי (payload) וגם התאמת התוכן של ההתראות מרחוק מידע.
body_loc_args	מערך אופציונלי של JSON כמחרוזת	ערכים של מחרוזות משתנות שישמשו במקום מפרידי הפורמט ב-body_loc_key כדי להתאים את הטקסט בגוף להגדרות המקומיות הנוכחיות של המשתמש. תואם ל-loc-args במטען הייעודי (payload) של ה-APN. צפייה סימוכין למפתחות מטען ייעודי (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	אופציונלי, מחרוזת	הפעולה שמשויכת לקליק של משתמש על ההתראה. אם צוין, פעילות עם מסנן Intent תואם תופעל כאשר משתמש לוחץ על ההתראה.
body_loc_key	אופציונלי, מחרוזת	המפתח למחרוזת ה-body במשאבי המחרוזת של האפליקציה, שבו יש להשתמש כדי תרגום הטקסט בגוף הטקסט להתאמה לשוק המקומי הנוכחי של המשתמש. למידע נוסף, ראו משאבי מחרוזות.
body_loc_args	מערך אופציונלי של JSON כמחרוזת	ערכי מחרוזת משתנים שיש להשתמש בהם במקום מצייןי הפורמט body_loc_key לשימוש כדי להתאים את הטקסט בגוף הטקסט לבין ההתאמה לשוק המקומי של המשתמש. למידע נוסף, ראו עיצוב פורמטים.
title_loc_key	אופציונלי, מחרוזת	המפתח למחרוזת הכותרת במשאבי המחרוזות של האפליקציה, שמשמש ללוקליזציה של טקסט הכותרת בהתאם ללוקליזציה הנוכחית של המשתמש. צפייה מידע נוסף זמין ב-String Resources.
title_loc_args	מערך אופציונלי של JSON כמחרוזת	ערכי מחרוזת משתנים שיש להשתמש בהם במקום מצייןי הפורמט title_loc_key שמשמש להתאמת הטקסט של הכותרת לבין ההתאמה לשוק המקומי של המשתמש. צפייה עיצוב ועיצוב לקבלת מידע נוסף.

טבלה 2ג. אינטרנט (JavaScript) – מפתחות להודעות התראות

פרמטר	שימוש	תיאור
title	אופציונלי, מחרוזת	כותרת ההתראה.
body	אופציונלי, מחרוזת	גוף ההודעה.
icon	אופציונלי, מחרוזת	כתובת ה-URL שבה נעשה שימוש בסמל ההתראה.
click_action	אופציונלי, מחרוזת	הפעולה שמשויכת לקליק של משתמש על ההתראה. חובה להשתמש ב-HTTPS לכל הערכים של כתובות ה-URL.

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

בטבלה הבאה מפורטים התחביר של יעדים, אפשרויות ומטען ייעודי (payload) בפורמט פשוט. טקסט downstream של הודעות HTTP.

טבלה 3 יעדים, אפשרויות ומטען ייעודי (payload) להודעות HTTP רגילות בפורמט טקסט פשוט.

פרמטר	שימוש	תיאור
יעדים
registration_id	חובה, מחרוזת	הפרמטר הזה מציין את אפליקציות הלקוח (אסימוני הרישום) שמקבלות את ההודעה. שליחת הודעות לקבוצה (שליחת הודעה ליותר מאסימון רישום אחד) מותרת רק בפורמט HTTP JSON.
אפשרויות
collapse_key	אופציונלי, מחרוזת	פרטים נוספים זמינים בטבלה 1.
time_to_live	אופציונלי, מספר	פרטים נוספים זמינים בטבלה 1.
restricted_package_name	אופציונלי, מחרוזת	פרטים נוספים זמינים בטבלה 1.
dry_run	אופציונלי, ערך בוליאני	פרטים נוספים זמינים בטבלה 1.
Payload
data.<key>	אופציונלי, מחרוזת	הפרמטר הזה מציין את צמדי המפתח-ערך של מטען הייעודי של ההודעה. אין הגבלה על מספר הפרמטרים של מפתח/ערך, אבל קיימת מגבלת גודל כולל של 4,096 בייטים. לדוגמה, ב-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 ב-downstream (טקסט פשוט).

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

קודי תגובה של שגיאות בהודעות בהמשך

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

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

שגיאה	קוד HTTP	מה מומלץ לעשות?
חסר אסימון רישום	200 + error:MissingRegistration	בודקים שהבקשה מכילה אסימון רישום (בשדה registration_id בהודעת טקסט פשוט, או בשדה to או registration_ids ב-JSON).
Invalid Registration Token	200 + שגיאה:רישום לא חוקי	בודקים את הפורמט של אסימון הרישום ששולחים לשרת. כדאי לוודא תואם לאסימון הרישום שאפליקציית הלקוח מקבלת במהלך הרישום ב-Firebase התראות. אין לקצר את השם או להוסיף תווים נוספים.
מכשיר לא רשום	200 + error:NotRegistered	אסימון רישום קיים עשוי להפסיק להיות תקף במספר תרחישים, כולל: אם אפליקציית הלקוח מבטלת את הרישום ב-FCM. אם אפליקציית הלקוח לא רשומה באופן אוטומטי, מה שיכול לקרות אם המשתמש מסיר את האפליקציה. לדוגמה, ב-iOS, אם שירות המשוב של APNs דיווח שהאסימון של APNs לא תקין. אם תוקף אסימון הרישום יפוג (לדוגמה, Google עשויה להחליט לרענן את הדף) אסימוני רישום או שהתוקף של אסימון ה-APNs פג עבור מכשירי iOS). אם אפליקציית הלקוח מעודכנת אבל הגרסה החדשה לא מוגדרת לקבלת הודעות. בכל המקרים האלה, צריך להסיר את טוקן הרישום הזה משרת האפליקציה ולהפסיק להשתמש בו כדי לשלוח הודעות.
שם חבילה לא חוקי	200 + שגיאה:InvalidPackageName	יש לוודא שההודעה ממוענת לאסימון רישום ששם החבילה שלו תואם לערך שהועבר בבקשה.
שגיאת אימות	401	אי אפשר לאמת את חשבון השולח ששימש לשליחת ההודעה. הסיבות האפשריות הן: כותרת ההרשאה חסרה או מכילה תחביר לא חוקי בבקשת ה-HTTP. פרויקט Firebase שאליו שייך מפתח השרת שצוין שגוי. מפתחות שרת מדור קודם בלבד – הבקשה הגיעה משרת שלא נכלל ברשימת ההיתרים בכתובות ה-IP של מפתח השרת. צריך לוודא שהאסימון ששולחים בתוך כותרת האימות הוא את מפתח השרת הנכון שמשויך לפרויקט. צפייה בדיקת התקינות של מפתח שרת אפשר לקבל פרטים נוספים. אם משתמשים במפתח שרת מדור קודם, מומלץ לשדרג למפתח חדש שאין לו הגבלות על כתובות IP. ראו העברת מפתחות שרת מדור קודם.
שולח לא תואם	200 + error:MismatchSenderId	אסימון רישום מקושר לקבוצה מסוימת של שולחים. כשאפליקציית לקוח נרשמת עבור FCM, צריך לציין אילו שולחים מורשים לשלוח הודעות. צריך להשתמש באחד ממזהי השולח האלה כששולחים הודעות לאפליקציית הלקוח. אם עוברים לשולח אחר, אסימוני ההרשמה הקיימים לא יפעלו.
קובץ JSON לא תקין	400	בודקים שההודעה בפורמט JSON תקינה ושהיא מכילה שדות חוקיים (למשל, מוודאים שסוג הנתונים הנכון מועבר).
פרמטרים לא חוקיים	400 + error:InvalidParameters	בודקים שהשם והסוג של הפרמטרים שצוינו נכונים.
ההודעה גדולה מדי	200 + error:MessageTooBig	צריך לבדוק שהגודל הכולל של נתוני המטען הייעודי (Payload) שכלולים בהודעה כן לא יחרגו מהמגבלות של FCM: 4,096 בייטים לרוב ההודעות, או 2,048 בייטים במקרה של הודעות לנושאים. האיסור הזה כולל את המפתחות והערכים.
מפתח נתונים לא חוקי	200 + שגיאה: מפתח InvalidData	בודקים שנתוני המטען הייעודי לא מכילים מפתח (כמו from או gcm, או כל ערך שמתחיל ב-google) ש-FCM משתמש בו באופן פנימי. שימו לב שחלק מהמילים (כמו collapse_key) משמשות גם את FCM, אבל הן מותרות בתוכן המועמס. במקרה כזה, הערך של התוכן המועמס יבוטל על ידי הערך של FCM.
אורך החיים לא חוקי	200 + error:InvalidTtl	צריך לבדוק שהערך שנעשה בו שימוש ב-time_to_live הוא מספר שלם שמייצג משך בשניות בין 0 ל-2,419,200 (4 שבועות).
זמן קצוב לתפוגה	5xx או 200 + שגיאה:לא זמין	השרת לא הצליח לעבד את הבקשה בזמן. לנסות שוב את אותה בקשה, אבל צריך: יש לכבד את הכותרת Retry-After אם היא כלולה בתשובה של FCM שרת חיבור. מטמיעים השהיה מעריכית לפני ניסיון חוזר (exponential backoff) במנגנון הניסיון החוזר. (לדוגמה, אם המתינו שנייה אחת לפני הניסיון הראשון, צריך להמתין לפחות שתי שניות לפני הניסיון הבא, ואז 4 שניות וכן הלאה). אם אתם שולחים מספר הודעות, יש להשהות כל אחת בנפרד בסכום אקראי נוסף כדי להימנע משליחת בקשה חדשה לכל ההודעות בו-זמנית. שולחים שגורמים לבעיות עלולים להיכנס לרשימת החסימה.
שגיאת שרת פנימית	500 או 200 + שגיאה:InternalServerError	השרת נתקל בשגיאה במהלך הניסיון לעבד את הבקשה. אפשר לנסות שוב אותה בקשה בהתאם לדרישות המפורטות ב"זמן קצוב לתפוגה" (עיינו בשורה שלמעלה). אם השגיאה אם היא נמשכת, יש לפנות לתמיכה של Firebase.
חריגה מקצב ההודעות במכשיר	200 + שגיאה: DeviceMessageRate Exceeded	שיעור ההודעות שנשלחות למכשיר מסוים גבוה מדי. אם אפליקציה של Apple שולחת הודעות בקצב שמחרוג מהמגבלות של APN, יכול להיות שתופיע הודעת השגיאה הזו מצמצמים את מספר ההודעות שנשלחו למכשיר הזה, שימוש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כדי לנסות לשלוח שוב.
חריגה מקצב שליחת ההודעות בנושאים	200 + שגיאה: TopicsMessageRate חריגה	שיעור ההודעות למנויים בנושא מסוים גבוה מדי. מצמצמים את מספר ההודעות שנשלחו בנושא הזה, וגם שימוש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כדי לנסות לשלוח שוב.
פרטי כניסה לא תקינים של APN	200 + שגיאה: InvalidApnsCredential	לא ניתן היה לשלוח הודעה שמטורגטת למכשיר Apple כי מפתח האימות הנדרש של APNs לא הועלה או שתוקפו פג. בודקים את התקינות של פרטי הכניסה לפיתוח ולייצור.

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

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

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

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