מסמך זה מספק הפניה לתחביר XMPP המשמש להעברת הודעות בין שרת האפליקציות, אפליקציות הלקוח ו-Firebase Cloud Messaging (FCM). שרת האפליקציות שלך חייב להתחבר לנקודות הקצה הבאות:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
הפרמטרים והאפשרויות הזמינים מתחלקים לקטגוריות הבאות:
- תחביר הודעות במורד הזרם
- קודי תגובה של שגיאה בהודעה במורד הזרם
- תחביר הודעות במעלה הזרם
- הודעות בקרת FCM
תחביר הודעות במורד הזרם
סעיף זה נותן את התחביר לשליחת הודעות במורד הזרם.
הודעות XMPP במורד זרם (JSON)
הטבלה הבאה מפרטת את היעדים, האפשרויות והמטען עבור הודעות XMPP JSON.
פָּרָמֶטֶר | נוֹהָג | תיאור | |
---|---|---|---|
יַעַד | |||
to | אופציונלי, מחרוזת | פרמטר זה מציין את הנמען של הודעה. הערך יכול להיות אסימון רישום של מכשיר, מפתח הודעות של קבוצת מכשירים, או נושא בודד (עם קידומת | |
condition | אופציונלי, מחרוזת | פרמטר זה מציין ביטוי לוגי של תנאים הקובע את יעד ההודעה. תנאי נתמך: נושא, מעוצב כ"הנושא שלך" בנושאים. ערך זה אינו תלוי רישיות. אופרטורים נתמכים: | |
אפשרויות | |||
message_id | חובה, מחרוזת | פרמטר זה מזהה באופן ייחודי הודעה בחיבור XMPP. | |
collapse_key | אופציונלי, מחרוזת | פרמטר זה מזהה קבוצת הודעות (למשל, עם אין ערובה לסדר שליחת ההודעות. הערה: מותר לכל היותר 4 מפתחות כיווץ שונים בכל זמן נתון. המשמעות היא ש-FCM יכולה לאחסן בו זמנית 4 הודעות שונות לכל אפליקציית לקוח. אם תחרוג ממספר זה, אין ערובה אילו 4 מפתחות כיווץ FCM ישמור. | |
priority | אופציונלי, מחרוזת | קובע את העדיפות של ההודעה. ערכים חוקיים הם "רגיל" ו"גבוה". בפלטפורמות של אפל, אלה תואמים את סדר העדיפויות של APN 5 ו-10. כברירת מחדל, הודעות התראה נשלחות בעדיפות גבוהה, והודעות נתונים נשלחות בעדיפות רגילה. עדיפות רגילה מייעלת את צריכת הסוללה של אפליקציית הלקוח ויש להשתמש בה אלא אם נדרשת אספקה מיידית. עבור הודעות עם עדיפות רגילה, האפליקציה עשויה לקבל את ההודעה באיחור לא מוגדר. כאשר הודעה נשלחת בעדיפות גבוהה, היא נשלחת מיד, והאפליקציה יכולה להציג התראה. | |
content_available | אופציונלי, בוליאני | בפלטפורמות של Apple, השתמש בשדה זה כדי לייצג | |
mutable_content | אופציונלי, JSON בוליאני | בפלטפורמות של Apple, השתמש בשדה זה כדי לייצג | |
time_to_live | אופציונלי, מספר | פרמטר זה מציין כמה זמן (בשניות) ההודעה צריכה להישמר באחסון FCM אם המכשיר לא מקוון. הזמן המקסימלי לחיות בתמיכה הוא 4 שבועות, וערך ברירת המחדל הוא 4 שבועות. למידע נוסף, ראה הגדרת תוחלת החיים של הודעה . | |
dry_run | אופציונלי, בוליאני | פרמטר זה, כאשר הוא מוגדר כ- ערך ברירת המחדל הוא | |
מטען | |||
data | אופציונלי, חפץ | פרמטר זה מציין את צמדי המפתח-ערך של מטען ההודעה. לדוגמה, עם בפלטפורמות של Apple, אם ההודעה נמסרת על ידי APNs, היא מייצגת את שדות הנתונים המותאמים אישית. אם הוא מועבר על ידי FCM, הוא מיוצג כמילון ערך מפתח ב-Android, זה גורם המפתח לא צריך להיות מילה שמורה ("from", "message_type", או כל מילה שמתחילה ב-"google" או "gcm"). אל תשתמש באף אחת מהמילים המוגדרות בטבלה זו (כגון ערכים בסוגי מחרוזת מומלצים. עליך להמיר ערכים באובייקטים או בסוגי נתונים אחרים שאינם מחרוזים (למשל, מספרים שלמים או בוליאנים) למחרוזת. | |
notification | אופציונלי, חפץ | פרמטר זה מציין את צמדי המפתח-ערך המוגדרים מראש, גלויים למשתמש, של מטען ההודעות. ראה תמיכת מטען הודעות לפרטים. למידע נוסף על אפשרויות הודעות הודעה והודעות נתונים, ראה סוגי הודעות . אם מסופק מטען הודעה, או שהאפשרות content_available מוגדרת כ- true עבור הודעה למכשיר Apple, ההודעה נשלחת דרך APNs , אחרת היא נשלחת דרך FCM. |
תמיכה במטען הודעות
הטבלאות הבאות מפרטות את המפתחות המוגדרים מראש הזמינים לבניית הודעות התראות עבור פלטפורמות אפל ואנדרואיד.
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
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. |
לפרש תגובת הודעת XMPP במורד הזרם
הטבלה הבאה מפרטת את השדות המופיעים בתגובת הודעת XMPP במורד הזרם.
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
from | חובה, מחרוזת | פרמטר זה מציין מי שלח את התגובה הזו. הערך הוא אסימון הרישום של אפליקציית הלקוח. |
message_id | חובה, מחרוזת | פרמטר זה מזהה באופן ייחודי הודעה בחיבור XMPP. הערך הוא מחרוזת המזהה באופן ייחודי את ההודעה המשויכת. |
message_type | חובה, מחרוזת | פרמטר זה מציין הודעת אם הערך מוגדר ל- |
error | אופציונלי, מחרוזת | פרמטר זה מציין שגיאה הקשורה להודעה במורד הזרם. הוא מוגדר כאשר message_type הוא nack . ראה טבלה 4 לפרטים. |
error_description | אופציונלי, מחרוזת | פרמטר זה מספק מידע תיאורי עבור השגיאה. הוא מוגדר כאשר message_type הוא nack . |
קודי תגובה של שגיאה בהודעה במורד הזרם
הטבלה הבאה מפרטת את קודי התגובה לשגיאה עבור הודעות במורד הזרם.
שְׁגִיאָה | קוד XMPP | פעולה מומלצת |
---|---|---|
חסר אסימון רישום | INVALID_JSON | בדוק שהבקשה מכילה אסימון רישום (ב- registration_id בהודעת טקסט רגילה, או בשדה to או registration_ids ב-JSON). |
רישום APN לא חוקי | INVALID_JSON | עבור רישומי iOS, בדוק שבקשת הרישום מהלקוח מכילה אסימון APNs ומזהה אפליקציה חוקיים. |
אסימון רישום לא חוקי | BAD_REGISTRATION | בדוק את הפורמט של אסימון הרישום שאתה מעביר לשרת. ודא שהוא תואם את אסימון הרישום שאפליקציית הלקוח מקבלת מההרשמה ל-FCM. אין לקטוע או להוסיף תווים נוספים. |
מכשיר לא רשום | DEVICE_UNREGISTERED | אסימון רישום קיים עשוי להפסיק להיות תקף במספר תרחישים, כולל:
|
השולח לא תואם | SENDER_ID_MISMATCH | אסימון רישום קשור לקבוצה מסוימת של שולחים. כאשר אפליקציית לקוח נרשמה ל-FCM, עליה לציין אילו שולחים מורשים לשלוח הודעות. עליך להשתמש באחד מאותם מזהי שולח בעת שליחת הודעות לאפליקציית הלקוח. אם תעבור לשולח אחר, אסימוני הרישום הקיימים לא יפעלו. |
JSON לא חוקי | INVALID_JSON | בדוק שהודעת ה-JSON מעוצבת כהלכה ומכילה שדות חוקיים (לדוגמה, וודא שסוג הנתונים הנכון מועבר). |
הודעה גדולה מדי | INVALID_JSON | בדוק שהגודל הכולל של נתוני המטען הכלולים בהודעה אינו חורג ממגבלות FCM: 4096 בתים עבור רוב ההודעות או 2048 בתים במקרה של הודעות לנושאים. זה כולל גם את המפתחות וגם את הערכים. |
מפתח נתונים לא חוקי | INVALID_JSON | ודא שנתוני המטען אינם מכילים מפתח (כגון from , gcm או כל ערך עם קידומת google ) שנמצא בשימוש פנימי על ידי FCM. שים לב שמילים מסוימות (כגון collapse_key ) נמצאות בשימוש גם על ידי FCM אך מותרות במטען, ובמקרה זה ערך המטען מוחלף על ידי ערך FCM. |
זמן לא חוקי לחיות | 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 | נכשל האימות עם שירותי דחיפה חיצוניים. בדוק אם אתה משתמש בתעודות הדחיפה הנכונות באינטרנט. |
תחביר הודעות במעלה הזרם
הודעה במעלה הזרם היא הודעה שאפליקציית הלקוח שולחת לשרת האפליקציה. נכון לעכשיו רק XMPP תומך בהעברת הודעות במעלה הזרם. עיין בתיעוד של הפלטפורמה שלך למידע נוסף על שליחת הודעות מאפליקציות לקוח.
פירוש הודעת XMPP במעלה הזרם
הטבלה הבאה מתארת את השדות ב-XMPP שיוצר על ידי FCM בתגובה לבקשות הודעות במעלה הזרם מיישומי לקוח.
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
from | חובה, מחרוזת | פרמטר זה מציין מי שלח את ההודעה. הערך הוא אסימון הרישום של אפליקציית הלקוח. |
category | חובה, מחרוזת | פרמטר זה מציין את שם חבילת האפליקציה של אפליקציית הלקוח ששלחה את ההודעה. |
message_id | חובה, מחרוזת | פרמטר זה מציין את המזהה הייחודי של ההודעה. |
data | אופציונלי, מחרוזת | פרמטר זה מציין את צמדי המפתח-ערך של מטען ההודעה. |
שולח הודעת ACK
הטבלה הבאה מתארת את תגובת ה-ACK ששרת האפליקציה צפוי לשלוח ל- FCM בתגובה להודעה במעלה הזרם ששרת האפליקציה קיבל.
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
to | חובה, מחרוזת | פרמטר זה מציין את הנמען של הודעת תגובה. הערך חייב להיות אסימון רישום של אפליקציית הלקוח ששלחה את ההודעה במעלה הזרם. |
message_id | חובה, מחרוזת | פרמטר זה מציין לאיזו הודעה מיועדת התגובה. הערך חייב להיות הערך message_id מההודעה המתאימה. |
message_type | חובה, מחרוזת | פרמטר זה מציין הודעת ack משרת אפליקציה ל-CCS. עבור הודעות במעלה הזרם, זה תמיד צריך להיות מוגדר כ- ack . |
הודעות שרת FCM (XMPP)
זוהי הודעה שנשלחה מ-FCM לשרת אפליקציות. להלן סוגי ההודעות העיקריים ש-FCM שולחת לשרת האפליקציות:
- בקרה: הודעות אלה שנוצרו ב-CCS מצביעות על כך שנדרשת פעולה משרת האפליקציה.
הטבלה הבאה מתארת את השדות הכלולים בהודעות ש-CCS שולחת לשרת אפליקציות.
פָּרָמֶטֶר | נוֹהָג | תיאור |
---|---|---|
תחום משותף | ||
message_type | חובה, מחרוזת | פרמטר זה מציין את סוג ההודעה: control. כאשר הוא מוגדר ל- |
control_type | אופציונלי, מחרוזת | פרמטר זה מציין את סוג הודעת הבקרה שנשלחה מ-FCM. נכון לעכשיו, רק |