מידע על הודעות FCM

Firebase Cloud Messaging (FCM) מציע מגוון רחב של אפשרויות ויכולות שליחת הודעות. המידע בדף הזה נועד לעזור לכם להבין את הסוגים השונים של הודעות FCM ואת הפעולות שאפשר לבצע איתן.

סוגי הודעות

באמצעות FCM, אפשר לשלוח ללקוחות שני סוגים של הודעות:

• הודעות התראה, שנקראות לפעמים 'הודעות תצוגה'. ערכת ה-SDK של FCM מטפלת בהן באופן אוטומטי.
• הודעות נתונים, שמטופלות על ידי אפליקציית הלקוח.

הודעות התראות מכילות קבוצה מוגדרת מראש של מפתחות שגלויים למשתמשים. לעומת זאת, הודעות נתונים מכילות רק את זוגות המפתח-ערך בהתאמה אישית שהוגדרו על ידי המשתמש. הודעות התראה יכולות להכיל מטען נתונים אופציונלי. עומס העבודה המקסימלי בשני סוגי ההודעות הוא 4,096 בייטים, מלבד שליחת הודעות ממסוף Firebase, שבו מופעלת אכיפה של מגבלה של 1,000 תווים.

	תרחיש לדוגמה	איך שולחים
הודעת התראה	FCM SDK מציג את ההודעה במכשירים של משתמשי הקצה בשם אפליקציית הלקוח כשהיא פועלת ברקע. אחרת, אם האפליקציה פועלת בחזית כשמתקבלת ההתראה, הקוד של האפליקציה קובע את ההתנהגות. להודעות התראות יש קבוצה מוגדרת מראש של מפתחות שגלויים למשתמשים, ומטען נתונים אופציונלי של צמדי מפתח/ערך בהתאמה אישית.	בסביבה מהימנה כמו Cloud Functions או שרת האפליקציה, משתמשים ב-Admin SDK או ב-HTTP v1 API. מגדירים את המפתח notification. יכול להיות לו גם עומס נתונים אופציונלי. תמיד אפשר לכווץ אותם. כאן אפשר למצוא דוגמאות להצגת התראות ולשליחת עומסי עבודה של בקשות. להשתמש ב כלי ליצירת התראות: מזינים את טקסט ההודעה, הכותרת וכו' ושולחים. כדי להוסיף עומס נתונים אופציונלי, מספקים נתונים מותאמים אישית.
הודעת נתונים	אפליקציית הלקוח אחראית לעיבוד הודעות הנתונים. הודעות נתונים מכילות רק צמדי מפתח/ערך מותאמים אישית ללא שמות מפתחות שמורים (ראו בהמשך).	בסביבה מהימנה, כמו Cloud Functions או שרת האפליקציה, משתמשים ב-Admin SDK או בפרוטוקולים של שרת FCM. בבקשה לשליחה, מגדירים את המפתח data.

משתמשים בהודעות התראה כשרוצים ש-SDK של FCM יטפל בהצגת התראה באופן אוטומטי כשהאפליקציה פועלת ברקע. כדאי להשתמש בהודעות נתונים כשרוצים לעבד את ההודעות באמצעות הקוד של אפליקציית הלקוח שלכם.

FCM יכול לשלוח הודעת התראה שכוללת מטען נתונים אופציונלי. במקרים כאלה, FCM מטפלת בהצגת עומס העבודה של ההתראה, ואפליקציית הלקוח מטפלת בעומס העבודה של הנתונים.

הודעות התראה

לצורך בדיקה או לצורך שיווק ויצירת עניין מחדש בקרב משתמשים, אפשר לשלוח הודעות התראה באמצעות מסוף Firebase. במסוף Firebase יש בדיקות A/B שמבוססות על ניתוח נתונים, שיעזרו לכם לשפר את המסרים השיווקיים.

כדי לשלוח הודעות התראה באופן פרוגרמטי באמצעות Admin SDK או באמצעות הפרוטוקולים FCM, מגדירים את המפתח notification עם קבוצת האפשרויות המוגדרות מראש של מפתח/ערך הנדרשת לחלק של הודעת ההתראה שגלוי למשתמשים. לדוגמה, זוהי הודעת התראה בפורמט JSON באפליקציית צ'אט. המשתמש צפוי לראות במכשיר הודעה עם הכותרת 'פורטוגל נגד דנמרק' והטקסט 'משחק נהדר!':

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

הודעות התראה מועברות למגש ההתראות כשהאפליקציה פועלת ברקע. באפליקציות שבחזית, ההודעות מטופלות על ידי פונקציית קריאה חוזרת.

