המסמך הזה מספק הפניה לתחביר HTTP שמשמש להעברת הודעות משרת האפליקציות לאפליקציות לקוח באמצעות העברת הודעות בענן ב-Firebase.
כשמשתמשים בפרוטוקול HTTP מדור קודם, שרת האפליקציות צריך להפנות את כל בקשות ה-HTTP לנקודת הקצה הזו:
https://fcm.googleapis.com/fcm/send
האפשרויות והפרמטרים הזמינים מתחלקים לקטגוריות הרחבות הבאות:
תחביר של הודעות במורד הזרם
הקטע הזה מספק את התחביר לשליחת הודעות במורד הזרם ולפירוש תגובות HTTP מ-Firebase Cloud Messaging.
הודעות HTTP במורד הזרם (JSON)
בטבלה הבאה מפורטים היעדים, האפשרויות והמטען הייעודי (payload) של הודעות HTTP JSON.
פרמטר | Usage | תיאור | |
---|---|---|---|
יעדים | |||
to |
אופציונלי, מחרוזת |
הפרמטר הזה מציין את נמען ההודעה.
הערך יכול להיות אסימון רישום של מכשיר, מפתח התראה של קבוצת מכשירים, או נושא יחיד (עם קידומת
|
|
registration_ids | אופציונלי, מערך מחרוזות |
הפרמטר הזה מציין את הנמען של הודעה מרובת שידורים, הודעה שנשלחת ליותר מאסימון רישום אחד.
הערך צריך להיות מערך של אסימוני רישום שאליהם צריך לשלוח את הודעת ה-Multicast. המערך חייב להכיל לפחות אסימון רישום אחד ולכל היותר 1,000. כדי לשלוח הודעה למכשיר יחיד, צריך להשתמש בפרמטר ניתן לשלוח הודעות לכולם רק בפורמט HTTP JSON. |
|
condition |
אופציונלי, מחרוזת | הפרמטר הזה מציין ביטוי לוגי של תנאים שקובעים את יעד ההודעה. תנאי נתמך: הנושא, בפורמט 'yourTopic' בנושאים. הערך הזה לא תלוי-רישיות. אופרטורים נתמכים: |
|
notification_key הוצא משימוש |
אופציונלי, מחרוזת | הפרמטר הזה הוצא משימוש. במקום זאת, אפשר להשתמש ב- |
|
אפשרויות | |||
collapse_key |
אופציונלי, מחרוזת | הפרמטר הזה מזהה קבוצה של הודעות (למשל, עם
לתשומת ליבכם: לא מובטח את סדר השליחה של ההודעות. הערה: בכל זמן נתון מותר להוסיף עד 4 מפתחות כיווץ שונים. כלומר, FCM יכול לאחסן בו-זמנית 4 הודעות שונות לכל אפליקציית לקוח. אם תחרגו מהמספר הזה, לא נוכל להבטיח אילו 4 מפתחות כיווץ יישמרו ב-FCM. |
|
priority |
אופציונלי, מחרוזת | ההגדרה הזו קובעת את עדיפות ההודעה. הערכים החוקיים הם 'רגיל' ו'גבוה'. בפלטפורמות של Apple, הערכים האלה תואמים לעדיפויות 5 ו-10 של ה-APN. כברירת מחדל, הודעות נשלחות בעדיפות גבוהה והודעות נתונים נשלחות בעדיפות רגילה. בעדיפות רגילה מבצעת אופטימיזציה של צריכת הסוללה של אפליקציית הלקוח, וצריך להשתמש בה אלא אם יש צורך באספקה מיידית. בהודעות בעדיפות רגילה, האפליקציה עשויה לקבל את ההודעה עם עיכוב שלא צוין. כשהודעה נשלחת בעדיפות גבוהה, היא נשלחת מיידית, והאפליקציה יכולה להציג התראה. |
|
content_available |
אופציונלי, בוליאני | בפלטפורמות של Apple, צריך להשתמש בשדה הזה כדי לייצג את |
|
mutable_content |
אופציונלי, קובץ JSON בוליאני | בפלטפורמות של Apple, צריך להשתמש בשדה הזה כדי לייצג את
|
|
time_to_live |
אופציונלי, מספר | הפרמטר הזה מציין את משך הזמן (בשניות) לשמירת ההודעה באחסון FCM אם המכשיר במצב אופליין. משך הזמן המקסימלי להפעלת תמיכה הוא 4 שבועות, וערך ברירת המחדל הוא 4 שבועות. למידע נוסף, אפשר לקרוא את המאמר הגדרת משך החיים של הודעה. |
|
restricted_package_
(Android בלבד) |
אופציונלי, מחרוזת | הפרמטר הזה מציין את שם החבילה של האפליקציה, שבה אסימוני הרישום צריכים להיות זהים על מנת לקבל את ההודעה. | |
dry_run |
אופציונלי, בוליאני | כשהפרמטר הזה מוגדר ל- ערך ברירת המחדל הוא |
|
מטען ייעודי (payload) | |||
data |
אופציונלי, אובייקט | הפרמטר הזה מציין את צמדי המפתח/ערך המותאמים אישית של המטען הייעודי (payload) של ההודעה. לדוגמה, באמצעות בפלטפורמות של Apple, אם ההודעה נשלחת דרך פריטי APN, היא מייצגת את שדות הנתונים המותאמים אישית. אם הוא נשלח דרך FCM,
הוא מיוצג כמילון לערך מפתח ב- ב-Android, התוצאה תהיה תוספת של Intent בשם המפתח לא יכול להיות מילה שמורה ('from', 'message_type' או כל מילה שמתחילה ב-'google' או ב-'gcm'). אין להשתמש באף אחת מהמילים המוגדרות בטבלה הזו
(כמו מומלץ להשתמש בערכים של סוגי המחרוזות. צריך להמיר ערכים באובייקטים או בסוגי נתונים אחרים שאינם מחרוזות (למשל, מספרים שלמים או בוליאניים) למחרוזת. |
|
notification |
אופציונלי, אובייקט | הפרמטר הזה מציין את צמדי המפתח/ערך המוגדרים מראש וגלויים למשתמש של
המטען הייעודי (payload) של ההתראות. לקבלת פרטים, אפשר לעיין בתמיכה למטען ייעודי (payload) של התראות.
למידע נוסף על האפשרויות של הודעות ושל הודעות נתונים, ראו את המאמר
סוגי הודעות. אם סופק מטען ייעודי (payload) של התראות, או שהאפשרות content_available מוגדרת לערך true לגבי הודעה במכשיר Apple, ההודעה נשלחת באמצעות APN. אחרת, היא נשלחת דרך FCM.
|
תמיכה במטען ייעודי (payload) של התראות
בטבלאות הבאות מפורטים המפתחות המוגדרים מראש שזמינים ליצירת הודעות התראה ל-iOS ול-Android.
פרמטר | Usage | תיאור |
---|---|---|
title |
אופציונלי, מחרוזת |
כותרת ההודעה. השדה הזה לא מוצג בטלפונים ובטאבלטים. |
body |
אופציונלי, מחרוזת |
טקסט ההודעה. |
sound |
אופציונלי, מחרוזת |
הצליל שיושמע כשהמכשיר מקבל את ההתראה.
מחרוזת לציון קובצי צלילים בחבילה הראשית של אפליקציית הלקוח או בתיקייה |
badge |
אופציונלי, מחרוזת |
ערך התג בסמל האפליקציה במסך הבית. אם לא מציינים את הפרמטר הזה, התג לא משתנה.
אם קובעים במדיניות את הערך |
click_action |
אופציונלי, מחרוזת |
הפעולה המשויכת ללחיצה של משתמש על ההתראה.
תואם ל- |
subtitle |
אופציונלי, מחרוזת |
כותרת המשנה של ההתראה. |
body_loc_key |
אופציונלי, מחרוזת |
המפתח למחרוזת ה-body במשאבי המחרוזת של האפליקציה, שבו ניתן להשתמש כדי להתאים לשוק המקומי את טקסט הגוף לפי הלוקליזציה הנוכחית של המשתמש.
תואם ל- למידע נוסף, אפשר לעיין ב מידע נוסף על מפתחות של מטען ייעודי (payload) וב התאמה לשוק המקומי של התוכן של ההתראות המרוחקות. |
body_loc_args |
אופציונלי, מערך JSON כמחרוזת |
ערכים של מחרוזות משתנים שישמשו במקום מציינים את הפורמט ב-
תואם ל- למידע נוסף, אפשר לעיין ב מידע נוסף על מפתחות של מטען ייעודי (payload) וב התאמה לשוק המקומי של התוכן של ההתראות המרוחקות. |
title_loc_key |
אופציונלי, מחרוזת |
המפתח למחרוזת הכותרת במשאבי המחרוזת של האפליקציה שישמש להתאמה לשוק המקומי של טקסט הכותרת להתאמה הנוכחית של המשתמש.
תואם ל- למידע נוסף, אפשר לעיין ב מידע נוסף על מפתחות של מטען ייעודי (payload) וב התאמה לשוק המקומי של התוכן של ההתראות המרוחקות. |
title_loc_args |
אופציונלי, מערך JSON כמחרוזת |
ערכי מחרוזת משתנים שיש להשתמש בהם במקום מגדירי הפורמט ב-
תואם ל- למידע נוסף, אפשר לעיין ב מידע נוסף על מפתחות של מטען ייעודי (payload) וב התאמה לשוק המקומי של התוכן של ההתראות המרוחקות. |
פרמטר | Usage | תיאור |
---|---|---|
title |
אופציונלי, מחרוזת |
כותרת ההודעה. |
body |
אופציונלי, מחרוזת |
טקסט ההודעה. |
android_channel_id |
אופציונלי, מחרוזת |
מזהה הערוץ של ההתראה (חדש ב-Android O). כדי לקבל התראה עם מזהה הערוץ הזה, האפליקציה צריכה ליצור ערוץ עם מזהה הערוץ הזה. אם לא שולחים את מזהה הערוץ הזה בבקשה, או אם מזהה הערוץ שסופק עדיין לא נוצר על ידי האפליקציה, FCM משתמש במזהה הערוץ שצוין בקובץ המניפסט של האפליקציה. |
icon |
אופציונלי, מחרוזת |
סמל ההודעה.
ההגדרה הזו מגדירה את סמל ההתראה ל- |
sound |
אופציונלי, מחרוזת |
הצליל שיושמע כשהמכשיר מקבל את ההתראה.
יש תמיכה ב- |
tag |
אופציונלי, מחרוזת |
המזהה שמשמש להחלפת ההתראות הקיימות בחלונית ההזזה של ההתראות. אם לא מציינים שום אפשרות, כל בקשה יוצרת התראה חדשה. אם צוינה התראה עם אותו תג, היא תחליף את ההתראה הקיימת בחלונית ההזזה להתראות. |
color |
אופציונלי, מחרוזת |
צבע סמל ההתראה, מבוטא בפורמט |
click_action |
אופציונלי, מחרוזת |
הפעולה המשויכת ללחיצה של משתמש על ההתראה. אם צוין, פעילות עם מסנן Intent תואם תופעל כשמשתמש ילחץ על ההתראה. |
body_loc_key |
אופציונלי, מחרוזת |
המפתח למחרוזת ה-body במשאבי המחרוזת של האפליקציה, שבו ניתן להשתמש כדי להתאים לשוק המקומי את טקסט הגוף לפי הלוקליזציה הנוכחית של המשתמש. מידע נוסף זמין במאמר משאבי מחרוזות. |
body_loc_args |
אופציונלי, מערך JSON כמחרוזת |
ערכים של מחרוזות משתנים שישמשו במקום מציינים את הפורמט ב- מידע נוסף זמין במאמר עיצוב ועיצוב. |
title_loc_key |
אופציונלי, מחרוזת |
המפתח למחרוזת הכותרת במשאבי המחרוזת של האפליקציה שישמש להתאמה לשוק המקומי של טקסט הכותרת להתאמה הנוכחית של המשתמש. מידע נוסף זמין במאמר משאבי מחרוזות. |
title_loc_args |
אופציונלי, מערך JSON כמחרוזת |
ערכי מחרוזת משתנים שיש להשתמש בהם במקום מגדירי הפורמט ב- מידע נוסף זמין במאמר עיצוב ועיצוב. |
פרמטר | Usage | תיאור |
---|---|---|
title |
אופציונלי, מחרוזת |
כותרת ההודעה. |
body |
אופציונלי, מחרוזת |
טקסט ההודעה. |
icon |
אופציונלי, מחרוזת |
כתובת ה-URL שבה יש להשתמש עבור סמל ההתראה. |
click_action |
אופציונלי, מחרוזת |
הפעולה המשויכת ללחיצה של משתמש על ההתראה. חובה להשתמש ב-HTTPS לכל הערכים של כתובות ה-URL. |
הודעות HTTP במורד הזרם (טקסט פשוט)
בטבלה הבאה מפורטים התחביר של מטרות עסקיות, אפשרויות ומטען ייעודי (payload) בהודעות HTTP בפורמט טקסט פשוט במורד הזרם.
פרמטר | 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, הפקודה המפתח לא יכול להיות מילה שמורה ('from', 'message_type' או כל מילה שמתחילה ב-'google' או ב-'gcm'). אין להשתמש באף אחת מהמילים המוגדרות בטבלה הזו (כמו |
פירוש תגובה להודעה במורד הזרם
שרת האפליקציות צריך להעריך גם את כותרת התגובה להודעה וגם את הגוף כדי לפרש את התגובה להודעה שנשלחת מ-FCM. התגובות האפשריות מפורטות בטבלה הבאה.
תשובה | תיאור |
---|---|
200 | ההודעה עובדה בהצלחה. גוף התשובה יכלול פרטים נוספים על סטטוס ההודעה, אבל הפורמט שלו תלוי בשאלה אם הבקשה הייתה JSON או טקסט פשוט. ראו טבלה 5 לפרטים נוספים. |
400 | רלוונטי רק לבקשות JSON. מציין שלא ניתן היה לנתח את הבקשה כ-JSON, או שהיא הכילה שדות לא חוקיים (למשל, העברת מחרוזת שבה היה צפוי מספר). הסיבה המדויקת לכשל מתוארת בתגובה, וצריך לטפל בבעיה לפני שאפשר יהיה לנסות שוב את הבקשה. |
401 | אירעה שגיאה באימות חשבון השולח. |
5xx | שגיאות בטווח 500-599 (כמו 500 או 503) מציינות שאירעה שגיאה פנימית בקצה העורפי של FCM במהלך הניסיון לעבד את הבקשה, או שהשרת לא זמין באופן זמני (למשל בגלל פסקי זמן). השולח צריך לנסות שוב מאוחר יותר, בהתאם לכל כותרת Retry-After שכלולה בתגובה. שרתי יישומים חייבים ליישם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). |
בטבלה הבאה מפורטים השדות בגוף התשובה של ההודעה במורד הזרם (JSON).
פרמטר | Usage | תיאור |
---|---|---|
multicast_id |
חובה, מספר | מזהה ייחודי (מספר) שמזהה את ההודעה למשתתפים מרובים. |
success |
חובה, מספר | מספר ההודעות שעובדו ללא שגיאה. |
failure |
חובה, מספר | מספר ההודעות שלא ניתן היה לעבד. |
results |
נדרש, מערך אובייקטים | מערך אובייקטים שמייצגים את הסטטוס של ההודעות שעובדו. האובייקטים רשומים באותו סדר שבו מופיעה הבקשה (כלומר לכל מזהה רישום בבקשה, התוצאה שלו מופיעה באותו אינדקס בתגובה).
|
פרמטר | Usage | תיאור |
---|---|---|
message_id |
אופציונלי, מספר | מזהה ההודעה של הנושא לאחר קבלת הבקשה ב-FCM, והמערכת תנסה לשלוח אותה לכל המכשירים שאליהם נרשמת. |
error |
אופציונלי, מחרוזת | אירעה שגיאה במהלך עיבוד ההודעה. הערכים האפשריים מופיעים בטבלה 9. |
פרמטר | Usage | תיאור |
---|---|---|
id |
חובה, מחרוזת | הפרמטר הזה מציין שמזהה ההודעה הייחודי FCM עבר עיבוד בהצלחה. |
registration_id |
אופציונלי, מחרוזת | הפרמטר הזה מציין את אסימון הרישום של אפליקציית הלקוח שאליה עובדה ההודעה ונשלחה. |
פרמטר | Usage | תיאור |
---|---|---|
Error |
חובה, מחרוזת | הפרמטר הזה מציין את ערך השגיאה בזמן עיבוד ההודעה עבור הנמען. פרטים נוספים מופיעים בטבלה 9. |
קודי תגובה לשגיאות של הודעות במורד הזרם
בטבלה הבאה מפורטים קודי התגובה לשגיאות של הודעות במורד הזרם.
שגיאה | קוד HTTP | מה מומלץ לעשות? |
---|---|---|
חסר אסימון רישום | 200 + שגיאה:חסר רישום | מוודאים שהבקשה מכילה אסימון רישום (ב-registration_id בהודעת טקסט פשוטה, או בשדה to או registration_ids ב-JSON). |
אסימון רישום לא חוקי | 200 + שגיאה:רישום לא חוקי | צריך לבדוק את הפורמט של אסימון הרישום שאתם מעבירים לשרת. מוודאים שהוא תואם לאסימון הרישום שאפליקציית הלקוח מקבלת מההרשמה באמצעות התראות של Firebase. אל תקצר או תוסיפו תווים נוספים. |
המכשיר לא רשום | 200 + שגיאה:לא רשום | אסימון רישום קיים עלול להפסיק להיות תקף במספר תרחישים, כולל:
|
שם לא חוקי של חבילה | 200 + שגיאה:InvalidPackageName | ודאו שההודעה נשלחה אל אסימון רישום ששם החבילה שלו תואם לערך שהועבר בבקשה. |
שגיאת אימות | 401 | לא ניתן היה לאמת את חשבון השולח ששימש לשליחת ההודעה. יכולות להיות לכך כמה סיבות:
|
שולח לא תואם | 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 + שגיאה:לא זמין | השרת לא הצליח לעבד את הבקשה בזמן. אפשר לנסות שוב את אותה בקשה, אבל צריך:
שולחים שגורמים לבעיות יתווספו לרשימה השחורה. |
שגיאת שרת פנימית | 500 או 200 + שגיאה:InternalServerError | השרת נתקל בשגיאה במהלך ניסיון לעבד את הבקשה. תוכלו לנסות שוב את אותה בקשה בהתאם לדרישות שמפורטות בקטע 'זמן קצוב לתפוגה' (ראו שורה למעלה). אם השגיאה נמשכת, יש לפנות לתמיכה של Firebase. |
חרגת משיעור ההודעות במכשיר | 200 + שגיאה:
DeviceMessageRate חרגת |
קצב ההודעות במכשיר מסוים גבוה מדי. אם אפליקציה של Apple שולחת הודעות בקצב שחורג ממגבלות ה-APN, ייתכן שתופיע הודעת השגיאה הזו. יש להפחית את מספר ההודעות שנשלחות למכשיר הזה ולהשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כדי לנסות לשלוח שוב. |
חרגת משיעור ההודעות של נושאים | 200 + שגיאה:
TopicsMessageRate חרגת |
שיעור ההודעות למנויים בנושא מסוים גבוה מדי. יש להפחית את מספר ההודעות שנשלחו בנושא הזה ולהשתמש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כדי לנסות לשלוח שוב. |
פרטי כניסה לא חוקיים ל-APN | 200 + שגיאה:
InvalidApnsCredential |
לא ניתן היה לשלוח הודעה שמטרגטת למכשיר Apple כי מפתח האימות של פריטי ה-APN לא הועלה או שהתוקף שלו פג. בדיקת התקינות של פרטי הכניסה לפיתוח ולייצור. |
ניהול קבוצות מכשירים
בטבלה הבאה מפורטים המפתחות ליצירת קבוצות של מכשירים ולהוספה ולהסרה של חברים. מידע נוסף זמין במדריך הרלוונטי לפלטפורמה שלך, iOS+ או Android.
פרמטר | Usage | תיאור |
---|---|---|
operation |
חובה, מחרוזת | הפעולה להרצה.הערכים החוקיים הם create ,
add ו-remove . |
notification_key_name |
חובה, מחרוזת | השם של קבוצת המכשירים שהוגדר על ידי המשתמש, שצריך ליצור או לשנות. |
notification_key |
חובה (מלבד פעולה אחת (create ), מחרוזת |
המזהה הייחודי של קבוצת המכשירים. הערך הזה מוחזר בתגובה לפעולת create מוצלחת, והוא נדרש
לכל הפעולות הבאות בקבוצת המכשירים. |
registration_ids |
חובה, מערך מחרוזות | אסימוני המכשיר להוספה או להסרה. אם מסירים את כל אסימוני הרישום הקיימים מקבוצת מכשירים, קבוצת המכשירים נמחקת על ידי FCM. |