פרוטוקול 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. חשוב לשים לב שלא מובטח שיתקבלו התראות שקטות ב-APN, והן עשויות להיות תלויות בגורמים כמו המשתמש שמפעיל את מצב צריכת חשמל נמוכה , יוצא ידנית מהאפליקציה וכו'. ב-Android, הודעות נתונים מוציאות את האפליקציה ממצב שינה כברירת מחדל. ב-Chrome, בשלב הזה אין תמיכה.
mutable_content אופציונלי, בוליאני מסוג JSON

בפלטפורמות של Apple, משתמשים בשדה הזה כדי לייצג את mutable-content בתוכן הייעודי לטעינה (payload) של APNs. כשהתראה נשלחת ומוגדרת לערך true, אפשר לשנות את התוכן של ההתראה לפני שהיא מוצגת באמצעות תוסף של אפליקציית שירות התראות. המערכת תתעלם מהפרמטר הזה ב-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 אופציונלי, אובייקט הפרמטר הזה מציין את צמד המפתח/ערך המוגדר מראש שגלוי למשתמש, שנמצא בעומס העבודה של ההתראה. לפרטים נוספים, ראו תמיכה במטען ייעודי (payload) של התראות. למידע נוסף על אפשרויות של הודעות התראה והודעות נתונים, קראו את המאמר סוגי הודעות. אם צוין מטען ייעודי (payload) של התראות, או האפשרות content_available מוגדרת לערך true עבור הודעה למכשיר Apple, ההודעה נשלחה דרך APN, אחרת היא נשלחת דרך FCM.

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

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

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

אם צוין, פעילות עם מסנן Intent תואם מופעלת כשמשתמש לוחץ על ההתראה.

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

המפתח למחרוזת ה-body במשאבי המחרוזת של האפליקציה, שבו הטקסט ישמש להתאמה לשוק המקומי של המשתמש.

למידע נוסף, ראו משאבי מחרוזות.

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 יעדים, אפשרויות ומטען ייעודי (payload) להודעות HTTP רגילות בפורמט טקסט פשוט.

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

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

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

הפרמטר הזה מציין את צמדי המפתח/ערך של המטען הייעודי (Payload) של ההודעה. אין הגבלה על מספר הפרמטרים של מפתח/ערך, אבל יש מגבלה על גודל ההודעה הכולל של 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 ב-downstream (טקסט פשוט).

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

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

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

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

שגיאה קוד HTTP מה מומלץ לעשות?
טוקן הרישום חסר 200 + error:MissingRegistration בודקים שהבקשה מכילה אסימון רישום (בשדה registration_id בהודעת טקסט פשוט, או בשדה to או registration_ids ב-JSON).
Invalid Registration Token 200 + שגיאה:רישום לא חוקי בודקים את הפורמט של אסימון הרישום ששולחים לשרת. חשוב לוודא שהוא תואם לאסימון הרישום שאפליקציית הלקוח מקבלת מהרישום ב-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 + שגיאה:
LegalDataKey		 בודקים שנתוני המטען הייעודי לא מכילים מפתח (כמו 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.
  • מטמיעים השהיה מעריכית לפני ניסיון חוזר (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 תמחק את קבוצת המכשירים.