רשימת המפתחות המלאה שמוגדרים מראש ליצירת הודעות התראה מופיעה במסמכי העזרה של אובייקט התראות של פרוטוקול HTTP v1.

הודעות נתונים

מגדירים את המפתח המתאים עם צמדי המפתח/ערך בהתאמה אישית כדי לשלוח עומס נתונים לאפליקציית הלקוח.

חשוב לוודא שלא משתמשים במילים שמורות בצמדי המפתח/ערך המותאמים אישית. מילים שמורות כוללות את 'from',‏ 'notification',‏ 'message_type' או כל מילה שמתחילה ב-'google' או ב-'gcm'.

לדוגמה, הנה הודעה בפורמט JSON באותה אפליקציית צ'אט כמו למעלה, שבה המידע ארוז במפתח המשותף data ואפליקציית הלקוח אמורה לפרש את התוכן:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

בדוגמה שלמעלה מוצג שימוש בשדה data ברמה העליונה, או בשדה המשותף, שמתורגם על ידי לקוחות בכל הפלטפורמות שמקבלות את ההודעה. בכל פלטפורמה, אפליקציית הלקוח מקבלת את עומס הנתונים בקריאה חוזרת (callback).

הצפנה להודעות נתונים

בשכבת התעבורה של Android (ראו ארכיטקטורת FCM) נעשה שימוש בהצפנה מקצה לקצה. בהתאם לצרכים שלכם, תוכלו להחליט להוסיף הצפנה מקצה לקצה להודעות הנתונים. FCM לא מספק פתרון מקצה לקצה. עם זאת, יש פתרונות חיצוניים זמינים, כמו Capillary או DTLS.

הודעות התראה עם עומס נתונים אופציונלי

אפשר לשלוח הודעות התראה שמכילות עומס נתונים אופציונלי של צמדי מפתח/ערך בהתאמה אישית, גם באופן פרוגרמטי וגם דרך מסוף Firebase. ב כלי ליצירת התראות, משתמשים בשדות נתונים מותאמים אישית בקטע אפשרויות מתקדמות.

ההתנהגות של האפליקציה כשהיא מקבלת הודעות שכוללות גם עומסי נתונים וגם התראות תלויה בסטטוס שלה – אם היא פועלת ברקע או בחזית. בעיקרון, אם היא פעילה בזמן הקבלה או לא.

• כשהאפליקציות פועלות ברקע, הן מקבלות את עומס הנתונים של ההתראה במגש ההתראות, ומטפלות בו רק כשהמשתמש מקייש על ההתראה.
• כשהאפליקציה בחזית, היא מקבלת אובייקט הודעה עם שני עומסי הנתונים הזמינים.

זוהי הודעה בפורמט 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 של FCM v1 מאפשרים להגדיר את כל השדות הזמינים באובייקט message בבקשות להעברת הודעות. אפשר לצלם:

• קבוצה משותפת של שדות שכל המופעים של האפליקציה שמקבלים את ההודעה צריכים לפרש.
• קבוצות של שדות ספציפיות לפלטפורמה, כמו AndroidConfig ו-WebpushConfig, שמתפרשות רק על ידי מכונות של אפליקציות שפועלות בפלטפורמה שצוינה.

באמצעות חסימה ספציפית לפלטפורמה, תוכלו להתאים אישית הודעות לפלטפורמות שונות כדי לוודא שהן יטופלו כראוי כשהן יתקבלו. הקצה העורפי של FCM יביא בחשבון את כל הפרמטרים שצוינו ויתאים אישית את ההודעה לכל פלטפורמה.

מתי כדאי להשתמש בשדות נפוצים

כדאי להשתמש בשדות נפוצים במקרים הבאים:

• טירגוט למופעים של האפליקציה בכל הפלטפורמות – Apple,‏ Android והאינטרנט
• שליחת הודעות לנושאים

כל המופעים של האפליקציה, ללא קשר לפלטפורמה, יכולים לפרש את השדות הנפוצים הבאים:

• message.notification.title
• message.notification.body
• message.data

מתי כדאי להשתמש בשדות ספציפיים לפלטפורמה

כדאי להשתמש בשדות ספציפיים לפלטפורמה במקרים הבאים:

• שליחת שדות רק לפלטפורמות מסוימות
• שליחת שדות ספציפיים לפלטפורמה בנוסף לשדות הנפוצים

