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

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

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

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

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

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

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

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

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

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

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

פרמטר	Usage	תיאור
יעדים
`to`	אופציונלי, מחרוזת	הפרמטר הזה מציין את נמען ההודעה. הערך יכול להיות אסימון רישום של מכשיר, מפתח התראה של קבוצת מכשירים, או נושא יחיד (עם קידומת `/topics/`). כדי לשלוח למספר נושאים, צריך להשתמש בפרמטר `condition`.
`registration_ids`	אופציונלי, מערך מחרוזות	הפרמטר הזה מציין את הנמען של הודעה מרובת שידורים, הודעה שנשלחת ליותר מאסימון רישום אחד. הערך צריך להיות מערך של אסימוני רישום שאליהם צריך לשלוח את הודעת ה-Multicast. המערך חייב להכיל לפחות אסימון רישום אחד ולכל היותר 1,000. כדי לשלוח הודעה למכשיר יחיד, צריך להשתמש בפרמטר `to`. ניתן לשלוח הודעות לכולם רק בפורמט HTTP JSON.
`condition`	אופציונלי, מחרוזת	הפרמטר הזה מציין ביטוי לוגי של תנאים שקובעים את יעד ההודעה. תנאי נתמך: הנושא, בפורמט 'yourTopic' בנושאים. הערך הזה לא תלוי-רישיות. אופרטורים נתמכים: `&&`, `\|\|`. תמיכה בשני אופרטורים לכל היותר לכל הודעת נושא.
`notification_key` הוצא משימוש	אופציונלי, מחרוזת	הפרמטר הזה הוצא משימוש. במקום זאת, אפשר להשתמש ב-`to` כדי לציין את הנמענים של ההודעה. למידע נוסף על שליחת הודעות לכמה מכשירים, כדאי לעיין במסמכי התיעוד של הפלטפורמה הרלוונטית.
אפשרויות
`collapse_key`	אופציונלי, מחרוזת	הפרמטר הזה מזהה קבוצה של הודעות (למשל, עם `collapse_key: "Updates Available"`) שאפשר לכווץ, כך שרק ההודעה האחרונה תישלח כשאפשר להמשיך את ההעברה. המטרה היא למנוע שליחת יותר מדי הודעות של אותן הודעות כשהמכשיר חוזר למצב אונליין או הופך לפעיל. לתשומת ליבכם: לא מובטח את סדר השליחה של ההודעות. הערה: בכל זמן נתון מותר להוסיף עד 4 מפתחות כיווץ שונים. כלומר, FCM יכול לאחסן בו-זמנית 4 הודעות שונות לכל אפליקציית לקוח. אם תחרגו מהמספר הזה, לא נוכל להבטיח אילו 4 מפתחות כיווץ יישמרו ב-FCM.
`priority`	אופציונלי, מחרוזת	ההגדרה הזו קובעת את עדיפות ההודעה. הערכים החוקיים הם 'רגיל' ו'גבוה'. בפלטפורמות של Apple, הערכים האלה תואמים לעדיפויות 5 ו-10 של ה-APN. כברירת מחדל, הודעות נשלחות בעדיפות גבוהה והודעות נתונים נשלחות בעדיפות רגילה. בעדיפות רגילה מבצעת אופטימיזציה של צריכת הסוללה של אפליקציית הלקוח, וצריך להשתמש בה אלא אם יש צורך באספקה מיידית. בהודעות בעדיפות רגילה, האפליקציה עשויה לקבל את ההודעה עם עיכוב שלא צוין. כשהודעה נשלחת בעדיפות גבוהה, היא נשלחת מיידית, והאפליקציה יכולה להציג התראה.
`content_available`	אופציונלי, בוליאני	בפלטפורמות של Apple, צריך להשתמש בשדה הזה כדי לייצג את `content-available` במטען הייעודי (payload) של ה-APNs. כשההתראה או ההודעה מוגדרות לערך `true`, מושמעת אפליקציית לקוח לא פעילה וההודעה נשלחת דרך נקודות APN כהתראה שקטה ולא דרך FCM. חשוב לזכור שלא בטוח שהתראות שקטות בפריטי APN יישלחו, והן תלויות בגורמים כמו הפעלת מצב צריכת חשמל נמוכה, אילוץ יציאה מהאפליקציה וכו'. ב-Android, הודעות נתונים מוציאות את האפליקציה ממצב שינה כברירת מחדל. בשלב זה, Chrome אינו נתמך.
`mutable_content`	אופציונלי, קובץ JSON בוליאני	בפלטפורמות של Apple, צריך להשתמש בשדה הזה כדי לייצג את `mutable-content` במטען הייעודי (payload) של ה-APNs. כשההתראה נשלחת והיא מוגדרת לערך `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) של ההתראות. לקבלת פרטים, אפשר לעיין בתמיכה למטען ייעודי (payload) של התראות. למידע נוסף על האפשרויות של הודעות ושל הודעות נתונים, ראו את המאמר סוגי הודעות. אם סופק מטען ייעודי (payload) של התראות, או שהאפשרות `content_available` מוגדרת לערך `true` לגבי הודעה במכשיר Apple, ההודעה נשלחת באמצעות APN. אחרת, היא נשלחת דרך FCM.

תמיכה במטען ייעודי (payload) של התראות

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

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

פרמטר	Usage	תיאור
`title`	אופציונלי, מחרוזת	כותרת ההודעה. השדה הזה לא מוצג בטלפונים ובטאבלטים.
`body`	אופציונלי, מחרוזת	טקסט ההודעה.
`sound`	אופציונלי, מחרוזת	הצליל שיושמע כשהמכשיר מקבל את ההתראה. מחרוזת לציון קובצי צלילים בחבילה הראשית של אפליקציית הלקוח או בתיקייה `Library/Sounds` במאגר הנתונים של האפליקציה. למידע נוסף, אפשר לעיין ב ספריית המפתחים ל-iOS.
`badge`	אופציונלי, מחרוזת	ערך התג בסמל האפליקציה במסך הבית. אם לא מציינים את הפרמטר הזה, התג לא משתנה. אם קובעים במדיניות את הערך `0`, התג יוסר.
`click_action`	אופציונלי, מחרוזת	הפעולה המשויכת ללחיצה של משתמש על ההתראה. תואם ל-`category` במטען הייעודי (payload) של ה-APNs.
`subtitle`	אופציונלי, מחרוזת	כותרת המשנה של ההתראה.
`body_loc_key`	אופציונלי, מחרוזת	המפתח למחרוזת ה-body במשאבי המחרוזת של האפליקציה, שבו ניתן להשתמש כדי להתאים לשוק המקומי את טקסט הגוף לפי הלוקליזציה הנוכחית של המשתמש. תואם ל-`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 — מקשים להתראות להודעות

