Firebase Cloud Messaging (FCM) מציע מגוון רחב של אפשרויות ויכולות העברת הודעות. המידע בדף זה נועד לעזור לך להבין את הסוגים השונים של הודעות FCM ומה אתה יכול לעשות איתם.
סוגי הודעות
עם FCM, אתה יכול לשלוח שני סוגים של הודעות ללקוחות:
- הודעות התראה, לפעמים נחשבות כ"הודעות תצוגה". אלה מטופלים על ידי FCM SDK באופן אוטומטי.
- הודעות נתונים, המטופלות על ידי אפליקציית הלקוח.
הודעות התראה מכילות קבוצה מוגדרת מראש של מפתחות גלויים למשתמש. הודעות נתונים, לעומת זאת, מכילות רק צמדי מפתח-ערך מותאמים אישית המוגדרים על ידי המשתמש. הודעות התראה יכולות להכיל מטען נתונים אופציונלי. עומס מקסימלי עבור שני סוגי ההודעות הוא 4000 בתים, למעט שליחת הודעות ממסוף Firebase, אשר אוכפת מגבלה של 1024 תווים.
השתמש בתרחיש | איך לשלוח | |
---|---|---|
הודעת התראה | FCM SDK מציג את ההודעה למכשירי משתמש קצה בשם אפליקציית הלקוח כאשר היא פועלת ברקע. אחרת, אם האפליקציה פועלת בחזית כאשר ההודעה מתקבלת, הקוד של האפליקציה קובע את ההתנהגות. להודעות התראה יש קבוצה מוגדרת מראש של מפתחות גלויים למשתמש ומטען נתונים אופציונלי של צמדי מפתח-ערך מותאמים אישית. |
|
הודעת נתונים | אפליקציית הלקוח אחראית לעיבוד הודעות נתונים. להודעות נתונים יש רק צמדי מפתח-ערך מותאמים אישית ללא שמות מפתח שמורים (ראה להלן). | בסביבה מהימנה כגון Cloud Functions או שרת האפליקציות שלך, השתמש ב- Admin SDK או בפרוטוקולי שרת FCM : הגדר את מפתח data בלבד. |
השתמש בהודעות התראה כאשר אתה רוצה ש-FCM SDK יטפל בהצגת התראה באופן אוטומטי כאשר האפליקציה שלך פועלת ברקע. השתמש בהודעות נתונים כאשר אתה רוצה לעבד את ההודעות עם קוד אפליקציית הלקוח שלך.
FCM יכול לשלוח הודעת התראה כולל מטען נתונים אופציונלי. במקרים כאלה, FCM מטפל בהצגת מטען ההודעות, ואפליקציית הלקוח מטפלת במטען הנתונים.
הודעות התראה
לבדיקה או לצורך שיווק ומעורבות מחדש של משתמשים, תוכל לשלוח הודעות התראה באמצעות מסוף Firebase . קונסולת Firebase מספקת בדיקות A/B מבוססות ניתוח כדי לעזור לך לחדד ולשפר מסרים שיווקיים.
כדי לשלוח הודעות התראה באופן פרוגרמטי באמצעות ה-Admin SDK או פרוטוקולי ה-FCM, הגדר את מפתח notification
עם הסט המוגדר מראש של אפשרויות מפתח-ערך עבור החלק הגלוי למשתמש של הודעת ההתראה. לדוגמה, הנה הודעת התראה בפורמט JSON באפליקציית IM. המשתמש יכול לצפות לראות הודעה עם הכותרת "פורטוגל נגד דנמרק" והטקסט "משחק נהדר!" על המכשיר:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "notification":{ "title":"Portugal vs. Denmark", "body":"great match!" } } }
הודעות התראות נשלחות למגש ההתראות כאשר האפליקציה ברקע. עבור אפליקציות בחזית, הודעות מטופלות על ידי פונקציית התקשרות חוזרת.
עיין בתיעוד ההפניה לרשימה המלאה של מפתחות מוגדרים מראש הזמינים לבניית הודעות התראות:
הודעות נתונים
הגדר את המפתח המתאים עם צמדי המפתח-ערך המותאמים אישית שלך כדי לשלוח מטען נתונים לאפליקציית הלקוח.
לדוגמה, הנה הודעה בפורמט JSON באותה אפליקציית IM כמו לעיל, כאשר המידע מוקף במפתח data
המשותף ואפליקציית הלקוח צפויה לפרש את התוכן:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "data":{ "Nick" : "Mario", "body" : "great match!", "Room" : "PortugalVSDenmark" } } }
הדוגמה שלמעלה מציגה את השימוש בשדה data
ברמה העליונה, או בשדה הנפוץ, שמתפרש על ידי לקוחות בכל הפלטפורמות שמקבלות את ההודעה. בכל פלטפורמה, אפליקציית הלקוח מקבלת את מטען הנתונים בפונקציית התקשרות חוזרת.
הצפנה עבור הודעות נתונים
שכבת ה-Android Transport Layer (ראה ארכיטקטורת FCM ) משתמשת בהצפנה מנקודה לנקודה. בהתאם לצרכים שלך, ייתכן שתחליט להוסיף הצפנה מקצה לקצה להודעות נתונים. FCM אינו מספק פתרון מקצה לקצה. עם זאת, ישנם פתרונות חיצוניים זמינים כגון Capillary או DTLS .
הודעות התראה עם מטען נתונים אופציונלי
הן באופן תכנותי או דרך מסוף Firebase, אתה יכול לשלוח הודעות התראה המכילות מטען אופציונלי של צמדי מפתח-ערך מותאמים אישית. ב- Notifications composer , השתמש בשדות הנתונים המותאמים אישית באפשרויות מתקדמות .
התנהגות האפליקציה בעת קבלת הודעות הכוללות גם הודעות וגם עומסי נתונים תלויה בשאלה אם האפליקציה נמצאת ברקע או בחזית - בעצם, אם היא פעילה או לא בזמן הקבלה.
- כאשר ברקע , אפליקציות מקבלות את מטען ההתראות במגש ההתראות, ומטפלות במטען הנתונים רק כאשר המשתמש מקיש על ההתראה.
- כאשר בחזית , האפליקציה שלך מקבלת אובייקט הודעה עם שני המטענים הזמינים.
הנה הודעה בפורמט JSON המכילה גם את מפתח notification
וגם את מפתח data
:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "notification":{ "title":"Portugal vs. Denmark", "body":"great match!" }, "data" : { "Nick" : "Mario", "Room" : "PortugalVSDenmark" } } }
התאמה אישית של מסר בין פלטפורמות
Firebase Admin SDK ופרוטוקול HTTP v1 FCM מאפשרים לבקשות ההודעה שלך להגדיר את כל השדות הזמינים באובייקט message
. זה כולל:
- קבוצה משותפת של שדות שיתפרשו על ידי כל מופעי האפליקציה שמקבלים את ההודעה.
- קבוצות שדות ספציפיות לפלטפורמה, כגון
AndroidConfig
ו-WebpushConfig
, המתפרשות רק על ידי מופעי אפליקציה הפועלים בפלטפורמה שצוינה.
בלוקים ספציפיים לפלטפורמה מעניקים לך גמישות להתאמה אישית של הודעות לפלטפורמות שונות כדי להבטיח שהן מטופלות כראוי בעת קבלתן. ה-backend של FCM ייקח בחשבון את כל הפרמטרים שצוינו ויתאים אישית את ההודעה לכל פלטפורמה.
מתי להשתמש בשדות נפוצים
השתמש בשדות נפוצים כאשר אתה:
- מיקוד למופעי אפליקציות בכל הפלטפורמות - אפל, אנדרואיד ואינטרנט
- שליחת הודעות לנושאים
כל מופעי האפליקציה, ללא קשר לפלטפורמה, יכולים לפרש את השדות הנפוצים הבאים:
מתי להשתמש בשדות ספציפיים לפלטפורמה
השתמש בשדות ספציפיים לפלטפורמה כאשר אתה רוצה:
- שלח שדות רק לפלטפורמות מסוימות
- שלח שדות ספציפיים לפלטפורמה בנוסף לשדות הנפוצים
בכל פעם שאתה רוצה לשלוח ערכים רק לפלטפורמות מסוימות, אל תשתמש בשדות נפוצים; להשתמש בשדות ספציפיים לפלטפורמה. לדוגמה, כדי לשלוח הודעה רק לפלטפורמות ולאינטרנט של אפל אך לא לאנדרואיד, עליך להשתמש בשתי קבוצות נפרדות של שדות, אחת לאפל ואחת לאינטרנט.
כאשר אתה שולח הודעות עם אפשרויות מסירה ספציפיות, השתמש בשדות ספציפיים לפלטפורמה כדי להגדיר אותן. אתה יכול לציין ערכים שונים לכל פלטפורמה אם תרצה. עם זאת, גם כאשר אתה רוצה להגדיר בעצם אותו ערך על פני פלטפורמות, עליך להשתמש בשדות ספציפיים לפלטפורמה. הסיבה לכך היא שכל פלטפורמה עשויה לפרש את הערך בצורה מעט שונה - לדוגמה, זמן חיים מוגדר באנדרואיד כזמן תפוגה בשניות, בעוד שב-Apple הוא מוגדר כתאריך תפוגה.
דוגמה: הודעת הודעה עם אפשרויות משלוח ספציפיות לפלטפורמה
בקשת השליחה v1 הבאה שולחת כותרת הודעה ותוכן משותפים לכל הפלטפורמות, אך גם שולחת כמה עקיפות ספציפיות לפלטפורמה. ספציפית, הבקשה:
- מגדיר זמן חיים ארוך עבור פלטפורמות אנדרואיד ואינטרנט, תוך הגדרת עדיפות הודעות APNs (פלטפורמות אפל) להגדרה נמוכה
- מגדיר את המקשים המתאימים כדי להגדיר את התוצאה של הקשה על המשתמש על ההתראה באנדרואיד ובאפל -
click_action
category
, בהתאמה.
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "notification":{ "title":"Match update", "body":"Arsenal goal in added time, score is now 3-0" }, "android":{ "ttl":"86400s", "notification"{ "click_action":"OPEN_ACTIVITY_1" } }, "apns": { "headers": { "apns-priority": "5", }, "payload": { "aps": { "category": "NEW_MESSAGE_CATEGORY" } } }, "webpush":{ "headers":{ "TTL":"86400" } } } }
עיין בתיעוד ההפניה של HTTP v1 לקבלת פרטים מלאים על המפתחות הזמינים בלוקים ספציפיים לפלטפורמה בגוף ההודעה. למידע נוסף על בניית בקשות שליחה המכילות את גוף ההודעה, ראה בניית בקשות שליחה .
אפשרויות משלוח
FCM מספקת סט ספציפי של אפשרויות מסירה להודעות הנשלחות למכשירי אנדרואיד, ומאפשרת אפשרויות דומות בפלטפורמות ובאינטרנט של אפל. לדוגמה, התנהגות הודעה "ניתנת לקיפול" נתמכת באנדרואיד דרך collapse_key
של FCM, באפל דרך apns-collapse-id
וב-JavaScript/אינטרנט דרך Topic
. לפרטים, עיין בתיאורים בסעיף זה ובתיעוד עזר קשור.
הודעות בלתי מתקפלות ומתקפלות
הודעה בלתי מתקפלת מציינת שכל הודעה בודדת נמסרת למכשיר. הודעה שאינה ניתנת לקיפול מספקת תוכן שימושי כלשהו, בניגוד להודעה ניתנת לקיפול כמו "פינג" ללא תוכן לאפליקציה לנייד כדי ליצור קשר עם השרת כדי להביא נתונים.
כמה מקרי שימוש טיפוסיים של הודעות בלתי מתקפלות הן הודעות צ'אט או הודעות קריטיות. לדוגמה, באפליקציית IM, תרצה להעביר כל הודעה, מכיוון שלכל הודעה יש תוכן שונה.
לאנדרואיד יש מגבלה של 100 הודעות שניתן לאחסן מבלי להתמוטט. אם מגיעים למגבלה, כל ההודעות המאוחסנות נמחקות. כשהמכשיר חוזר למצב מקוון, הוא מקבל הודעה מיוחדת המציינת שהגבלה הושגה. לאחר מכן, האפליקציה יכולה להתמודד עם המצב כראוי, בדרך כלל על ידי בקשת סנכרון מלא משרת האפליקציה.
הודעה מתקפלת היא הודעה שעשויה להיות מוחלפת בהודעה חדשה אם היא עדיין לא נמסרה למכשיר.
מקרי שימוש נפוץ של הודעות מתקפלות הן הודעות המשמשות כדי לומר לאפליקציה לנייד לסנכרן נתונים מהשרת. דוגמה לכך תהיה אפליקציית ספורט שמעדכנת את המשתמשים עם הניקוד האחרון. רק ההודעה האחרונה רלוונטית.
כדי לסמן הודעה כניתנת לקיפול באנדרואיד, כלול את הפרמטר collapse_key
במטען ההודעה. כברירת מחדל, מפתח הכיווץ הוא שם חבילת האפליקציה הרשום במסוף Firebase. שרת FCM יכול לאחסן בו-זמנית ארבע הודעות שונות הניתנות לקיפול לכל מכשיר, כל אחת עם מפתח כיווץ שונה. אם תחרוג ממספר זה, FCM שומר רק ארבעה מפתחות כיווץ, ללא הבטחות לגבי אילו מהם נשמרים.
הודעות נושא ללא מטען ניתנות לכיווץ כברירת מחדל. הודעות ההתראה תמיד ניתנות לכיווץ ויתעלמו מהפרמטר collapse_key
.
באיזה עליי להשתמש?
הודעות מתקפלות הן בחירה טובה יותר מנקודת מבט של ביצועים, בתנאי שהאפליקציה שלך לא צריכה להשתמש בהודעות לא מתקפלות. עם זאת, אם אתה משתמש בהודעות הניתנות לכיווץ, זכור ש-FCM מאפשר להשתמש רק בארבעה מפתחות כיווץ שונים על ידי FCM לכל אסימון רישום בכל זמן נתון. אסור לחרוג ממספר זה, אחרת זה עלול לגרום לתוצאות בלתי צפויות.
השתמש בתרחיש | איך לשלוח | |
---|---|---|
בלתי מתקפל | כל הודעה חשובה לאפליקציית הלקוח וצריכה להימסר. | פרט להודעות התראה, כל ההודעות אינן ניתנות לכיבוי כברירת מחדל. |
מִתקַפֵּל | כאשר יש הודעה חדשה יותר שהופך הודעה ישנה וקשורה ללא רלוונטית לאפליקציית הלקוח, FCM מחליף את ההודעה הישנה יותר. לדוגמה: הודעות המשמשות להפעלת סנכרון נתונים מהשרת, או הודעות הודעות מיושנות. | הגדר את הפרמטר המתאים בבקשת ההודעה שלך:
|
הגדרת העדיפות של הודעה
יש לך שתי אפשרויות להקצאת עדיפות מסירה להודעות במורד הזרם: רגילה ובעדיפות גבוהה. למרות שההתנהגות שונה במקצת בין הפלטפורמות, מסירת הודעות רגילות ובעדיפות גבוהה עובדת כך:
עדיפות רגילה. הודעות עדיפות רגילות נמסרות מיד כאשר האפליקציה נמצאת בחזית. עבור אפליקציות ברקע, המסירה עשויה להתעכב. עבור הודעות פחות רגישות לזמן, כגון התראות על אימייל חדש, שמירת ממשק המשתמש שלך מסונכרן או סנכרון נתוני אפליקציה ברקע, בחר בעדיפות מסירה רגילה.
עדיפות גבוהה. FCM מנסה להעביר הודעות בעדיפות גבוהה באופן מיידי גם אם המכשיר נמצא במצב Doze. הודעות בעדיפות גבוהה מיועדות לתוכן רגיש לזמן, גלוי למשתמש.
הנה דוגמה להודעת עדיפות רגילה שנשלחה באמצעות פרוטוקול FCM HTTP v1 כדי להודיע למנוי מגזין שתוכן חדש זמין להורדה:
{ "message":{ "topic":"subscriber-updates", "notification":{ "body" : "This week's edition is now available.", "title" : "NewsMagazine.com", }, "data" : { "volume" : "3.21.15", "contents" : "http://www.news-magazine.com/world-week/21659772" }, "android":{ "priority":"normal" }, "apns":{ "headers":{ "apns-priority":"5" } }, "webpush": { "headers": { "Urgency": "high" } } } }
לפרטים נוספים ספציפיים לפלטפורמה על הגדרת עדיפות הודעה:
קביעת תוחלת החיים של הודעה
FCM בדרך כלל מספקת הודעות מיד לאחר שליחתן. עם זאת, ייתכן שזה לא תמיד אפשרי. לדוגמה, אם הפלטפורמה היא אנדרואיד, המכשיר יכול להיות כבוי, במצב לא מקוון או לא זמין בדרך אחרת. לחלופין, FCM עשוי לעכב הודעות בכוונה כדי למנוע מאפליקציה לצרוך משאבים מוגזמים ולהשפיע לרעה על חיי הסוללה.
כאשר זה קורה, FCM מאחסן את ההודעה ומעביר אותה ברגע שזה אפשרי. למרות שזה בסדר ברוב המקרים, יש כמה אפליקציות שעבורן הודעה מאוחרת עלולה אף פעם לא להימסר. לדוגמה, אם ההודעה היא שיחה נכנסת או הודעת וידאו צ'אט, יש לה משמעות רק לפרק זמן קצר לפני סיום השיחה. או אם ההודעה היא הזמנה לאירוע, היא חסרת תועלת אם היא מתקבלת לאחר שהאירוע הסתיים.
ב-Android וב-Web/JavaScript, אתה יכול לציין את תוחלת החיים המקסימלית של הודעה. הערך חייב להיות משך בין 0 ל-2,419,200 שניות (28 ימים), והוא מתאים לפרק הזמן המרבי שעבורו FCM מאחסן ומנסה להעביר את ההודעה. בקשות שאינן מכילות שדה זה כברירת מחדל לתקופה המקסימלית של ארבעה שבועות.
להלן כמה שימושים אפשריים לתכונה זו:
- וידאו צ'אט שיחות נכנסות
- אירועי הזמנה שפג תוקפם
- אירועי לוח שנה
יתרון נוסף של ציון תוחלת החיים של הודעה הוא ש-FCM אף פעם לא מצערת הודעות עם ערך זמן חיים של 0 שניות. במילים אחרות, FCM מבטיחה את המאמץ הטוב ביותר עבור הודעות שיש להעביר "עכשיו או לעולם לא". זכור שערך time_to_live
של 0 פירושו שההודעות שלא ניתן להעביר מיד נמחקות. עם זאת, מכיוון שהודעות כאלה לעולם אינן מאוחסנות, זה מספק את זמן האחזור הטוב ביותר לשליחת הודעות התראה.
הנה דוגמה לבקשה הכוללת TTL:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "data":{ "Nick" : "Mario", "body" : "great match!", "Room" : "PortugalVSDenmark" }, "apns":{ "headers":{ "apns-expiration":"1604750400" } }, "android":{ "ttl":"4500s" }, "webpush":{ "headers":{ "TTL":"4500" } } } }
חיי הודעה
כאשר שרת אפליקציה מפרסם הודעה ל-FCM ומקבל חזרה מזהה הודעה, אין זה אומר שההודעה כבר נמסרה למכשיר. אלא, זה אומר שהוא התקבל למשלוח. מה שקורה להודעה לאחר קבלתה תלוי בגורמים רבים.
בתרחיש הטוב ביותר, אם המכשיר מחובר ל-FCM, המסך דולק ואין הגבלות מצערת, ההודעה נמסרת מיד.
אם המכשיר מחובר אך ב-Doze, הודעה בעדיפות נמוכה מאוחסנת על ידי FCM עד שהמכשיר יוצא מ-Doze. וכאן דגל ה- collapse_key
משחק תפקיד: אם כבר יש הודעה עם אותו מפתח כיווץ (ואסימון רישום) מאוחסנת ומחכה למשלוח, ההודעה הישנה נמחקת וההודעה החדשה תופסת את מקומה (כלומר, הישנה ההודעה מכווצת על ידי ההודעה החדשה). עם זאת, אם מפתח הכיווץ אינו מוגדר, הן ההודעות החדשות והן ההודעות הישנות מאוחסנות למסירה עתידית.
אם המכשיר אינו מחובר ל-FCM, ההודעה נשמרת עד ליצירת חיבור (שוב תוך שמירה על כללי מפתח הכיווץ). כאשר נוצר חיבור, FCM מספק את כל ההודעות הממתינות למכשיר. אם ההתקן לעולם לא יתחבר שוב (לדוגמה, אם הוא אופס להגדרות היצרן), ההודעה בסופו של דבר הופסקה והיא נמחקת מאחסון FCM. פסק הזמן המוגדר כברירת מחדל הוא ארבעה שבועות, אלא אם הוגדר דגל time_to_live
.
כדי לקבל יותר תובנות לגבי מסירת הודעה:
כדי לקבל תובנות נוספות לגבי מסירת הודעות בפלטפורמות אנדרואיד או אפל, ראה את לוח המחוונים לדיווח של FCM , המתעד את מספר ההודעות שנשלחו ונפתחו במכשירי אפל ואנדרואיד, יחד עם נתונים עבור "הופעות" (התראות שנראו על ידי משתמשים) עבור אפליקציות אנדרואיד.
עבור מכשירי אנדרואיד עם הודעות ערוץ ישיר מופעלות, אם המכשיר לא התחבר ל-FCM במשך יותר מחודש, FCM עדיין מקבל את ההודעה אך משליך אותה מיד. אם המכשיר מתחבר תוך ארבעה שבועות מהודעת הנתונים האחרונה ששלחת אליו, הלקוח שלך יקבל את ההתקשרות חזרה onDeletedMessages() . לאחר מכן, האפליקציה יכולה להתמודד עם המצב כראוי, בדרך כלל על ידי בקשת סנכרון מלא משרת האפליקציה.
לבסוף, כאשר FCM מנסה להעביר הודעה למכשיר והאפליקציה הוסרה, FCM משליך את ההודעה הזו מיד ומבטל את תוקף אסימון הרישום. ניסיונות עתידיים לשלוח הודעה למכשיר זה מביאים לשגיאה NotRegistered
.
מצערת ושינוי קנה מידה
המטרה שלנו היא להעביר תמיד כל הודעה שנשלחת דרך FCM. עם זאת, העברת כל הודעה גורמת לפעמים לחוויית משתמש כללית גרועה. במקרים אחרים, עלינו לספק גבולות כדי להבטיח ש-FCM מספקת שירות שניתן להרחבה עבור כל השולחים.
מניעת הודעה מתקפלת
כפי שתואר לעיל, הודעות מתקפלות הן התראות ללא תוכן שנועדו להתמוטט זו על גבי זו. במקרה שמפתח חוזר על אותה הודעה לאפליקציה לעתים קרובות מדי, אנו מעכבים (מצערים) הודעות כדי להפחית את ההשפעה על הסוללה של המשתמש.
לדוגמה, אם תשלח מספר גדול של בקשות סנכרון דוא"ל חדשות למכשיר בודד, אנו עשויים לדחות את בקשת הסנכרון הבאה של הדוא"ל בכמה דקות כדי שהמכשיר יוכל להסתנכרן בקצב ממוצע נמוך יותר. מצערת זו נעשית אך ורק כדי להגביל את השפעת הסוללה שחווה המשתמש.
אם מקרה השימוש שלך דורש דפוסי שליחת פרצים גבוהים, ייתכן שהודעות בלתי מתקפלות הן הבחירה הנכונה. עבור הודעות כאלה, הקפד לכלול את התוכן בהודעות כאלה על מנת להוזיל את עלות הסוללה.
אנו מגבילים הודעות מתקפלות לפרץ של 20 הודעות לאפליקציה לכל מכשיר, עם מילוי מחדש של הודעה אחת כל 3 דקות.
מצערת שרת XMPP
אנו מגבילים את קצב החיבור לשרתי FCM XMPP ל-400 חיבורים לדקה לפרויקט. זה לא אמור להיות בעיה במשלוח הודעות, אבל זה חשוב כדי להבטיח את היציבות של המערכת שלנו.
עבור כל פרויקט, FCM מאפשר 2500 חיבורים במקביל.
שיעור הודעות מקסימלי למכשיר בודד
עבור אנדרואיד, ניתן לשלוח עד 240 הודעות לדקה ו-5,000 הודעות לשעה למכשיר בודד. סף גבוה זה נועד לאפשר פרצי תנועה לטווח קצר, כגון כאשר משתמשים מקיימים אינטראקציה מהירה בצ'אט. מגבלה זו מונעת משגיאות בשליחת ההיגיון לרוקן בטעות את הסוללה במכשיר.
עבור iOS, אנו מחזירים שגיאה כאשר הקצב חורג ממגבלות APNs.
מגבלת הודעות במעלה הזרם
אנו מגבילים הודעות במעלה הזרם ב-1,500,000 לדקה לפרויקט כדי למנוע עומס יתר על שרתי היעד במעלה הזרם.
אנו מגבילים הודעות במעלה הזרם למכשיר ב-1,000 לדקה כדי להגן מפני ריקון הסוללה מהתנהגות אפליקציה רעה.
הגבלת הודעות בנושא
שיעור ההוספה/הסרה של מנויי נושא מוגבל ל-3,000 QPS לפרויקט.
לשיעורי שליחת הודעות, ראה Fanout Throttling .
מצערת מנאוט
איבוד הודעות הוא תהליך של שליחת הודעה למכשירים מרובים, כגון כאשר אתה ממקד לנושאים וקבוצות, או כאשר אתה משתמש במלחין ההודעות כדי למקד לקהלים או לפלחי משתמשים.
העברת הודעות איננה מיידית ולכן מדי פעם יש לך מספר אוהדים מתנהלים במקביל. אנו מגבילים את מספר אוהדי ההודעות במקביל לכל פרויקט ל-1,000. לאחר מכן, אנו עשויים לדחות בקשות נוספות של מעריצים או לדחות את הפצת הבקשות עד שיסתיימו חלק מהמעריצים שכבר מתנהלים.
שיעור הפנאאוטים שניתן להשיג בפועל מושפע ממספר הפרויקטים המבקשים מעריצים בו זמנית. שיעור אוהדים של 10,000 QPS עבור פרויקט בודד אינו נדיר, אך מספר זה אינו ערובה והוא תוצאה של העומס הכולל על המערכת. חשוב לציין כי קיבולת ה-fanout הזמינה מחולקת בין הפרויקטים ולא על פני בקשות ה-fanout. לכן, אם לפרויקט שלך יש שני אוהדים בתהליך, אז כל אוהד יראה רק מחצית משיעור האוהדים הזמין. הדרך המומלצת למקסם את מהירות ה-Fanout שלך היא לקיים מופע פעיל אחד בלבד בכל פעם.
יציאות FCM וחומת האש שלך
אם לארגון שלך יש חומת אש להגבלת תעבורה לאינטרנט או ממנו, עליך להגדיר אותה כך שתאפשר למכשירים ניידים להתחבר ל-FCM כדי שמכשירים ברשת שלך יקבלו הודעות. FCM משתמש בדרך כלל ביציאה 5228, אך לפעמים היא משתמשת ב-443, 5229 ו-5230.
עבור התקנים שמתחברים לרשת שלך, FCM לא מספקת כתובות IP ספציפיות מכיוון שטווח ה-IP שלנו משתנה בתדירות גבוהה מדי וכללי חומת האש שלך עלולים להתיישן ולהשפיע על חוויית המשתמשים שלך. באופן אידיאלי, רשימת ההיתרים מוציאה את 5228-5230 ו-443 ללא הגבלות IP. עם זאת, אם חייבת להיות לך הגבלת IP, עליך לרשום את כל כתובות ה-IP הרשומות ב- goog.json . רשימה גדולה זו מתעדכנת באופן שוטף, ומומלץ לעדכן את הכללים שלך על בסיס חודשי. בעיות הנגרמות על ידי הגבלות IP של חומת אש הן לעתים קרובות לסירוגין וקשות לאבחון.
אנו מציעים קבוצה של שמות מתחם שניתן לרשום ברשימה הרשמית במקום כתובות IP. שמות מארחים אלה מפורטים להלן. אם נתחיל להשתמש בשמות מארחים נוספים, נעדכן את הרשימה כאן. השימוש בשמות דומיין עבור כלל חומת האש שלך עשוי להיות פונקציונלי במכשיר חומת האש שלך.
יציאות TCP לפתיחה:
- 5228
- 5229
- 5230
- 443
שמות מארחים לפתיחה:
- mtalk.google.com
- mtalk4.google.com
- mtalk-staging.google.com
- mtalk-dev.google.com
- alt1-mtalk.google.com
- alt2-mtalk.google.com
- alt3-mtalk.google.com
- alt4-mtalk.google.com
- alt5-mtalk.google.com
- alt6-mtalk.google.com
- alt7-mtalk.google.com
- alt8-mtalk.google.com
- android.apis.google.com
- device-provisioning.googleapis.com
- firebaseinstallations.googleapis.com
חומות אש של תרגום כתובות רשת ו/או בדיקת מנות מדינה:
אם הרשת שלך מיישמת Network Address Translation (NAT) או Stateful Packet Inspection (SPI), הטמע פסק זמן של 30 דקות או יותר עבור החיבורים שלנו דרך יציאות 5228-5230. זה מאפשר לנו לספק קישוריות אמינה תוך הפחתת צריכת הסוללה של המכשירים הניידים של המשתמשים שלך.
אישורים
בהתאם לתכונות ה-FCM שאתה מיישם, ייתכן שתצטרך את האישורים הבאים מפרויקט Firebase שלך:
מזהה פרויקט | מזהה ייחודי לפרויקט Firebase שלך, המשמש בבקשות לנקודת הקצה FCM v1 HTTP. ערך זה זמין בחלונית ההגדרות של מסוף Firebase . |
אסימון רישום | מחרוזת אסימון ייחודית המזהה כל מופע אפליקציה של לקוח. אסימון הרישום נדרש להעברת הודעות של מכשיר יחיד וקבוצת מכשירים. שימו לב שאסימוני רישום חייבים להישמר בסוד. |
מספר זהות השולח | ערך מספרי ייחודי שנוצר בעת יצירת פרויקט Firebase שלך, זמין בכרטיסייה Cloud Messaging בחלונית ההגדרות של מסוף Firebase. מזהה השולח משמש לזיהוי כל שולח שיכול לשלוח הודעות לאפליקציית הלקוח. |
אסימון גישה | אסימון OAuth 2.0 קצר מועד שמאשר בקשות ל-API של HTTP v1. האסימון הזה משויך לחשבון שירות ששייך לפרויקט Firebase שלך. כדי ליצור ולסובב אסימוני גישה, בצע את השלבים המתוארים באישור שליחת בקשות . |
מפתח שרת (עבור פרוטוקולים מדור קודם) | מפתח שרת שמאשר לשרת האפליקציה שלך גישה לשירותי Google, כולל שליחת הודעות באמצעות פרוטוקולי Firebase Cloud Messaging מדור קודם. אתה מקבל את מפתח השרת בעת יצירת פרויקט Firebase שלך. אתה יכול להציג אותו בכרטיסייה Cloud Messaging בחלונית ההגדרות של מסוף Firebase. חשוב: אל תכלול את מפתח השרת בשום מקום בקוד הלקוח שלך. כמו כן, הקפד להשתמש רק במפתחות שרת כדי לאשר את שרת האפליקציה שלך. מפתחות אנדרואיד, פלטפורמת אפל ומפתחות הדפדפן נדחים על ידי FCM. |
Firebase Cloud Messaging (FCM) מציע מגוון רחב של אפשרויות ויכולות העברת הודעות. המידע בדף זה נועד לעזור לך להבין את הסוגים השונים של הודעות FCM ומה אתה יכול לעשות איתם.
סוגי הודעות
עם FCM, אתה יכול לשלוח שני סוגים של הודעות ללקוחות:
- הודעות התראה, לפעמים נחשבות כ"הודעות תצוגה". אלה מטופלים על ידי FCM SDK באופן אוטומטי.
- הודעות נתונים, המטופלות על ידי אפליקציית הלקוח.
הודעות התראה מכילות קבוצה מוגדרת מראש של מפתחות גלויים למשתמש. הודעות נתונים, לעומת זאת, מכילות רק צמדי מפתח-ערך מותאמים אישית המוגדרים על ידי המשתמש. הודעות התראה יכולות להכיל מטען נתונים אופציונלי. עומס מקסימלי עבור שני סוגי ההודעות הוא 4000 בתים, למעט שליחת הודעות ממסוף Firebase, אשר אוכפת מגבלה של 1024 תווים.
השתמש בתרחיש | איך לשלוח | |
---|---|---|
הודעת התראה | FCM SDK מציג את ההודעה למכשירי משתמש קצה בשם אפליקציית הלקוח כאשר היא פועלת ברקע. אחרת, אם האפליקציה פועלת בחזית כאשר ההודעה מתקבלת, הקוד של האפליקציה קובע את ההתנהגות. להודעות התראה יש קבוצה מוגדרת מראש של מפתחות גלויים למשתמש ומטען נתונים אופציונלי של צמדי מפתח-ערך מותאמים אישית. |
|
הודעת נתונים | אפליקציית הלקוח אחראית לעיבוד הודעות נתונים. להודעות נתונים יש רק צמדי מפתח-ערך מותאמים אישית ללא שמות מפתח שמורים (ראה להלן). | בסביבה מהימנה כגון Cloud Functions או שרת האפליקציות שלך, השתמש ב- Admin SDK או בפרוטוקולי שרת FCM : הגדר את מפתח data בלבד. |
השתמש בהודעות התראה כאשר אתה רוצה ש-FCM SDK יטפל בהצגת התראה באופן אוטומטי כאשר האפליקציה שלך פועלת ברקע. השתמש בהודעות נתונים כאשר אתה רוצה לעבד את ההודעות עם קוד אפליקציית הלקוח שלך.
FCM יכול לשלוח הודעת התראה כולל מטען נתונים אופציונלי. במקרים כאלה, FCM מטפל בהצגת מטען ההודעות, ואפליקציית הלקוח מטפלת במטען הנתונים.
הודעות התראה
לבדיקה או לצורך שיווק ומעורבות מחדש של משתמשים, תוכל לשלוח הודעות התראה באמצעות מסוף Firebase . קונסולת Firebase מספקת בדיקות A/B מבוססות ניתוח כדי לעזור לך לחדד ולשפר מסרים שיווקיים.
כדי לשלוח הודעות התראה באופן פרוגרמטי באמצעות ה-Admin SDK או פרוטוקולי ה-FCM, הגדר את מפתח notification
עם הסט המוגדר מראש של אפשרויות מפתח-ערך עבור החלק הגלוי למשתמש של הודעת ההתראה. לדוגמה, הנה הודעת התראה בפורמט JSON באפליקציית IM. המשתמש יכול לצפות לראות הודעה עם הכותרת "פורטוגל נגד דנמרק" והטקסט "משחק נהדר!" על המכשיר:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "notification":{ "title":"Portugal vs. Denmark", "body":"great match!" } } }
הודעות התראות נשלחות למגש ההתראות כאשר האפליקציה ברקע. עבור אפליקציות בחזית, הודעות מטופלות על ידי פונקציית התקשרות חוזרת.
עיין בתיעוד ההפניה לרשימה המלאה של מפתחות מוגדרים מראש הזמינים לבניית הודעות התראות:
הודעות נתונים
הגדר את המפתח המתאים עם צמדי המפתח-ערך המותאמים אישית שלך כדי לשלוח מטען נתונים לאפליקציית הלקוח.
לדוגמה, הנה הודעה בפורמט JSON באותה אפליקציית IM כמו לעיל, כאשר המידע מוקף במפתח data
המשותף ואפליקציית הלקוח צפויה לפרש את התוכן:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "data":{ "Nick" : "Mario", "body" : "great match!", "Room" : "PortugalVSDenmark" } } }
הדוגמה שלמעלה מציגה את השימוש בשדה data
ברמה העליונה, או בשדה הנפוץ, שמתפרש על ידי לקוחות בכל הפלטפורמות שמקבלות את ההודעה. בכל פלטפורמה, אפליקציית הלקוח מקבלת את מטען הנתונים בפונקציית התקשרות חוזרת.
הצפנה עבור הודעות נתונים
שכבת ה-Android Transport Layer (ראה ארכיטקטורת FCM ) משתמשת בהצפנה מנקודה לנקודה. בהתאם לצרכים שלך, ייתכן שתחליט להוסיף הצפנה מקצה לקצה להודעות נתונים. FCM אינו מספק פתרון מקצה לקצה. עם זאת, ישנם פתרונות חיצוניים זמינים כגון Capillary או DTLS .
הודעות התראה עם מטען נתונים אופציונלי
הן באופן תכנותי או דרך מסוף Firebase, אתה יכול לשלוח הודעות התראה המכילות מטען אופציונלי של צמדי מפתח-ערך מותאמים אישית. ב- Notifications composer , השתמש בשדות הנתונים המותאמים אישית באפשרויות מתקדמות .
התנהגות האפליקציה בעת קבלת הודעות הכוללות גם הודעות וגם עומסי נתונים תלויה בשאלה אם האפליקציה נמצאת ברקע או בחזית - בעצם, אם היא פעילה או לא בזמן הקבלה.
- כאשר ברקע , אפליקציות מקבלות את מטען ההתראות במגש ההתראות, ומטפלות במטען הנתונים רק כאשר המשתמש מקיש על ההתראה.
- כאשר בחזית , האפליקציה שלך מקבלת אובייקט הודעה עם שני המטענים הזמינים.
הנה הודעה בפורמט JSON המכילה גם את מפתח notification
וגם את מפתח data
:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "notification":{ "title":"Portugal vs. Denmark", "body":"great match!" }, "data" : { "Nick" : "Mario", "Room" : "PortugalVSDenmark" } } }
התאמה אישית של מסר בין פלטפורמות
Firebase Admin SDK ופרוטוקול HTTP v1 FCM מאפשרים לבקשות ההודעה שלך להגדיר את כל השדות הזמינים באובייקט message
. זה כולל:
- קבוצה משותפת של שדות שיתפרשו על ידי כל מופעי האפליקציה שמקבלים את ההודעה.
- קבוצות שדות ספציפיות לפלטפורמה, כגון
AndroidConfig
ו-WebpushConfig
, המתפרשות רק על ידי מופעי אפליקציה הפועלים בפלטפורמה שצוינה.
בלוקים ספציפיים לפלטפורמה מעניקים לך גמישות להתאמה אישית של הודעות לפלטפורמות שונות כדי להבטיח שהן מטופלות כראוי בעת קבלתן. ה-backend של FCM ייקח בחשבון את כל הפרמטרים שצוינו ויתאים אישית את ההודעה לכל פלטפורמה.
מתי להשתמש בשדות נפוצים
השתמש בשדות נפוצים כאשר אתה:
- מיקוד למופעי אפליקציות בכל הפלטפורמות - אפל, אנדרואיד ואינטרנט
- שליחת הודעות לנושאים
כל מופעי האפליקציה, ללא קשר לפלטפורמה, יכולים לפרש את השדות הנפוצים הבאים:
מתי להשתמש בשדות ספציפיים לפלטפורמה
השתמש בשדות ספציפיים לפלטפורמה כאשר אתה רוצה:
- שלח שדות רק לפלטפורמות מסוימות
- שלח שדות ספציפיים לפלטפורמה בנוסף לשדות הנפוצים
בכל פעם שאתה רוצה לשלוח ערכים רק לפלטפורמות מסוימות, אל תשתמש בשדות נפוצים; להשתמש בשדות ספציפיים לפלטפורמה. לדוגמה, כדי לשלוח הודעה רק לפלטפורמות ולאינטרנט של אפל אך לא לאנדרואיד, עליך להשתמש בשתי קבוצות נפרדות של שדות, אחת לאפל ואחת לאינטרנט.
כאשר אתה שולח הודעות עם אפשרויות מסירה ספציפיות, השתמש בשדות ספציפיים לפלטפורמה כדי להגדיר אותן. אתה יכול לציין ערכים שונים לכל פלטפורמה אם תרצה. עם זאת, גם כאשר אתה רוצה להגדיר בעצם אותו ערך על פני פלטפורמות, עליך להשתמש בשדות ספציפיים לפלטפורמה. הסיבה לכך היא שכל פלטפורמה עשויה לפרש את הערך בצורה מעט שונה - לדוגמה, זמן חיים מוגדר באנדרואיד כזמן תפוגה בשניות, בעוד שב-Apple הוא מוגדר כתאריך תפוגה.
Example: notification message with platform-specific delivery options
The following v1 send request sends a common notification title and content to all platforms, but also sends some platform-specific overrides. Specifically, the request:
- sets a long time-to-live for Android and Web platforms, while setting the APNs (Apple platforms) message priority to a low setting
- sets the appropriate keys to define the result of a user tap on the notification on Android and Apple —
click_action
, andcategory
, respectively.
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "notification":{ "title":"Match update", "body":"Arsenal goal in added time, score is now 3-0" }, "android":{ "ttl":"86400s", "notification"{ "click_action":"OPEN_ACTIVITY_1" } }, "apns": { "headers": { "apns-priority": "5", }, "payload": { "aps": { "category": "NEW_MESSAGE_CATEGORY" } } }, "webpush":{ "headers":{ "TTL":"86400" } } } }
See the HTTP v1 reference documentation for complete detail on the keys available in platform-specific blocks in the message body. For more information about building send requests that contain the message body, see Build Send Requests .
Delivery options
FCM provides a specific set of delivery options for messages sent to Android devices, and allows for similar options on Apple platforms and web. For example, "collapsible" message behavior is supported on Android via FCM's collapse_key
, on Apple via apns-collapse-id
, and on JavaScript/Web via Topic
. For details, see descriptions in this section and related reference documentation.
Non-collapsible and collapsible messages
A non-collapsible message denotes that each individual message is delivered to the device. A non-collapsible message delivers some useful content, as opposed to a collapsible message like a content-free "ping" to the mobile app to contact the server to fetch data.
Some typical use cases of non-collapsible messages are chat messages or critical messages. For example, in an IM app, you would want to deliver every message, because every message has different content.
For Android there is a limit of 100 messages that can be stored without collapsing. If the limit is reached, all stored messages are discarded. When the device is back online, it receives a special message indicating that the limit was reached. The app can then handle the situation properly, typically by requesting a full sync from the app server.
A collapsible message is a message that may be replaced by a new message if it has yet to be delivered to the device.
A common use cases of collapsible messages are messages used to tell a mobile app to sync data from the server. An example would be a sports app that updates users with the latest score. Only the most recent message is relevant.
To mark a message as collapsible on Android, include the collapse_key
parameter in the message payload. By default, the collapse key is the app package name registered in the Firebase console. The FCM server can simultaneously store four different collapsible messages per device, each with a different collapse key. If you exceed this number, FCM only keeps four collapse keys, with no guarantees about which ones are kept.
Topic messages with no payload are collapsible by default. Notification messages are always collapsible and will ignore the collapse_key
parameter.
Which should I use?
Collapsible messages are a better choice from a performance standpoint, provided your app doesn't need to use non-collapsible messages. However, if you use collapsible messages, remember that FCM only allows a maximum of four different collapse keys to be used by FCM per registration token at any given time. You must not exceed this number, or it could cause unpredictable consequences.
Use scenario | How to send | |
---|---|---|
Non-collapsible | Every message is important to the client app and needs to be delivered. | Except for notification messages, all messages are non-collapsible by default. |
Collapsible | When there is a newer message that renders an older, related message irrelevant to the client app, FCM replaces the older message. For example: messages used to initiate a data sync from the server, or outdated notification messages. | Set the appropriate parameter in your message request:
|
Setting the priority of a message
You have two options for assigning delivery priority to downstream messages: normal and high priority. Though the behavior differs slightly across platforms, delivery of normal and high priority messages works like this:
Normal priority. Normal priority messages are delivered immediately when the app is in the foreground. For backgrounded apps, delivery may be delayed. For less time-sensitive messages, such as notifications of new email, keeping your UI in sync, or syncing app data in the background, choose normal delivery priority.
High priority. FCM attempts to deliver high priority messages immediately even if the device is in Doze mode. High priority messages are for time-sensitive, user visible content.
Here is an example of a normal priority message sent via the FCM HTTP v1 protocol to notify a magazine subscriber that new content is available to download:
{ "message":{ "topic":"subscriber-updates", "notification":{ "body" : "This week's edition is now available.", "title" : "NewsMagazine.com", }, "data" : { "volume" : "3.21.15", "contents" : "http://www.news-magazine.com/world-week/21659772" }, "android":{ "priority":"normal" }, "apns":{ "headers":{ "apns-priority":"5" } }, "webpush": { "headers": { "Urgency": "high" } } } }
For more platform-specific detail on setting message priority:
Setting the lifespan of a message
FCM usually delivers messages immediately after they are sent. However, this might not always be possible. For example, if the platform is Android, the device could be turned off, offline, or otherwise unavailable. Or FCM might intentionally delay messages to prevent an app from consuming excessive resources and negatively affecting battery life.
When this happens, FCM stores the message and delivers it as soon as it's feasible. While this is fine in most cases, there are some apps for which a late message might as well never be delivered. For example, if the message is an incoming call or video chat notification, it is meaningful only for a short period of time before the call is terminated. Or if the message is an invitation to an event, it is useless if received after the event has ended.
On Android and Web/JavaScript, you can specify the maximum lifespan of a message. The value must be a duration from 0 to 2,419,200 seconds (28 days), and it corresponds to the maximum period of time for which FCM stores and attempts to deliver the message. Requests that don't contain this field default to the maximum period of four weeks.
Here are some possible uses for this feature:
- Video chat incoming calls
- Expiring invitation events
- Calendar events
Another advantage of specifying the lifespan of a message is that FCM never throttles messages with a time-to-live value of 0 seconds. In other words, FCM guarantees best effort for messages that must be delivered "now or never." Keep in mind that a time_to_live
value of 0 means messages that can't be delivered immediately are discarded. However, because such messages are never stored, this provides the best latency for sending notification messages.
Here is an example of a request that includes TTL:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "data":{ "Nick" : "Mario", "body" : "great match!", "Room" : "PortugalVSDenmark" }, "apns":{ "headers":{ "apns-expiration":"1604750400" } }, "android":{ "ttl":"4500s" }, "webpush":{ "headers":{ "TTL":"4500" } } } }
Lifetime of a message
When an app server posts a message to FCM and receives a message ID back, it does not mean that the message was already delivered to the device. Rather, it means that it was accepted for delivery. What happens to the message after it is accepted depends on many factors.
In the best-case scenario, if the device is connected to FCM, the screen is on and there are no throttling restrictions, the message is delivered right away.
If the device is connected but in Doze, a low priority message is stored by FCM until the device is out of Doze. And that's where the collapse_key
flag plays a role: if there is already a message with the same collapse key (and registration token) stored and waiting for delivery, the old message is discarded and the new message takes its place (that is, the old message is collapsed by the new one). However, if the collapse key is not set, both the new and old messages are stored for future delivery.
If the device is not connected to FCM, the message is stored until a connection is established (again respecting the collapse key rules). When a connection is established, FCM delivers all pending messages to the device. If the device never gets connected again (for instance, if it was factory reset), the message eventually times out and is discarded from FCM storage. The default timeout is four weeks, unless the time_to_live
flag is set.
To get more insight into the delivery of a message:
To get more insight into the delivery of messages on Android or Apple platforms, see the FCM reporting dashboard , which records the number of messages sent and opened on Apple and Android devices, along with data for "impressions" (notifications seen by users) for Android apps.
For Android devices with direct channel messaging enabled, if the device has not connected to FCM for more than one month, FCM still accepts the message but immediately discards it. If the device connects within four weeks of the last data message you sent to it, your client receives the onDeletedMessages() callback. The app can then handle the situation properly, typically by requesting a full sync from the app server.
Finally, when FCM attempts to deliver a message to the device and the app was uninstalled, FCM discards that message right away and invalidates the registration token. Future attempts to send a message to that device results in a NotRegistered
error.
Throttling and scaling
Our goal is to always deliver every message sent via FCM. However, delivering every message sometimes results in a poor overall user experience. In other cases, we need to provide boundaries to ensure that FCM provides a scalable service for all senders.
Collapsible message throttling
As described above, collapsible messages are content-free notifications designed to collapse on top of each other. In the event that a developer is repeating the same message to an app too frequently, we delay (throttle) messages to reduce the impact on a user's battery.
For example, if you send large numbers of new email sync requests to a single device, we might delay the next email sync request a few minutes so that the device can sync at a lower average rate. This throttling is done strictly to limit the battery impact experienced by the user.
If your use case requires high burst send patterns, then non-collapsible messages may be the right choice. For such messages, make sure to include the content in such messages in order to reduce the battery cost.
We limit collapsible messages to a burst of 20 messages per app per device, with a refill of 1 message every 3 minutes.
XMPP server throttling
We limit the rate that you can connect to FCM XMPP servers to 400 connections per minute per project. This shouldn't be an issue for message delivery, but it is important for ensuring the stability of our system.
For each project, FCM allows 2500 connections in parallel.
Maximum message rate to a single device
For Android, you can send up to 240 messages/minute and 5,000 messages/hour to a single device. This high threshold is meant to allow for short term bursts of traffic, such as when users are interacting rapidly over chat. This limit prevents errors in sending logic from inadvertently draining the battery on a device.
For iOS, we return an error when the rate exceeds APNs limits.
Upstream message limit
We limit upstream messages at 1,500,000/minute per project to avoid overloading upstream destination servers.
We limit upstream messages per device at 1,000/minute to protect against battery drain from bad app behavior.
Topic message limit
The topic subscription add/remove rate is limited to 3,000 QPS per project.
For message sending rates, see Fanout Throttling .
Fanout throttling
Message fanout is the process of sending a message to multiple devices, such as when you target topics and groups, or when you use the Notifications composer to target audiences or user segments.
Message fanout is not instantaneous and so occasionally you have multiple fanouts in progress concurrently. We limit the number of concurrent message fanouts per project to 1,000. After that, we may reject additional fanout requests or defer the fanout of the requests until some of the already in progress fanouts complete.
The actual achievable fanout rate is influenced by the number of projects requesting fanouts at the same time. A fanout rate of 10,000 QPS for an individual project is not uncommon, but that number is not a guarantee and is a result of the total load on the system. It is important to note that the available fanout capacity is divided among projects and not across fanout requests. So, if your project has two fanouts in progress, then each fanout will only see half of the available fanout rate. The recommended way to maximize your fanout speed is to only have one active fanout in progress at a time.
FCM ports and your firewall
If your organization has a firewall to restrict traffic to or from the Internet, you need to configure it to allow mobile devices to connect with FCM in order for devices on your network to receive messages. FCM typically uses port 5228, but it sometimes uses 443, 5229, and 5230.
For devices connecting on your network, FCM doesn't provide specific IPs because our IP range changes too frequently and your firewall rules could get out of date, impacting your users' experience. Ideally, allowlist ports 5228-5230 & 443 with no IP restrictions. However, if you must have an IP restriction, you should allowlist all of the IP addresses listed in goog.json . This large list is updated regularly, and you are recommended to update your rules on a monthly basis. Problems caused by firewall IP restrictions are often intermittent and difficult to diagnose.
We do offer a set of domain names that can be allowlisted instead of IP addresses. Those hostnames are listed below. If we start using additional hostnames, we will update the list here. Using domain names for your firewall rule may or may not be functional in your firewall device.
TCP ports to open:
- 5228
- 5229
- 5230
- 443
Hostnames to open:
- mtalk.google.com
- mtalk4.google.com
- mtalk-staging.google.com
- mtalk-dev.google.com
- alt1-mtalk.google.com
- alt2-mtalk.google.com
- alt3-mtalk.google.com
- alt4-mtalk.google.com
- alt5-mtalk.google.com
- alt6-mtalk.google.com
- alt7-mtalk.google.com
- alt8-mtalk.google.com
- android.apis.google.com
- device-provisioning.googleapis.com
- firebaseinstallations.googleapis.com
Network Address Translation and/or Stateful Packet Inspection firewalls:
If your network implements Network Address Translation (NAT) or Stateful Packet Inspection (SPI), implement a 30 minute or larger timeout for our connections over ports 5228-5230. This enables us to provide reliable connectivity while reducing the battery consumption of your users' mobile devices.
Credentials
Depending on which FCM features you implement, you may need the following credentials from your Firebase project:
Project ID | A unique identifier for your Firebase project, used in requests to the FCM v1 HTTP endpoint. This value is available in the Firebase console Settings pane. |
Registration token | A unique token string that identifies each client app instance. The registration token is required for single device and device group messaging. Note that registration tokens must be kept secret. |
Sender ID | A unique numerical value created when you create your Firebase project, available in the Cloud Messaging tab of the Firebase console Settings pane. The sender ID is used to identify each sender that can send messages to the client app. |
Access token | A short-lived OAuth 2.0 token that authorizes requests to the HTTP v1 API. This token is associated with a service account that belongs to your Firebase project. To create and rotate access tokens, follow the steps described in Authorize Send Requests . |
Server key (for legacy protocols) | A server key that authorizes your app server for access to Google services, including sending messages via the Firebase Cloud Messaging legacy protocols. You obtain the server key when you create your Firebase project. You can view it in the Cloud Messaging tab of the Firebase console Settings pane. Important: Do not include the server key anywhere in your client code. Also, make sure to use only server keys to authorize your app server. Android, Apple platform, and browser keys are rejected by FCM. |