אם אתם רוצים לשלוח ערכים רק לפלטפורמות מסוימות, אל תשתמשו בשדות נפוצים, אלא בשדות ספציפיים לפלטפורמה. לדוגמה, כדי לשלוח התראה רק לפלטפורמות של Apple ולאינטרנט, אבל לא ל-Android, צריך להשתמש בשתי קבוצות נפרדות של שדות, אחת ל-Apple ואחת לאינטרנט.

כששולחים הודעות עם אפשרויות שליחה ספציפיות, צריך להשתמש בשדות ספציפיים לפלטפורמה כדי להגדיר אותן. אם רוצים, אפשר לציין ערכים שונים לכל פלטפורמה. עם זאת, גם אם רוצים להגדיר ערך זהה במהותו בפלטפורמות שונות, צריך להשתמש בשדות ספציפיים לפלטפורמה. הסיבה לכך היא שכל פלטפורמה יכולה לפרש את הערך בצורה שונה במקצת. לדוגמה, משך החיים מוגדר ב-Android כזמן תפוגה בשניות, ואילו ב-Apple הוא מוגדר כתאריך תפוגה.

דוגמה: הודעת התראה עם אפשרויות שליחה ספציפיות לפלטפורמה

בבקשת השליחה הבאה בגרסה 1, שם ההתראה והתוכן שלה נשלחים לכל הפלטפורמות, אבל נשלחים גם כמה שינויים ספציפיים לפלטפורמה. באופן ספציפי, הבקשה:

• מגדיר זמן חיים ארוך לפלטפורמות Android ו-Web, ומגדיר את העדיפות של ההודעות ב-APNs (פלטפורמות Apple) להגדרה נמוכה
• מגדיר את המפתחות המתאימים כדי להגדיר את התוצאה של הקשה של משתמש על ההתראה ב-Android וב-Apple – 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 מספק קבוצה ספציפית של אפשרויות העברה להודעות שנשלחות למכשירי Android, ומאפשר אפשרויות דומות בפלטפורמות של Apple ובאינטרנט. לדוגמה, התנהגות של הודעות 'ניתנות לכווץ' נתמכת ב-Android דרך collapse_key של FCM, ב-Apple דרך apns-collapse-id וב-JavaScript/Web דרך Topic. פרטים נוספים זמינים בתיאור שבקטע הזה ובמסמכי העזרה הרלוונטיים.

הודעות שלא ניתן לכווץ והודעות שניתן לכווץ

הודעה לא ניתנת לכווץ מציינת שכל הודעה נשלחת למכשיר בנפרד. הודעה שלא ניתן לכווץ מכילה תוכן שימושי, בניגוד להודעה שניתן לכווץ, כמו 'פינג' ללא תוכן לאפליקציה לנייד כדי ליצור קשר עם השרת ולשלוף נתונים.

FCM לא מבטיחה את סדר המסירה.

דוגמאות לשימוש בהודעות שלא ניתן לכווץ הן הודעות בצ'אט או הודעות קריטיות. לדוגמה, באפליקציית צ'אט, כדאי לשלוח כל הודעה כי לכל הודעה יש תוכן שונה.

ב-Android יש מגבלה של 100 הודעות שאפשר לאחסן בלי שהן יתכווצו. אם מגיעים למגבלה, כל ההודעות שנשמרו נמחקות. כשהמכשיר חוזר לאינטרנט, הוא מקבל הודעה מיוחדת על כך שהמגבלה הגיעה. לאחר מכן, האפליקציה יכולה לטפל במצב בצורה נכונה, בדרך כלל על ידי בקשה לסנכרון מלא משרת האפליקציה.

הודעה שניתן לכווץ היא הודעה שעשויה להיות מוחלפת בהודעה חדשה אם היא עדיין לא נמסרה למכשיר.

תרחיש לדוגמה נפוץ של הודעות שניתן לכווץ הוא הודעות שמשמשות להודעה לאפליקציה לנייד לסנכרן נתונים מהשרת. לדוגמה, אפליקציית ספורט שמעדכנת את המשתמשים בתוצאה האחרונה. רק ההודעה האחרונה רלוונטית.

כדי לסמן הודעה כהודעה שניתן לכווץ ב-Android, צריך לכלול את הפרמטר collapse_key בתוכן של ההודעה. כברירת מחדל, מפתח ההתכווצות הוא שם חבילת האפליקציה שרשום במסוף Firebase. השרת FCM יכול לאחסן בו-זמנית ארבע הודעות שונות שניתן לכווץ בכל מכשיר, לכל אחת מפתח כיווץ שונה. אם חורגים מהמספר הזה, FCM שומר רק ארבעה מפתחות כיווץ, ללא ערובה לגבי המפתחות שיישמרו.