פרמטר	Usage	תיאור
`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`	אופציונלי, מחרוזת	המפתח למחרוזת הכותרת במשאבי המחרוזת של האפליקציה שישמש להתאמה לשוק המקומי של טקסט הכותרת להתאמה הנוכחית של המשתמש. מידע נוסף זמין במאמר משאבי מחרוזות.
`title_loc_args`	אופציונלי, מערך JSON כמחרוזת	ערכי מחרוזת משתנים שיש להשתמש בהם במקום מגדירי הפורמט ב-`title_loc_key`, שישמשו להתאמה לשוק המקומי של טקסט הכותרת להתאמה לשוק המקומי הנוכחי של המשתמש. מידע נוסף זמין במאמר עיצוב ועיצוב.

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

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

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

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

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

פרמטר	Usage	תיאור
יעדים
`registration_id`	חובה, מחרוזת	הפרמטר הזה מציין את אפליקציות הלקוח (אסימוני הרישום) שמקבלות את ההודעה. העברת הודעות Multicast (שליחה ליותר מאסימון רישום אחד) מותרת באמצעות פורמט HTTP JSON בלבד.
אפשרויות
`collapse_key`	אופציונלי, מחרוזת	פרטים נוספים זמינים בטבלה 1.
`time_to_live`	אופציונלי, מספר	פרטים נוספים זמינים בטבלה 1.
`restricted_package_name`	אופציונלי, מחרוזת	פרטים נוספים זמינים בטבלה 1.
`dry_run`	אופציונלי, בוליאני	פרטים נוספים זמינים בטבלה 1.
מטען ייעודי (payload)
`data.<key>`	אופציונלי, מחרוזת	הפרמטר הזה מציין את צמדי המפתח/ערך של המטען הייעודי (payload) של ההודעה. אין הגבלה על מספר הפרמטרים של מפתח-ערך, אבל יש מגבלת גודל של 4,096 בייטים בסך הכול. לדוגמה, ב-Android, הפקודה `"data.score"."3x1"` תוביל ל-Intent נוסף בשם `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).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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