מסמך זה מספק הפניה לתחביר ה-HTTP המשמש להעברת הודעות משרת האפליקציות שלך לאפליקציות לקוח באמצעות Firebase Cloud Messaging.
בעת שימוש בפרוטוקול HTTP מדור קודם, שרת האפליקציות שלך חייב להפנות את כל בקשות ה-HTTP לנקודת קצה זו:
https://fcm.googleapis.com/fcm/send
הפרמטרים והאפשרויות הזמינים מתחלקים לקטגוריות הרחבות הבאות:
תחביר הודעות במורד הזרם
סעיף זה נותן את התחביר לשליחת הודעות במורד הזרם ולפענוח תגובות HTTP מ-Firebase Cloud Messaging.
הודעות HTTP במורד זרם (JSON)
הטבלה הבאה מפרטת את היעדים, האפשרויות והמטען עבור הודעות HTTP JSON.
פָּרָמֶטֶר | נוֹהָג | תיאור | |
---|---|---|---|
יעדים | |||
to | אופציונלי, מחרוזת | פרמטר זה מציין את הנמען של הודעה. הערך יכול להיות אסימון רישום של מכשיר, מפתח הודעות של קבוצת מכשירים, או נושא בודד (עם קידומת | |
registration_ids | אופציונלי, מערך של מחרוזות | פרמטר זה מציין את הנמען של הודעת ריבוי שידור, הודעה שנשלחה ליותר מאסימון רישום אחד. הערך צריך להיות מערך של אסימוני רישום שאליהם יש לשלוח את הודעת השידור המרובה. המערך חייב להכיל לפחות 1 ולכל היותר 1000 אסימוני רישום. כדי לשלוח הודעה למכשיר בודד, השתמש בפרמטר הודעות ריבוי שידור מותרות רק בפורמט HTTP JSON. | |
condition | אופציונלי, מחרוזת | פרמטר זה מציין ביטוי לוגי של תנאים הקובעים את יעד ההודעה. תנאי נתמך: נושא, מעוצב כ"הנושא שלך" בנושאים. ערך זה אינו תלוי רישיות. אופרטורים נתמכים: | |
notification_key הוצא משימוש | אופציונלי, מחרוזת | פרמטר זה הוצא משימוש. במקום זאת, השתמש | |
אפשרויות | |||
collapse_key | אופציונלי, מחרוזת | פרמטר זה מזהה קבוצת הודעות (למשל, עם שימו לב שאין ערובה לסדר שליחת ההודעות. הערה: מותר לכל היותר 4 מפתחות כיווץ שונים בכל זמן נתון. המשמעות היא ש-FCM יכולה לאחסן בו זמנית 4 הודעות שונות לכל אפליקציית לקוח. אם תחרוג ממספר זה, אין ערובה אילו 4 מפתחות כיווץ FCM ישמור. | |
priority | אופציונלי, מחרוזת | קובע את העדיפות של ההודעה. ערכים חוקיים הם "רגיל" ו"גבוה". בפלטפורמות של אפל, אלה תואמים את סדר העדיפויות של APN 5 ו-10. כברירת מחדל, הודעות התראה נשלחות בעדיפות גבוהה, והודעות נתונים נשלחות בעדיפות רגילה. עדיפות רגילה מייעלת את צריכת הסוללה של אפליקציית הלקוח ויש להשתמש בה אלא אם נדרשת אספקה מיידית. עבור הודעות עם עדיפות רגילה, האפליקציה עשויה לקבל את ההודעה באיחור לא מוגדר. כאשר הודעה נשלחת בעדיפות גבוהה, היא נשלחת מיד, והאפליקציה יכולה להציג התראה. | |
content_available | אופציונלי, בוליאני | בפלטפורמות של Apple, השתמש בשדה זה כדי לייצג | |
mutable_content | אופציונלי, JSON בוליאני | בפלטפורמות של Apple, השתמש בשדה זה כדי לייצג | |
time_to_live | אופציונלי, מספר | פרמטר זה מציין כמה זמן (בשניות) ההודעה צריכה להישמר באחסון FCM אם המכשיר לא מקוון. הזמן המקסימלי לחיות בתמיכה הוא 4 שבועות, וערך ברירת המחדל הוא 4 שבועות. למידע נוסף, ראה הגדרת תוחלת החיים של הודעה . | |
restricted_package_ (אנדרואיד בלבד) | אופציונלי, מחרוזת | פרמטר זה מציין את שם החבילה של האפליקציה שבה חייבים להתאים אסימוני הרישום כדי לקבל את ההודעה. | |
dry_run | אופציונלי, בוליאני | פרמטר זה, כאשר הוא מוגדר כ- ערך ברירת המחדל הוא | |
מטען | |||
data | אופציונלי, חפץ | פרמטר זה מציין את צמדי המפתח-ערך המותאמים אישית של המטען של ההודעה. לדוגמה, עם בפלטפורמות של Apple, אם ההודעה נשלחת דרך APN, היא מייצגת את שדות הנתונים המותאמים אישית. אם הוא נשלח באמצעות FCM, הוא יוצג כמילון ערך מפתח ב-Android, זה יביא המפתח לא צריך להיות מילה שמורה ("from", "message_type", או כל מילה שמתחילה ב-"google" או "gcm"). אל תשתמש באף אחת מהמילים המוגדרות בטבלה זו (כגון ערכים בסוגי מחרוזת מומלצים. עליך להמיר ערכים באובייקטים או בסוגי נתונים אחרים שאינם מחרוזים (למשל, מספרים שלמים או בוליאנים) למחרוזת. | |
notification | אופציונלי, חפץ | פרמטר זה מציין את צמדי המפתח-ערך המוגדרים מראש, גלויים למשתמש, של מטען ההודעות. ראה תמיכת מטען הודעות לפרטים. למידע נוסף על אפשרויות הודעות הודעה והודעות נתונים, ראה סוגי הודעות . אם מסופק מטען הודעה, או שהאפשרות content_available מוגדרת כ- true עבור הודעה למכשיר Apple, ההודעה נשלחת דרך APNs , אחרת היא נשלחת דרך FCM. |
תמיכה במטען הודעות
הטבלאות הבאות מפרטות את המפתחות המוגדרים מראש הזמינים לבניית הודעות התראות עבור iOS ו-Android.
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
title | אופציונלי, מחרוזת | כותרת ההודעה. שדה זה אינו גלוי בטלפונים ובטאבלטים. |
body | אופציונלי, מחרוזת | גוף ההודעה. |
sound | אופציונלי, מחרוזת | הצליל שיש לנגן כאשר המכשיר מקבל את ההתראה. מחרוזת המציינת קבצי קול בחבילה הראשית של אפליקציית הלקוח או בתיקיית |
badge | אופציונלי, מחרוזת | הערך של התג בסמל האפליקציה של מסך הבית. אם לא צוין, התג לא משתנה. אם מוגדר ל |
click_action | אופציונלי, מחרוזת | הפעולה המשויכת למשתמש לחץ על ההודעה. מתאים |
subtitle | אופציונלי, מחרוזת | כותרת המשנה של ההודעה. |
body_loc_key | אופציונלי, מחרוזת | המפתח למחרוזת הגוף במשאבי המחרוזת של האפליקציה לשימוש כדי לבצע לוקליזציה של טקסט הגוף ללוקליזציה הנוכחית של המשתמש. מתאים ראה הפניה למפתח מטען ולוקליזציה של התוכן של ההודעות המרוחקות שלך למידע נוסף. |
body_loc_args | אופציונלי, מערך JSON כמחרוזת | ערכי מחרוזת משתנים שישמשו במקום מפרטי הפורמט ב- מתאים ל- ראה הפניה למפתח מטען ולוקליזציה של התוכן של ההודעות המרוחקות שלך למידע נוסף. |
title_loc_key | אופציונלי, מחרוזת | המפתח למחרוזת הכותרת במשאבי המחרוזת של האפליקציה לשימוש כדי לבצע לוקליזציה של טקסט הכותרת ללוקליזציה הנוכחית של המשתמש. מקביל ל- ראה הפניה למפתח מטען ולוקליזציה של התוכן של ההודעות המרוחקות שלך למידע נוסף. |
title_loc_args | אופציונלי, מערך JSON כמחרוזת | ערכי מחרוזת משתנים שישמשו במקום מפרטי הפורמט ב- מתאים ל- ראה הפניה למפתח מטען ולוקליזציה של התוכן של ההודעות המרוחקות שלך למידע נוסף. |
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
title | אופציונלי, מחרוזת | כותרת ההודעה. |
body | אופציונלי, מחרוזת | גוף ההודעה. |
android_channel_id | אופציונלי, מחרוזת | מזהה הערוץ של ההתראה (חדש באנדרואיד O). האפליקציה חייבת ליצור ערוץ עם מזהה ערוץ זה לפני שמתקבלת התראה עם מזהה ערוץ זה. אם לא תשלח את מזהה הערוץ הזה בבקשה, או אם מזהה הערוץ שסופק עדיין לא נוצר על ידי האפליקציה, FCM משתמש במזהה הערוץ שצוין במניפסט האפליקציה. |
icon | אופציונלי, מחרוזת | סמל ההודעה. מגדיר את סמל ההתראה ל- |
sound | אופציונלי, מחרוזת | הצליל שיש לנגן כאשר המכשיר מקבל את ההתראה. תומך |
tag | אופציונלי, מחרוזת | מזהה המשמש להחלפת הודעות קיימות במגירת ההודעות. אם לא צוין, כל בקשה יוצרת הודעה חדשה. אם צוין וכבר מוצגת הודעה עם אותו תג, ההודעה החדשה מחליפה את הקיימת במגירת ההודעות. |
color | אופציונלי, מחרוזת | צבע הסמל של ההודעה, מבוטא בפורמט |
click_action | אופציונלי, מחרוזת | הפעולה המשויכת למשתמש לחץ על ההודעה. אם צוין, פעילות עם מסנן כוונות תואם מופעלת כאשר משתמש לוחץ על ההודעה. |
body_loc_key | אופציונלי, מחרוזת | המפתח למחרוזת הגוף במשאבי המחרוזת של האפליקציה לשימוש כדי לבצע לוקליזציה של טקסט הגוף ללוקליזציה הנוכחית של המשתמש. ראה משאבי מחרוזת למידע נוסף. |
body_loc_args | אופציונלי, מערך JSON כמחרוזת | ערכי מחרוזת משתנים שישמשו במקום מפרטי הפורמט ב- ראה עיצוב ועיצוב למידע נוסף. |
title_loc_key | אופציונלי, מחרוזת | המפתח למחרוזת הכותרת במשאבי המחרוזת של האפליקציה לשימוש כדי לבצע לוקליזציה של טקסט הכותרת ללוקליזציה הנוכחית של המשתמש. ראה משאבי מחרוזת למידע נוסף. |
title_loc_args | אופציונלי, מערך JSON כמחרוזת | ערכי מחרוזת משתנים שישמשו במקום מפרטי הפורמט ב- ראה עיצוב ועיצוב למידע נוסף. |
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
title | אופציונלי, מחרוזת | כותרת ההודעה. |
body | אופציונלי, מחרוזת | גוף ההודעה. |
icon | אופציונלי, מחרוזת | כתובת האתר לשימוש עבור סמל ההודעה. |
click_action | אופציונלי, מחרוזת | הפעולה המשויכת למשתמש לחץ על ההודעה. עבור כל ערכי כתובת האתר, יש צורך ב-HTTPS. |
הודעות HTTP במורד הזרם (טקסט רגיל)
הטבלה הבאה מפרטת את התחביר עבור יעדים, אפשרויות ומטען בטקסט רגיל במורד הזרם של הודעות HTTP.
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
יעדים | ||
registration_id | חובה, מחרוזת | פרמטר זה מציין את יישומי הלקוח (אסימוני רישום) שמקבלים את ההודעה. העברת הודעות ריבוי שידור (שליחה ליותר מאסימון רישום אחד) מותרת בפורמט HTTP JSON בלבד. |
אפשרויות | ||
collapse_key | אופציונלי, מחרוזת | ראה טבלה 1 לפרטים. |
time_to_live | אופציונלי, מספר | ראה טבלה 1 לפרטים. |
restricted_package_name | אופציונלי, מחרוזת | ראה טבלה 1 לפרטים. |
dry_run | אופציונלי, בוליאני | ראה טבלה 1 לפרטים. |
מטען | ||
data.<key> | אופציונלי, מחרוזת | פרמטר זה מציין את צמדי המפתח-ערך של מטען ההודעה. אין הגבלה על מספר הפרמטרים של ערך מפתח, אבל יש מגבלה כוללת של גודל הודעה של 4000 בתים. לדוגמה, באנדרואיד, המפתח לא צריך להיות מילה שמורה ("from", "message_type", או כל מילה שמתחילה ב-"google" או "gcm"). אל תשתמש באף אחת מהמילים המוגדרות בטבלה זו (כגון |
פירוש תגובת הודעה במורד הזרם
שרת האפליקציה צריך להעריך הן את כותרת תגובת ההודעה והן את הגוף כדי לפרש את תגובת ההודעה שנשלחה מ-FCM. הטבלה הבאה מתארת את התגובות האפשריות.
תְגוּבָה | תיאור |
---|---|
200 | ההודעה עובדה בהצלחה. גוף התגובה יכיל פרטים נוספים על סטטוס ההודעה, אך הפורמט שלה יהיה תלוי אם הבקשה הייתה JSON או טקסט רגיל. ראה טבלה 5 לפרטים נוספים. |
400 | חל רק על בקשות JSON. מציין שלא ניתן היה לנתח את הבקשה כ-JSON, או שהיא הכילה שדות לא חוקיים (לדוגמה, העברת מחרוזת שבה היה צפוי מספר). סיבת הכישלון המדויקת מתוארת בתגובה ויש לטפל בבעיה לפני שניתן לנסות שוב את הבקשה. |
401 | אירעה שגיאה באימות חשבון השולח. |
5xx | שגיאות בטווח 500-599 (כגון 500 או 503) מצביעות על כך שהייתה שגיאה פנימית ב-backend של FCM בעת ניסיון לעבד את הבקשה, או שהשרת אינו זמין באופן זמני (לדוגמה, בגלל פסק זמן). השולח חייב לנסות שוב מאוחר יותר, תוך מתן כבוד לכל כותרת Retry-After שנכלל בתגובה. שרתי יישומים חייבים ליישם גיבוי אקספוננציאלי. |
הטבלה הבאה מפרטת את השדות בגוף תגובה להודעה במורד הזרם (JSON).
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
multicast_id | חובה, מספר | מזהה (מספר) ייחודי המזהה את הודעת השידור המרובה. |
success | חובה, מספר | מספר ההודעות שעובדו ללא שגיאה. |
failure | חובה, מספר | מספר ההודעות שלא ניתן היה לעבד. |
results | חובה, מערך חפצים | מערך אובייקטים המייצג את מצב ההודעות שעובדו. האובייקטים רשומים באותו סדר כמו הבקשה (כלומר, עבור כל מזהה רישום בבקשה, התוצאה שלו רשומה באותו אינדקס בתגובה).
|
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
message_id | אופציונלי, מספר | מזהה הודעת הנושא כאשר FCM קיבל בהצלחה את הבקשה וינסה לשלוח לכל המכשירים הרשומים. |
error | אופציונלי, מחרוזת | שגיאה שהתרחשה בעת עיבוד ההודעה. ניתן למצוא את הערכים האפשריים בטבלה 9 . |
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
id | חובה, מחרוזת | פרמטר זה מציין את מזהה ההודעה הייחודי FCM שעובד בהצלחה. |
registration_id | אופציונלי, מחרוזת | פרמטר זה מציין את אסימון הרישום עבור אפליקציית הלקוח שאליה ההודעה עובדה ונשלחה. |
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
Error | חובה, מחרוזת | פרמטר זה מציין את ערך השגיאה בעת עיבוד ההודעה עבור הנמען. ראה טבלה 9 לפרטים. |
קודי תגובה של שגיאה בהודעה במורד הזרם
הטבלה הבאה מפרטת את קודי התגובה לשגיאה עבור הודעות במורד הזרם.
שְׁגִיאָה | קוד HTTP | פעולה מומלצת |
---|---|---|
חסר אסימון רישום | 200 + שגיאה:MissingRegistration | בדוק שהבקשה מכילה אסימון רישום (ב- registration_id בהודעת טקסט רגילה, או בשדה to או registration_ids ב-JSON). |
אסימון רישום לא חוקי | 200 + שגיאה:רישום לא חוקי | בדוק את הפורמט של אסימון הרישום שאתה מעביר לשרת. ודא שהוא תואם את אסימון הרישום שאפליקציית הלקוח מקבלת מההרשמה ל-Firebase Notifications. אין לקטוע או להוסיף תווים נוספים. |
מכשיר לא רשום | 200 + שגיאה: לא רשום | אסימון רישום קיים עשוי להפסיק להיות תקף במספר תרחישים, כולל:
|
שם חבילה לא חוקי | 200 + error:InvalidPackageName | ודא שההודעה הופנתה לאסימון רישום ששם החבילה שלו תואם לערך שהועבר בבקשה. |
שגיאת אימות | 401 | לא ניתן היה לאמת את חשבון השולח ששימש לשליחת הודעה. סיבות אפשריות הן:
|
השולח לא תואם | 200 + error:MismatchSenderId | אסימון רישום קשור לקבוצה מסוימת של שולחים. כאשר אפליקציית לקוח נרשמה ל-FCM, עליה לציין אילו שולחים רשאים לשלוח הודעות. עליך להשתמש באחד מאותם מזהי שולח בעת שליחת הודעות לאפליקציית הלקוח. אם תעבור לשולח אחר, אסימוני הרישום הקיימים לא יפעלו. |
JSON לא חוקי | 400 | בדוק שהודעת ה-JSON מעוצבת כהלכה ומכילה שדות חוקיים (לדוגמה, וודא שסוג הנתונים הנכון מועבר). |
פרמטרים לא חוקיים | 400 + error:InvalidParameters | בדוק שלפרמטרים שסופקו יש את השם והסוג הנכונים. |
הודעה גדולה מדי | 200 + שגיאה: MessageTooBig | בדוק שהגודל הכולל של נתוני המטען הכלולים בהודעה אינו חורג ממגבלות FCM: 4096 בתים עבור רוב ההודעות, או 2048 בתים במקרה של הודעות לנושאים. זה כולל גם את המפתחות וגם את הערכים. |
מפתח נתונים לא חוקי | 200 + שגיאה: InvalidDataKey | בדוק שנתוני המטען אינם מכילים מפתח (כגון from , או gcm , או ערך כלשהו עם קידומת google ) שנמצא בשימוש פנימי על ידי FCM. שים לב שמילים מסוימות (כגון collapse_key ) משמשות גם על ידי FCM אך מותרות במטען, ובמקרה זה ערך המטען יעקוף על ידי ערך FCM. |
זמן לא חוקי לחיות | 200 + שגיאה:InvalidTtl | בדוק שהערך המשמש ב- time_to_live הוא מספר שלם המייצג משך בשניות בין 0 ל-2,419,200 (4 שבועות). |
פסק זמן | 5xx או 200 + שגיאה: לא זמין | השרת לא הצליח לעבד את הבקשה בזמן. נסה שוב את אותה בקשה, אך עליך:
שולחים שגורמים לבעיות מסתכנים ברשימה השחורה. |
שגיאת שרת פנימית | 500 או 200 + שגיאה:InternalServerError | השרת נתקל בשגיאה בעת ניסיון לעבד את הבקשה. תוכל לנסות שוב את אותה בקשה בהתאם לדרישות המפורטות ב"זמן קצוב" (ראה שורה למעלה). אם השגיאה נמשכת, פנה לתמיכה של Firebase . |
קצב הודעת ההתקן חרג | 200 + שגיאה: DeviceMessageRate חרג | קצב ההודעות למכשיר מסוים גבוה מדי. אם אפליקציה של אפל שולחת הודעות בקצב העולה על מגבלות ה-APN, היא עשויה לקבל הודעת שגיאה זו צמצם את מספר ההודעות שנשלחות למכשיר זה והשתמש ב-backoff אקספוננציאלי כדי לנסות לשלוח שוב. |
קצב הודעות נושאים חרג | 200 + שגיאה: TopicsMessageRate חרג | שיעור ההודעות למנויים לנושא מסוים גבוה מדי. צמצם את מספר ההודעות שנשלחו עבור נושא זה והשתמש ב-backoff אקספוננציאלי כדי לנסות לשלוח שוב. |
אישורי APN לא חוקיים | 200 + שגיאה: InvalidApnsCredential | לא ניתן לשלוח הודעה המיועדת למכשיר אפל מכיוון שמפתח האימות הנדרש של APN לא הועלה או שפג תוקפו. בדוק את תקפות אישורי הפיתוח והייצור שלך. |
ניהול קבוצת מכשירים
הטבלה הבאה מפרטת את המפתחות ליצירת קבוצות מכשירים והוספה והסרה של חברים. למידע נוסף, עיין במדריך עבור הפלטפורמה שלך, iOS+ או Android .
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
operation | חובה, מחרוזת | הפעולה להפעלה. ערכים חוקיים הם create , add remove . |
notification_key_name | חובה, מחרוזת | השם המוגדר על ידי המשתמש של קבוצת המכשירים שיש ליצור או לשנות. |
notification_key | נדרש (למעט פעולת create , מחרוזת | מזהה ייחודי של קבוצת המכשירים. ערך זה מוחזר בתגובה לפעולת create מוצלחת, ונדרש עבור כל הפעולות הבאות בקבוצת המכשירים. |
registration_ids | חובה, מערך של מחרוזות | אסימוני המכשיר להוספה או הסרה. אם תסיר את כל אסימוני הרישום הקיימים מקבוצת מכשירים, FCM תמחק את קבוצת המכשירים. |