הודעות בנושאים ללא מטען ייעודי (Payload) ניתנות לכווץ כברירת מחדל. הודעות התראה תמיד ניתנות לכיווץ, והמערכת תתעלם מהפרמטר collapse_key.

באיזו אפשרות כדאי להשתמש?

מבחינת ביצועים, עדיף להשתמש בהודעות שניתן לכווץ, בתנאי שאין צורך להשתמש בהודעות שלא ניתן לכווץ באפליקציה. עם זאת, אם אתם משתמשים בהודעות שניתן לכווץ, חשוב לזכור ש-FCM מאפשרת ל-FCM להשתמש רק בארבעה מפתחות כיווץ שונים לכל אסימון רישום בכל זמן נתון. אסור לחרוג מהמספר הזה, אחרת עלולות להיות לכך השלכות בלתי צפויות.

	תרחיש לדוגמה	איך שולחים
מודעה שלא ניתן לכווץ	כל הודעה חשובה לאפליקציית הלקוח וצריך להעביר אותה.	כברירת מחדל, אי אפשר לכווץ את כל ההודעות, מלבד הודעות התראה.
מודעה שניתן לכיווץ	כשיש הודעה חדשה שגורמת להודעה קשורה ישנה יותר להיות לא רלוונטית לאפליקציית הלקוח, FCM מחליף את ההודעה הישנה. לדוגמה: הודעות שמשמשות להתחלת סנכרון נתונים מהשרת, או הודעות התראה לא עדכניות.	מגדירים את הפרמטר המתאים בבקשה להודעה: collapseKey ב-Android apns-collapse-id ב-Apple Topic באינטרנט collapse_key בפרוטוקולים מדור קודם (כל הפלטפורמות)

הגדרת העדיפות של הודעה

יש שתי אפשרויות להקצאת עדיפות למשלוח של הודעות במורד הזרם: רגילה וגבוהה. ההתנהגות משתנה מעט בין הפלטפורמות, אבל כך מתבצעת שליחת הודעות עם עדיפות רגילה ותורנית:

• עדיפות רגילה הודעות בעדיפות רגילה נשלחות באופן מיידי כשהאפליקציה בחזית. באפליקציות שפועלות ברקע, יכול להיות עיכוב בהעברה. להודעות פחות דחופות, כמו התראות על אימיילים חדשים, שמירה על סנכרון של ממשק המשתמש או סנכרון נתוני האפליקציה ברקע, בוחרים בעדיפות שליחה רגילה.

• עדיפות גבוהה. FCM מנסה להעביר הודעות בעדיפות גבוהה באופן מיידי, גם אם המכשיר נמצא במצב שינה. הודעות בעדיפות גבוהה מיועדות לתוכן שזמין למשתמשים ותלוי זמן.

כששולחים הודעות נתונים למכשירי Apple, חובה להגדיר את רמת העדיפות ל-5, או לעדיפות רגילה. הודעות שנשלחות בעדיפות גבוהה נדחות על ידי הקצה העורפי של FCM עם השגיאה INVALID_ARGUMENT.

זוהי דוגמה להודעה ברמת עדיפות רגילה שנשלחת באמצעות פרוטוקול 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"
      }
    }
  }
}

פרטים נוספים על הגדרת עדיפות ההודעות בפלטפורמות שונות:

• מסמכי תיעוד של APNs
• הגדרה וניהול של עדיפות ההודעות (ב-Android)
• דרגת הדחיפות של הודעות דחיפה באינטרנט

תרחישי שימוש קריטיים

ממשקי ה-API של FCM לא מיועדים להתראות חירום או לפעילויות אחרות בסיכון גבוה שבהן השימוש בממשקי ה-API או תקלה בהם עלולים לגרום למוות, לפציעה או לנזק סביבתי (למשל, הפעלה של מתקנים גרעיניים, בקרת תנועה אווירית או מערכות תומכות חיים). כל שימוש כזה אסור במפורש בכפוף לסעיף 4. א. 7 של התנאים וההגבלות. באחריותך הבלעדית לנהל את התאימות של האפליקציה לתנאים, וכל נזק שנגרם כתוצאה מהאי-תאימות. Google מספקת את ממשקי ה-API "כפי שהם", ושומרת לעצמה את הזכות להפסיק את השימוש בממשקי ה-API, או בכל חלק או תכונה שלהם, או את הגישה שלך אליהם, מכל סיבה ובכל שלב, ללא חבות או התחייבות אחרת כלפיך או כלפי המשתמשים שלך.

הגדרת אורך החיים של הודעה

