במסמך הזה יש הפניה לתחביר ה-XMPP שמשמש להעברה הודעות בין שרת האפליקציה, אפליקציות הלקוח ו-Firebase Cloud Messaging (FCM). שרת האפליקציה צריך להתחבר לנקודות הקצה הבאות:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
הפרמטרים הזמינים האפשרויות נכללות בקטגוריות הבאות:
- תחביר של הודעות במורד הזרם
- קודי תגובה של שגיאות בהודעות במורד הזרם
- תחביר של הודעות ב-Upstream
- FCM הודעות שליטה
תחביר ההודעות במורד הזרם
בקטע הזה מצוין התחביר לשליחת הודעות במורד הזרם (downstream).
הודעות XMPP במורד הזרם (JSON)
בטבלה הבאה מפורטים היעדים, האפשרויות והמטען הייעודי (payload) של XMPP JSON. הודעות.
פרמטר | שימוש | תיאור | |
---|---|---|---|
Target | |||
to |
אופציונלי, מחרוזת |
הפרמטר הזה מציין את הנמען של ההודעה.
הערך יכול להיות אסימון רישום של מכשיר,
מקש התראה או נושא יחיד (עם קידומת
|
|
condition |
אופציונלי, מחרוזת | הפרמטר הזה מציין ביטוי לוגי של תנאים קובע את יעד ההודעה. תנאי נתמך: נושא, בפורמט ''yourTopic' in topics'. הערך הזה לא תלוי רישיות. אופרטורים נתמכים: |
|
אפשרויות | |||
message_id |
שדה חובה, מחרוזת | הפרמטר הזה מזהה באופן ייחודי הודעה בחיבור XMPP. |
|
collapse_key |
אופציונלי, מחרוזת | הפרמטר הזה מזהה קבוצה של הודעות (למשל,
אין ערובה לסדר שבו ההודעות נשלחות. הערה: בכל רגע נתון מותר להשתמש ב-4 מקשי כיווץ שונים לכל היותר. המשמעות היא ש-FCM יכול לאחסן בו-זמנית 4 הודעות שונות לכל אפליקציית לקוח. אם חורגים מהמספר הזה, אין ערובה לאילו 4 מפתחות קריסת נתונים FCM ישמור. |
|
priority |
אופציונלי, מחרוזת | מגדיר את עדיפות ההודעה. הערכים החוקיים הם 'רגילים' ו-"high". בפלטפורמות של Apple, הערכים האלה תואמים לעדיפויות APN 5 ו-10. כברירת מחדל, הודעות התראה נשלחות בעדיפות גבוהה והודעות נתונים נשלחים בעדיפות רגילה. עדיפות רגילה מבצעת אופטימיזציה של אפליקציית הלקוח צריכת הסוללה ויש להשתמש בה אלא אם נדרשת שליחה מיידית. כשמדובר בהודעות עם עדיפות רגילה, האפליקציה עשויה לקבל את ההודעה עם עיכוב לא מוגדר. כששולחים הודעה בעדיפות גבוהה, היא נשלחת באופן מיידי והאפליקציה יכולה להציג התראה. |
|
content_available |
אופציונלי, ערך בוליאני | בפלטפורמות של Apple, צריך להשתמש בשדה הזה כדי לייצג את |
|
mutable_content |
אופציונלי, ערך בוליאני של JSON | בפלטפורמות של Apple, משתמשים בשדה הזה כדי לייצג
|
|
time_to_live |
אופציונלי, מספר | הפרמטר הזה מציין למשך כמה זמן (בשניות) ההודעה צריכה להישמר באחסון של FCM אם המכשיר במצב אופליין. משך החיים המקסימלי שנתמך הוא 4 שבועות, וערך ברירת המחדל הוא 4 שבועות. מידע נוסף זמין במאמר הגדרת משך החיים של הודעה. |
|
dry_run |
אופציונלי, ערך בוליאני | כשהפרמטר הזה מוגדר ל- ערך ברירת המחדל הוא |
|
מטען ייעודי (payload) | |||
data |
אופציונלי, אובייקט | הפרמטר הזה מציין את צמדי המפתח-ערך של מטען הייעודי של ההודעה. לדוגמה, באמצעות בפלטפורמות של Apple, אם ההודעה נשלחת על ידי APNs, היא מייצגת את שדות הנתונים המותאמים אישית. אם המיקום
הוא נמסר על ידי FCM,
הוא מיוצג כמילון של ערכי מפתח ב ב-Android, התוצאה תהיה תוספת Intent בשם המפתח לא יכול להיות מילה שמוגדרת לשימוש מיוחד ('from', 'message_type' או כל מילה שמתחילה ב-'google' או ב-'gcm'). אסור להשתמש באף אחת מהמילים שמוגדרות בטבלה הזו (כמו מומלץ להשתמש בערכים מסוג מחרוזת. צריך להמיר ערכים באובייקטים או בסוגים אחרים של נתונים שאינם מחרוזות (למשל, מספרים שלמים או ערכים בוליאניים) למחרוזת. |
|
notification |
אופציונלי, אובייקט | הפרמטר הזה מציין את צמד המפתח/ערך המוגדר מראש שגלוי למשתמש, שנמצא בתוכן של ההתראה. פרטים נוספים זמינים במאמר בנושא תמיכה במטען הייעודי של ההתראות. מידע נוסף על אפשרויות של הודעות התראה והודעות נתונים זמין במאמר סוגי הודעות. אם צוין עומס שימושי של התראה, או שהאפשרות content_available מוגדרת כ-true להודעה למכשיר Apple, ההודעה נשלחת דרך APNs. אחרת, היא נשלחת דרך FCM.
|
תמיכה בתוכן של ההתראות
הטבלאות הבאות מפרטות את הערכים המוגדרים מראש מפתחות שזמינים ליצירת הודעות התראה עבור פלטפורמות של Apple ו-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 |
אופציונלי, מחרוזת |
הפעולה שמשויכת ללחיצה של משתמש על ההתראה. אם צוין, פעילות עם מסנן כוונה תואם תושק כשהמשתמש ילחץ על ההתראה. |
body_loc_key |
אופציונלי, מחרוזת |
המפתח למחרוזת הגוף במשאבי המחרוזות של האפליקציה, שמשמש להתאמה של טקסט הגוף ללוקליזציה הנוכחית של המשתמש. למידע נוסף, ראו משאבי מחרוזות. |
body_loc_args |
אופציונלי, מערך JSON כמחרוזת |
ערכי מחרוזת משתנים שיש להשתמש בהם במקום מצייןי הפורמט
למידע נוסף, ראו עיצוב פורמטים. |
title_loc_key |
אופציונלי, מחרוזת |
המפתח למחרוזת הכותרת במשאבי המחרוזת של האפליקציה, שבו יש להשתמש כדי התאמה לשוק המקומי של טקסט הכותרת בהתאם לשוק המקומי הנוכחי של המשתמש. למידע נוסף, ראו משאבי מחרוזות. |
title_loc_args |
מערך אופציונלי של JSON כמחרוזת |
ערכי מחרוזת משתנים שיש להשתמש בהם במקום מצייןי הפורמט
למידע נוסף, ראו עיצוב פורמטים. |
פרמטר | שימוש | תיאור |
---|---|---|
title |
אופציונלי, מחרוזת |
כותרת ההתראה. |
body |
אופציונלי, מחרוזת |
גוף ההודעה. |
icon |
אופציונלי, מחרוזת |
כתובת ה-URL שבה צריך להשתמש עבור סמל ההתראה. |
click_action |
אופציונלי, מחרוזת |
הפעולה שמשויכת ללחיצה של משתמש על ההתראה. חובה להשתמש ב-HTTPS לכל הערכים של כתובות ה-URL. |
פרשנות של תגובה להודעת XMPP במורד הזרם
הטבלה הבאה מפרטת את השדות שמופיעים בתגובה להודעת XMPP במורד הזרם.
פרמטר | שימוש | תיאור |
---|---|---|
from |
שדה חובה, מחרוזת | הפרמטר הזה מציין מי שלח את התשובה הזו. הערך הוא אסימון הרישום של אפליקציית הלקוח. |
message_id |
שדה חובה, מחרוזת | הפרמטר הזה מזהה באופן ייחודי הודעה בחיבור XMPP. הערך הוא מחרוזת שמזהה באופן ייחודי את ההודעה המשויכת. |
message_type |
שדה חובה, מחרוזת | הפרמטר הזה מציין הודעת אם הערך מוגדר כ- |
error |
אופציונלי, מחרוזת | הפרמטר הזה מציין שגיאה שקשורה להודעת ה-downstream. הוא מוגדר כשהערך של message_type הוא nack . פרטים נוספים זמינים בטבלה 4. |
error_description |
אופציונלי, מחרוזת | הפרמטר הזה מספק מידע תיאורי של השגיאה. הוא מוגדר
כשהערך בשדה message_type הוא nack . |
קודי תגובה לשגיאות בהודעות במורד הזרם
בטבלה הבאה מפורטים קודי התגובה של השגיאות להודעות במורד הזרם.
שגיאה | קוד XMPP | הפעולה המומלצת |
---|---|---|
חסר טוקן רישום | INVALID_JSON |
ודאו שהבקשה מכילה אסימון רישום (בקוד של
registration_id בהודעת טקסט פשוטה, או ב-to
או registration_ids ב-JSON). |
רישום לא תקין של APNs | INVALID_JSON |
ברישומים ל-iOS, צריך לוודא שבקשת הרישום מהלקוח מכילה אסימון APNs ומזהה אפליקציה תקפים. |
Invalid Registration Token | BAD_REGISTRATION |
כדאי לבדוק את הפורמט של אסימון הרישום שאתם מעבירים לשרת. מוודאים שהוא תואם לאסימון הרישום שאפליקציית הלקוח מקבלת מהרישום ב-FCM. אין לקצר את השם או להוסיף לו תווים. |
מכשיר לא רשום | DEVICE_UNREGISTERED |
אסימון רישום קיים עשוי להפסיק להיות תקף במספר תרחישים, כולל:
|
שולח לא תואם | SENDER_ID_MISMATCH |
אסימון רישום מקושר לקבוצה מסוימת של שולחים. כשאפליקציית לקוח נרשמת ל-FCM, היא צריכה לציין אילו שולחים מורשים לשלוח הודעות. עליך להשתמש באחד של מזהי השולחים האלה במהלך שליחת הודעות לאפליקציית הלקוח. אם עוברים לכתובת אחרת שולח, אסימוני הרישום הקיימים לא יעבדו. |
JSON לא תקין | INVALID_JSON |
בודקים שההודעה בפורמט JSON תקינה ושהיא מכילה שדות תקינים (למשל, מוודאים שסוג הנתונים הנכון מועבר). |
ההודעה גדולה מדי | INVALID_JSON |
חשוב לוודא שהגודל הכולל של נתוני עומס העבודה (payload) שכלולים בהודעה לא חורג מהמגבלות של FCM: 4096 בייטים ברוב ההודעות או 2048 בייטים במקרה של הודעות לנושאים. האיסור הזה כולל את המפתחות והערכים. |
מפתח נתונים לא תקין | INVALID_JSON |
צריך לבדוק שנתוני המטען הייעודי (Payload) לא מכילים מפתח (למשל from ,
gcm , או כל ערך אחר
התחילית של המאפיין הזה היא google ) שנמצא בשימוש פנימי על ידי FCM. יש לשים לב שיש מילים (כמו collapse_key )
משמשים גם את FCM, אבל הם מותרים במטען הייעודי (Payload), ובמקרה כזה
הערך של FCM מבטלים את ערך המטען הייעודי (Payload). |
אורך החיים לא חוקי | INVALID_JSON |
צריך לבדוק שהערך שנעשה בו שימוש ב-time_to_live הוא מספר שלם שמייצג
משך בשניות בין 0 ל-2,419,200 (4 שבועות). |
הודעת ACK לא תקינה | BAD_ACK |
לפני שמנסים שוב, צריך לבדוק שהפורמט של ההודעה ack תקין. צפייה
טבלה 6 לפרטים נוספים. |
זמן קצוב לתפוגה | SERVICE_UNAVAILABLE |
השרת לא הצליח לעבד את הבקשה בזמן. לנסות שוב את אותה בקשה, אבל צריך:
הערה: שולחים שגורמים לבעיות עלולים להיכנס לרשימת החסימה. |
שגיאת שרת פנימית | INTERNAL_SERVER_
|
השרת נתקל בשגיאה במהלך הניסיון לעבד את הבקשה. אפשר לנסות שוב אותה בקשה בהתאם לדרישות המפורטות ב"זמן קצוב לתפוגה" (עיינו בשורה שלמעלה). |
חרגת מהשיעור המרבי של שליחת הודעות מהמכשיר | DEVICE_MESSAGE_RATE |
קצב ההודעות למכשיר מסוים גבוה מדי. כדאי לצמצם את מספר ההודעות שנשלחות למכשיר הזה, ולא לנסות שוב לשלוח הודעות למכשיר הזה באופן מיידי. |
חריגה מקצב שליחת ההודעות בנושאים | TOPICS_MESSAGE_RATE |
שיעור ההודעות למנויים בנושא מסוים גבוה מדי. מצמצמים את מספר ההודעות שנשלחו בנושא הזה, ואל תנסה לשלוח אותו שוב באופן מיידי. |
ריקון החיבור | CONNECTION_DRAINING |
אי אפשר לעבד את ההודעה כי החיבור מתרוקן. הסיבה לכך היא: מדי פעם, FCM צריך לסגור את החיבור כדי לבצע איזון עומסים. ניסיון חוזר של ההודעה חיבור XMPP אחר. |
פרטי כניסה לא חוקיים של APN | INVALID_APNS_CREDENTIAL |
לא ניתן היה לשלוח הודעה שמטורגטת למכשיר iOS כי מפתח האימות הנדרש של APNs לא הועלה או שתוקפו פג. איך לבדוק את תוקף הפיתוח ועל פרטי הכניסה לסביבת הייצור. |
האימות נכשל | AUTHENTICATION_FAILED |
האימות באמצעות שירותי דחיפה חיצוניים נכשל. בודקים אם אתם משתמשים באישורי ה-Web Push הנכונים. |
תחביר של הודעות ב-upstream
הודעת upstream היא הודעה שאפליקציית הלקוח שולחת לשרת של האפליקציה. בשלב הזה רק XMPP תומך בהעברת הודעות בכיוון 'מעלה'. למידע נוסף על שליחת הודעות מאפליקציות לקוח, אפשר לעיין במסמכי התיעוד של הפלטפורמה.
פירוש של הודעת XMPP ב-upstream
הטבלה הבאה מתארת את השדות בבית ה-XMPP שנוצר מאת FCM בתגובה לבקשות להצגת הודעות ב-upstream מאפליקציות של לקוח.
פרמטר | שימוש | תיאור |
---|---|---|
from |
חובה, מחרוזת | הפרמטר הזה מציין מי שלח את ההודעה. הערך הוא אסימון הרישום של אפליקציית הלקוח. |
category |
חובה, מחרוזת | הפרמטר הזה מציין את שם החבילה של האפליקציה של אפליקציית הלקוח ששלחה את ההודעה. |
message_id |
שדה חובה, מחרוזת | הפרמטר הזה מציין את המזהה הייחודי של ההודעה. |
data |
אופציונלי, מחרוזת | הפרמטר הזה מציין את צמדי המפתח-ערך של מטען הייעודי של ההודעה. |
שליחה של הודעת ACK
הטבלה הבאה מתארת את תגובת ה-ACK שאליה שרת האפליקציות צפוי לשלוח FCM בתגובה ל הודעת upstream ששרת האפליקציה קיבל.
פרמטר | שימוש | תיאור |
---|---|---|
to |
חובה, מחרוזת | הפרמטר הזה מציין את הנמען של הודעת התשובה. הערך צריך להיות טוקן רישום של אפליקציית הלקוח ששלחה את ההודעה ב-upstream. |
message_id |
חובה, מחרוזת | הפרמטר הזה מציין לאיזו הודעה התשובה מיועדת. הערך חייב להיות הערך של message_id מההודעה המתאימה ב-upstream. |
message_type |
חובה, מחרוזת | הפרמטר הזה מציין הודעת ack משרת אפליקציות ל-CCS.
בהודעות מ-upstream, הערך צריך להיות תמיד ack . |
FCM הודעות שרת (XMPP)
זו הודעה שנשלחה מ-FCM לשרת אפליקציות. אלה הסוגים העיקריים של הודעות שFCM שולח לשרת האפליקציות:
- קבוצת בקרה: ההודעות האלה שנוצרו על ידי CCS מציינות נדרשת פעולה משרת האפליקציות.
בטבלה הבאה מתוארים השדות שכלולים בהודעות ש-CCS שולח לשרת האפליקציה.
פרמטר | שימוש | תיאור |
---|---|---|
שדה משותף | ||
message_type |
שדה חובה, מחרוזת | הפרמטר הזה מציין את סוג ההודעה: בקרה. כשהערך הוא |
control_type |
אופציונלי, מחרוזת | הפרמטר הזה מציין את סוג הודעת הבקרה שנשלחת מ-FCM. כרגע יש תמיכה רק ב- |