במסמך הזה מופיע מסמך עזר בנושא התחביר של HTTP שמשמש להעברת הודעות משרת האפליקציות לאפליקציות הלקוח דרך Firebase Cloud Messaging.
כשמשתמשים בפרוטוקול HTTP הקודם, שרת האפליקציה צריך להפנות את כל בקשות ה-HTTP לנקודת הקצה הזו:
https://fcm.googleapis.com/fcm/send
הפרמטרים והאפשרויות הזמינים הם במסגרת את הקטגוריות הכלליות הבאות:
תחביר ההודעות במורד הזרם
בקטע הזה מוסבר התחביר לשליחת הודעות במורד הזרם ולפרש תגובות HTTP מ-Firebase Cloud Messaging.
הודעות HTTP במורד הזרם (JSON)
בטבלה הבאה מפורטים היעדים, האפשרויות והמטען הייעודי (payload) של הודעות HTTP JSON.
פרמטר | שימוש | תיאור | |
---|---|---|---|
יעדים | |||
to |
אופציונלי, מחרוזת |
הפרמטר הזה מציין את הנמען של ההודעה.
הערך יכול להיות אסימון רישום של מכשיר,
מקש התראה או נושא יחיד (עם קידומת
|
|
registration_ids | אופציונלי, מערך של מחרוזות |
הפרמטר הזה מציין את הנמען של הודעת multicast, הודעה שנשלחת ליותר מאסימון רישום אחד.
הערך צריך להיות מערך של אסימוני רישום שאליהם צריך לשלוח את הודעת ה-multicast. המערך חייב להכיל לפחות 1 ולא יותר מ-1,000
אסימוני רישום. כדי לשלוח הודעה למכשיר אחד, משתמשים
הפרמטר מותר לשלוח הודעות Multicast רק באמצעות פורמט HTTP JSON. |
|
condition |
אופציונלי, מחרוזת | הפרמטר הזה מציין ביטוי לוגי של תנאים שקובעים את היעד של ההודעה. תנאי נתמך: נושא, בפורמט 'yourTopic' בנושאים". הערך הזה לא תלוי רישיות. אופרטורים נתמכים: |
|
notification_key הוצא משימוש |
אופציונלי, מחרוזת | הפרמטר הזה הוצא משימוש. במקום זאת, צריך להשתמש ב- |
|
אפשרויות | |||
collapse_key |
אופציונלי, מחרוזת | הפרמטר הזה מזהה קבוצה של הודעות (למשל,
לתשומת ליבכם: אין התחייבות לסדר שבו ההודעות נשלחות. הערה: בכל רגע נתון מותר להשתמש ב-4 מקשי כיווץ שונים לכל היותר. המשמעות היא אפליקציית FCM יכולה לשמור בו-זמנית 4 הודעות שונות בכל אפליקציית לקוח. אם תחרוג מהמספר הזה, אי אפשר להבטיח אילו 4 מפתחות כיווץ יישמרו ב-FCM. |
|
priority |
אופציונלי, מחרוזת | הגדרת העדיפות של ההודעה. הערכים החוקיים הם 'רגילים' ו-"high". בפלטפורמות של 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) של התראה, או
האפשרות content_available מוגדרת ל-true עבור הודעה ל-Apple
במכשיר, ההודעה נשלחת דרך נקודות APN, אחרת היא נשלחת באמצעות
FCM
|
תמיכה בתוכן של ההתראות
הטבלאות הבאות מפרטות את הערכים המוגדרים מראש מפתחות שזמינים ליצירת הודעות התראה ל-iOS ול-Android.
פרמטר | שימוש | תיאור |
---|---|---|
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) והתאמה של התוכן של ההתראות מרחוק לשוק המקומי. |
פרמטר | שימוש | תיאור |
---|---|---|
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 כמחרוזת |
ערכי מחרוזת משתנים שיש להשתמש בהם במקום מצייןי הפורמט
צפייה עיצוב ועיצוב לקבלת מידע נוסף. |
פרמטר | שימוש | תיאור |
---|---|---|
title |
אופציונלי, מחרוזת |
כותרת ההתראה. |
body |
אופציונלי, מחרוזת |
גוף ההודעה. |
icon |
אופציונלי, מחרוזת |
כתובת ה-URL שבה נעשה שימוש בסמל ההתראה. |
click_action |
אופציונלי, מחרוזת |
הפעולה שמשויכת לקליק של משתמש על ההתראה. חובה להשתמש ב-HTTPS לכל הערכים של כתובות ה-URL. |
הודעות HTTP במורד הזרם (טקסט פשוט)
בטבלה הבאה מפורטים התחביר של יעדים, אפשרויות ומטען ייעודי (payload) בפורמט פשוט. טקסט downstream של הודעות 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, הערך המפתח לא יכול להיות מילה שמורה ('from', 'message_type' או כל מילה שמתחילה ב-)
"google" או 'gcm'). אסור להשתמש באף אחת מהמילים שמוגדרות בטבלה הזו (כמו |
פרשנות של תגובת הודעה במורד הזרם
שרת האפליקציה צריך להעריך גם את כותרת התגובה להודעה וגם את הגוף שלה כדי לפרש את תגובת ההודעה שנשלחה מ-FCM. בטבלה הבאה מתוארות התשובות האפשריות.
תגובה | תיאור |
---|---|
200 | ההודעה טופלה בהצלחה. גוף התשובה יכלול עוד פרטים על סטטוס ההודעה, אבל הפורמט שלו יהיה תלוי בשאלה אם הבקשה היה JSON או טקסט פשוט. פרטים נוספים זמינים בטבלה 5. |
400 | הכוונה היא רק לבקשות JSON. הקוד הזה מציין שלא ניתן היה לנתח את הבקשה כ-JSON, או שהיא הכילה שדות לא חוקיים (לדוגמה, העברה של מחרוזת במקום מספר). הסיבה המדויקת לכישלון מתוארת בתגובה, וצריך לטפל בבעיה לפני שאפשר לנסות שוב את הבקשה. |
401 | אירעה שגיאה באימות חשבון השולח. |
5xx | שגיאות בטווח 500-599 (כמו 500 או 503) מציינות שהייתה
אירעה שגיאה פנימית בקצה העורפי FCM במהלך הניסיון לעבד את הבקשה, או
השרת אינו זמין באופן זמני (לדוגמה, בגלל חסימות זמניות). השולח צריך לנסות שוב מאוחר יותר, תוך שמירה על כל כותרת Retry-After שכלולה בתגובה. שרתי אפליקציות חייבים להטמיע השהיה מעריכית לפני ניסיון חוזר (exponential backoff). |
בטבלה הבאה מפורטים השדות בגוף התגובה להודעה במורד הזרם (JSON).
פרמטר | שימוש | תיאור |
---|---|---|
multicast_id |
חובה, מספר | מזהה ייחודי (מספר) המזהה של הודעת Multicast. |
success |
חובה, מספר | מספר ההודעות שעובדו ללא שגיאה. |
failure |
שדה חובה, מספר | מספר ההודעות שלא ניתן היה לעבד. |
results |
חובה, מערך של אובייקטים | מערך של אובייקטים שמייצגים את הסטטוס של ההודעות שעברו עיבוד.
האובייקטים מופיעים באותו סדר שבו מופיעה הבקשה (כלומר, לכל רישום
המזהה בבקשה, התוצאה שלה מופיעה באותו אינדקס בתשובה).
|
פרמטר | שימוש | תיאור |
---|---|---|
message_id |
אופציונלי, מספר | מזהה הודעת הנושא כאשר FCM קיבל בהצלחה את הבקשה ו ינסה לשלוח לכל המכשירים שנרשמת אליהם. |
error |
אופציונלי, מחרוזת | שגיאה שהתרחשה במהלך עיבוד ההודעה. הערכים האפשריים מופיעים בטבלה 9. |
פרמטר | שימוש | תיאור |
---|---|---|
id |
חובה, מחרוזת | הפרמטר הזה מציין את מזהה ההודעה הייחודי FCM שעובד בהצלחה. |
registration_id |
אופציונלי, מחרוזת | הפרמטר הזה מציין את טוקן הרישום של אפליקציית הלקוח שאליה הודעת ה-SMS עובדה ונשלחה. |
פרמטר | שימוש | תיאור |
---|---|---|
Error |
חובה, מחרוזת | הפרמטר הזה מציין את ערך השגיאה במהלך עיבוד ההודעה לנמען. פרטים נוספים זמינים בטבלה 9. |
קודי תגובה של שגיאות בהודעות בהמשך
בטבלה הבאה מפורטים קודי התגובה של השגיאות להודעות במורד הזרם.
שגיאה | קוד HTTP | מה מומלץ לעשות? |
---|---|---|
חסר אסימון רישום | 200 + error:MissingRegistration | בודקים שהבקשה מכילה אסימון רישום (בשדה registration_id בהודעת טקסט פשוט, או בשדה to או registration_ids ב-JSON). |
Invalid Registration Token | 200 + שגיאה:רישום לא חוקי | בודקים את הפורמט של אסימון הרישום ששולחים לשרת. כדאי לוודא תואם לאסימון הרישום שאפליקציית הלקוח מקבלת במהלך הרישום ב-Firebase התראות. אין לקצר את השם או להוסיף תווים נוספים. |
מכשיר לא רשום | 200 + error:NotRegistered | אסימון רישום קיים עשוי להפסיק להיות תקף במספר תרחישים, כולל:
|
שם חבילה לא חוקי | 200 + שגיאה:InvalidPackageName | יש לוודא שההודעה ממוענת לאסימון רישום ששם החבילה שלו תואם לערך שהועבר בבקשה. |
שגיאת אימות | 401 | אי אפשר לאמת את חשבון השולח ששימש לשליחת ההודעה. הסיבות האפשריות הן:
|
שולח לא תואם | 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 + שגיאה:לא זמין | השרת לא הצליח לעבד את הבקשה בזמן. לנסות שוב את אותה בקשה, אבל צריך:
שולחים שגורמים לבעיות עלולים להיכנס לרשימת החסימה. |
שגיאת שרת פנימית | 500 או 200 + שגיאה:InternalServerError | השרת נתקל בשגיאה במהלך הניסיון לעבד את הבקשה. אפשר לנסות שוב אותה בקשה בהתאם לדרישות המפורטות ב"זמן קצוב לתפוגה" (עיינו בשורה שלמעלה). אם השגיאה אם היא נמשכת, יש לפנות לתמיכה של Firebase. |
חריגה מקצב ההודעות במכשיר | 200 + שגיאה:
DeviceMessageRate Exceeded |
שיעור ההודעות שנשלחות למכשיר מסוים גבוה מדי. אם אפליקציה של Apple שולחת הודעות בקצב שמחרוג מהמגבלות של APN, יכול להיות שתופיע הודעת השגיאה הזו מצמצמים את מספר ההודעות שנשלחו למכשיר הזה, שימוש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כדי לנסות לשלוח שוב. |
חריגה מקצב שליחת ההודעות בנושאים | 200 + שגיאה:
TopicsMessageRate חריגה |
שיעור ההודעות למנויים בנושא מסוים גבוה מדי. מצמצמים את מספר ההודעות שנשלחו בנושא הזה, וגם שימוש בהשהיה מעריכית לפני ניסיון חוזר (exponential backoff) כדי לנסות לשלוח שוב. |
פרטי כניסה לא תקינים של APN | 200 + שגיאה:
InvalidApnsCredential |
לא ניתן היה לשלוח הודעה שמטורגטת למכשיר Apple כי מפתח האימות הנדרש של APNs לא הועלה או שתוקפו פג. בודקים את התקינות של פרטי הכניסה לפיתוח ולייצור. |
ניהול קבוצות מכשירים
בטבלה הבאה מפורטים המפתחות ליצירת קבוצות מכשירים ולצירוף והסרה של חברים. למידע נוסף, אפשר לעיין במדריך לפלטפורמה שלכם: iOS+ או Android.
פרמטר | שימוש | תיאור |
---|---|---|
operation |
חובה, מחרוזת | הפעולה להרצה. הערכים החוקיים הם create , add ו-remove . |
notification_key_name |
שדה חובה, מחרוזת | השם שהוגדר על ידי המשתמש של קבוצת המכשירים ליצירה או לשינוי. |
notification_key |
חובה (למעט פעולה create , מחרוזת) |
המזהה הייחודי של קבוצת המכשירים. הערך הזה
מוחזר בתגובה עבור ערך create מוצלח
והוא
שנדרשת לכל הפעולות הבאות בקבוצת המכשירים. |
registration_ids |
נדרש, מערך מחרוזות | האסימונים של המכשיר שרוצים להוסיף או להסיר. אם מסירים את כל אסימוני רישום מקבוצת מכשירים, FCM מוחק את קבוצת המכשירים. |