בדרך כלל, FCM מעביר הודעות מיד אחרי שהן נשלחות. עם זאת, יכול להיות שלא תמיד תהיה אפשרות לעשות זאת. לדוגמה, אם הפלטפורמה היא Android, יכול להיות שהמכשיר מושבת, לא מחובר לאינטרנט או לא זמין מסיבה אחרת. לחלופין, יכול להיות ש-FCM יעכב הודעות בכוונה כדי למנוע מאפליקציה לצרוך יותר מדי משאבים ולהשפיע לרעה על חיי הסוללה.

במקרה כזה, FCM מאחסן את ההודעה ומעביר אותה בהקדם האפשרי. ברוב המקרים זה בסדר, אבל יש אפליקציות שבהן הודעה מאוחרת לא תישלח בכלל. לדוגמה, אם ההודעה היא על שיחה נכנסת או על התראה לגבי שיחת וידאו, היא רלוונטית רק לזמן קצר לפני שהשיחה מסתיימת. למשל, אם ההודעה היא הזמנה לאירוע, היא לא תהיה שימושית אם תתקבל אחרי שהאירוע יסתיים.

ב-Android ובאינטרנט/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, המסך דלוק ואין הגבלות על צמצום הקצב, ההודעה נשלחת מיד.

אם המכשיר מחובר אבל נמצא במצב שינה, FCM שומר הודעה עם תעדוף נמוך עד שהמכשיר יוצא ממצב שינה. כאן נכנס לתמונה הדגל collapse_key: אם כבר יש הודעה עם אותו מפתח כיווץ (ואסימון רישום) שמאוחסנת וממתינה למשלוח, ההודעה הישנה תושלך וההודעה החדשה תיכנס במקומה (כלומר, ההודעה הישנה תכווצ על ידי ההודעה החדשה). עם זאת, אם מפתח ההתכווצות לא מוגדר, גם ההודעות החדשות וגם ההודעות הישנות מאוחסנות לצורך שליחה עתידית.

אם המכשיר לא מחובר ל-FCM, ההודעה מאוחסנת עד שנוצר חיבור (שוב, בהתאם לכללי מפתח התכווץ). כשהחיבור מתבצע, FCM מעביר את כל ההודעות בהמתנה למכשיר. אם המכשיר לא יתחבר שוב (למשל, אם הוא אופס להגדרות המקוריות), יפוג הזמן הקצוב להודעה והיא תימחק מהאחסון ב-FCM. זמן הקצוב לתפוגה שמוגדר כברירת מחדל הוא ארבעה שבועות, אלא אם מגדירים את הדגל time_to_live.

כדי לקבל תובנות נוספות לגבי העברת ההודעה:

כדי לקבל תובנות נוספות על שליחת ההודעות בפלטפורמות Android או Apple, אפשר לעיין ב לוח הבקרה של הדוחות FCM, שבו מתועד מספר ההודעות שנשלחו ונפתחו במכשירי Apple ובמכשירי Android, וגם נתונים של 'חשיפות' (התראות שמוצגות למשתמשים) באפליקציות ל-Android.

במכשירי Android שבהם התכונה 'הודעות ישירות לערוץ' מופעלת, אם המכשיר לא מחובר ל-FCM במשך יותר מחודש, המערכת ב-FCM עדיין תקבל את ההודעה אבל תמחק אותה מיד. אם המכשיר יתחבר תוך ארבעה שבועות ממועד שליחת הודעת הנתונים האחרונה, הלקוח יקבל את קריאת החזרה (callback) onDeletedMessages()‎. לאחר מכן, האפליקציה יכולה לטפל במצב בצורה נכונה, בדרך כלל על ידי בקשה לסנכרון מלא משרת האפליקציה.

לבסוף, כש-FCM מנסה להעביר הודעה למכשיר והאפליקציה הוסרה, FCM משליכה את ההודעה הזו מיד ומבטלת את תוקף אסימון הרישום. ניסיונות עתידיים לשלוח הודעה למכשיר הזה יגרמו לשגיאה NotRegistered.

ויסות נתונים (throttle) ומכסות

המטרה שלנו היא תמיד להעביר את כל ההודעות שנשלחות דרך FCM. עם זאת, לפעמים שליחת כל ההודעות גורמת לחוויית משתמש כוללת גרועה. במקרים אחרים, אנחנו צריכים להגדיר גבולות כדי להבטיח ש-FCM יספק שירות שניתן להתאמה לכל השולחים. סוגי המגבלות והמכסות שמפורטים בקטע הזה עוזרים לנו לאזן בין הגורמים החשובים האלה.

הערה: המגבלות שמפורטות בקטע הזה עשויות להשתנות.

הגבלת רוחב הפס של הודעות במורד הזרם

ב-HTTP v1 API הוספנו מכסות לדקה לכל פרויקט להעברת הודעות במורד הזרם. מכסת ברירת המחדל של 600,000 הודעות לדקה מכסה יותר מ-99% מהמפתחים של FCM, תוך שמירה על יציבות המערכת והקטנת ההשפעה של פרויקטים עם עומסים חריגים.

דפוסי תנועה חדים עלולים לגרום לשגיאות שלחרגו מהמכסה. בתרחיש שלחריגה מהמכסה, המערכת תחזיר את קוד הסטטוס HTTP 429 (QUOTA_EXCEEDED) עד שהמכסה תתמלא מחדש בדקה הבאה. ייתכן שתקבלו תשובות עם קוד 429 גם במצבי עומס יתר, לכן מומלץ מאוד לטפל בתשובות עם קוד 429 בהתאם להמלצות שפורסמו.

חשוב לזכור:

• המכסה ב-downstream מודדת הודעות, לא בקשות.
• שגיאות לקוח (קודי סטטוס HTTP 400-499) נספרות (לא כולל 429).
• המכסות הן לדקה, אבל הדקות האלה לא מותאמות לשעון.

מכסת ניטור

אפשר לראות את המכסות, השימוש והשגיאות במסוף Google Cloud:

1. נכנסים למסוף Google Cloud
2. בוחרים באפשרות APIs & services.
3. ברשימה של הטבלה, בוחרים באפשרות Firebase Cloud Messaging API.
4. בוחרים באפשרות QUOTA & SYSTEM LIMITS.

הערה: התרשימים האלה לא מותאמים במדויק לזמן של דקות המכסה, כלומר יכול להיות שיוצגו קוד השגיאה 429 גם כשמספר הבקשות נראה נמוך מהמכסה.

איך מבקשים להגדיל את המכסות?

לפני שמבקשים להגדיל את המכסה, חשוב לוודא:

• השימוש שלכם הוא לפחות 80% מהמכסה במשך 5 דקות רצופות לפחות ביום.
• שיעור השגיאות בצד הלקוח נמוך מ-5%, במיוחד בשעות השיא של התנועה.
• פועלים לפי השיטות המומלצות לשליחת הודעות בקנה מידה נרחב.

אם אתם עומדים בקריטריונים האלה, תוכלו לשלוח בקשה להגדלת המכסה בשיעור של עד 25%, ו-FCM תעשה כל מאמץ מעשי כדי למלא את הבקשה (אי אפשר להבטיח הגדלה).

אם אתם זקוקים למכסה גדולה יותר לשליחת הודעות במורד הזרם בגלל השקה קרובה או אירוע זמני, עליכם לבקש את המכסה לפחות 15 יום מראש כדי שיהיה לנו מספיק זמן לטפל בבקשה. לבקשות גדולות (יותר מ-18 מיליון הודעות לדקה), נדרש הודעה מראש של 30 יום לפחות. בקשות להשקות ולאירועים מיוחדים עדיין כפופות לדרישות לגבי שיעור השגיאות בצד הלקוח ולשיטות המומלצות.

אפשר גם לעיין בשאלות הנפוצות בנושא מכסות FCM.

מגבלת הודעות בנושא

קצב ההוספה/הסרה של מינויים לנושאים מוגבל ל-3,000 בקשות לשנייה לכל פרויקט.

בהסבר על הגבלת קצב השליחה של הודעות מוסבר על שיעורי שליחת ההודעות.

ויסות נתונים (throttle) של fanout

העברת הודעות היא תהליך השליחה של הודעה לכמה מכשירים, למשל כשמטרגטים נושאים וקבוצות, או כשמשתמשים בכלי ליצירת התראות כדי לטרגט קהלים או פלחים של משתמשים.

ההפצה של ההודעות לא מתבצעת באופן מיידי, ולכן לפעמים יש כמה הפצות בו-זמנית. אנחנו מגבילים את מספר ההודעות שאפשר לשלוח בו-זמנית לכל צד ל-1,000. לאחר מכן, יכול להיות שנדחה בקשות נוספות להפצה לגורמים נוספים או נדחה את ההפצה של הבקשות עד להשלמת חלק מההפצות שכבר נמצאות בטיפול.

שיעור ההסתעפות בפועל מושפע ממספר הפרויקטים שמבקשים הסתעפות בו-זמנית. קצב פיזור של 10,000 בקשות לשנייה בפרויקט ספציפי הוא לא נדיר, אבל המספר הזה לא מובטח והוא תוצאה של העומס הכולל על המערכת. חשוב לציין שיכולת ההסתעפות הזמינה מחולקת בין פרויקטים ולא בין בקשות להסתעפות. לכן, אם יש בפרויקט שני פילוחים מתמשכים, כל אחד מהם יקבל רק מחצית מרמת הפיצול הזמינה. כדי למקסם את מהירות ההתפצלות, מומלץ להפעיל רק פעולת התפלגות אחת בכל פעם.

הגבלת התקשורת של הודעות שכווצו

כפי שמתואר למעלה, הודעות שניתן לכווץ הן התראות ללא תוכן שנועדו להתקפל אחת על גבי השנייה. אם מפתח חוזר על אותה הודעה באפליקציה בתדירות גבוהה מדי, אנחנו מעכבים (מצמצמים) את ההודעות כדי לצמצם את ההשפעה על הסוללה של המשתמש.

לדוגמה, אם שולחים מספר גדול של בקשות חדשות לסנכרון אימייל למכשיר אחד, יכול להיות שנאחר את הבקשה הבאה לסנכרון האימייל בכמה דקות כדי שהמכשיר יוכל לסנכרן בקצב ממוצע נמוך יותר. המטרה היחידה של הצמצום הזה היא להגביל את ההשפעה על הסוללה של המשתמש.

אם בתרחיש לדוגמה שלכם נדרש דפוס שליחה של אירועים מרובים בבת אחת, הודעות שלא ניתן לכווץ עשויות להיות הבחירה הנכונה. כדי לצמצם את עלות השימוש בסוללה, חשוב לכלול את התוכן בהודעות כאלה.

אנחנו מגבילים את מספר ההודעות שניתן לכווץ ל-20 הודעות לכל אפליקציה בכל מכשיר, עם הוספה של הודעה אחת כל 3 דקות.

הגבלת רוחב הפס של שרת XMPP

זהירות: ב-20 ביוני 2023 הוצאנו משימוש את האפשרות לשלוח הודעות (כולל הודעות ב-upstream) באמצעות ממשקי ה-API הקודמים של FCM XMPP ו-HTTP, והם יוסרו החל מיוני 2024. אם אתם משתמשים בממשקי ה-API הקודמים לשליחה של FCM, מומלץ מאוד לעבור ל-HTTP v1 API או להשתמש ב-Admin SDK כדי ליצור בקשות שליחה.

אנחנו מגבילים את הקצב שבו אפשר להתחבר לשרתים של FCM XMPP ל-400 חיבורים לדקה לכל פרויקט. זה לא אמור להפריע לשליחת ההודעות, אבל חשוב לוודא את היציבות של המערכת. לכל פרויקט, ‏FCM מאפשר 2,500 חיבורים בו-זמנית.

בהודעות מ-upstream באמצעות XMPP, מערכת FCM מגבילה את מספר הודעות ה-upstream ל-1,500,000 בדקה לכל פרויקט, כדי למנוע עומס יתר על שרתי היעד של ה-upstream.

אנחנו מגבילים את מספר ההודעות שפועלות בכיוון 'מעלה' לכל מכשיר ל-1,000 הודעות לדקה, כדי להגן מפני שחיקה של הסוללה כתוצאה מהתנהגות לא תקינה של אפליקציות.

קצב ההודעות המקסימלי למכשיר יחיד

ב-Android, אפשר לשלוח עד 240 הודעות בדקה ו-5,000 הודעות לשעה למכשיר אחד. הסף הגבוה הזה נועד לאפשר התפרצויות קצרות טווח של תנועה, למשל כשמשתמשים מקיימים אינטראקציה מהירה בצ'אט. המגבלה הזו מונעת שגיאות בלוגיקה של השליחה שעלולות לרוקן בטעות את הסוללה במכשיר.

ב-iOS, אנחנו מחזירים שגיאה כשהקצב חורג מהמגבלות של APN.

זהירות: אין לשלוח הודעות באופן שוטף בקצב קרוב לקצב המקסימלי הזה. הפעולה הזו עלולה לבזבז את המשאבים של משתמשי הקצה, והאפליקציה שלכם עשויה להיות מסומנת כשימוש לרעה.

יציאות 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

חומות אש של תרגום כתובות רשת ו/או בדיקת חבילות עם מצב (stateful):

אם ברשת שלכם מופעלת תרגום כתובות רשת (NAT) או בדיקה של מנות עם מצב (SPI), צריך להגדיר זמן קצוב לתפוגה של 30 דקות או יותר לחיבורים שלנו ביציאות 5228-5230. כך אנחנו יכולים לספק קישוריות מהימנה תוך צמצום צריכת הסוללה של המכשירים הניידים של המשתמשים.

הערה: אם אתם מקבלים התראות דרך APN, ודאו שפתחתם גם את היציאות שצוינו על ידי Apple.

אינטראקציות של VPN ואפשרות לעקוף אותן

Firebase Cloud Messaging מבצעת פעולות שונות כדי לוודא שהחיבור להודעות הדחיפה מהטלפון לשרת אמין וזמין כמה שיותר. השימוש ב-VPN מסבך את המאמץ הזה.

רשתות VPN מסתיירות את המידע הבסיסי ש-FCM צריך כדי לכוונן את החיבור שלו, כדי למקסם את האמינות ואת חיי הסוללה. במקרים מסוימים, רשתות VPN משבשות באופן פעיל חיבורים לטווח ארוך, וכתוצאה מכך חוויית המשתמש נפגעת בגלל הודעות שלא התקבלו או הודעות שהתקבלו באיחור, או בגלל עלות גבוהה של הסוללה. כשה-VPN מוגדר לאפשר לנו לעשות זאת, אנחנו עוקפים את ה-VPN באמצעות חיבור מוצפן (דרך הרשת הבסיסית, Wi-Fi או LTE) כדי להבטיח חוויה מהימנה וחסכנית בסוללה. השימוש של FCM ב-VPN שניתן לעקוף הוא ספציפי לערוץ ההתראות של FCM. תנועה אחרת של FCM, כמו תנועה של רישום, משתמשת ב-VPN אם הוא פעיל. כשהחיבור FCM עובר על פני ה-VPN, הוא מאבד את היתרונות הנוספים שה-VPN יכול לספק, כמו אנונימיזציה של כתובת ה-IP.

לרשתות VPN שונות יש שיטות שונות לבדוק אם אפשר לעקוף אותן. לקבלת הוראות, יש לעיין במסמכים של ה-VPN הספציפי.

אם ה-VPN לא מוגדר כאפשרות לעקיפה, Firebase Cloud Messaging ישתמש ברשת ה-VPN כדי להתחבר לשרת. כתוצאה מכך, יכול להיות שיהיה עיכוב בהעברת הודעות ויכול להיות שצריכת הסוללה תהיה גבוהה יותר, כי Cloud Messaging פועל כדי לשמור על החיבור דרך חיבור ה-VPN.

פרטי כניסה

בהתאם לתכונות של FCM שתטמיעו, יכול להיות שתצטרכו את פרטי הכניסה הבאים מפרויקט Firebase:

מזהה פרויקט	מזהה ייחודי של פרויקט Firebase, שמשמש בבקשות לנקודת הקצה של HTTP v1‏ FCM. הערך הזה זמין בחלונית Settings במסוף Firebase.
טוקן הרשמה	מחרוזת אסימון ייחודית שמזהה כל מופע של אפליקציית לקוח. טוקן הרישום נדרש לשליחת הודעות למכשיר יחיד ולקבוצות של מכשירים. חשוב לזכור שאסור לחשוף את אסימוני הרישום.
מזהה השולח	ערך מספרי ייחודי שנוצר כשיוצרים את פרויקט Firebase. הערך זמין בכרטיסייה Cloud Messaging בחלונית Settings במסוף Firebase. מזהה השולח משמש לזיהוי כל שולח שיכול לשלוח הודעות לאפליקציית הלקוח.
אסימון גישה	אסימון OAuth 2.0 לטווח קצר שמאשר בקשות ל-API של HTTP v1. האסימון הזה משויך לחשבון שירות ששייך לפרויקט שלכם ב-Firebase. כדי ליצור אסימוני גישה ולבצע רוטציה שלהם, פועלים לפי השלבים שמפורטים בקטע אימות בקשות שליחה.
מפתח שרת (לפרוטוקולים קודמים **שהווצאו משימוש**)	מפתח שרת שמעניק הרשאה לשרת האפליקציה לגשת לשירותי Google, כולל שליחת הודעות באמצעות הפרוטוקולים הקודמים של Firebase Cloud Messaging שכבר הוצאו משימוש. חשוב: אל תכללו את מפתח השרת בשום מקום בקוד הלקוח. בנוסף, חשוב להשתמש רק במפתחות שרת כדי לאשר את שרת האפליקציה. מפתחות של Android, פלטפורמת Apple ומפתחות דפדפן נדחים על ידי FCM.