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

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

סוגי הודעות

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

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

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

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

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

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

הודעות התראה

לצורך בדיקה או לצורכי שיווק ויצירת עניין מחדש בקרב משתמשים, אפשר לשלוח הודעות התראה באמצעות מסוף 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. ב כתיבה של התראות, משתמשים בשדות Custom data בקטע Advanced options (אפשרויות מתקדמות).

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

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

זוהי הודעה בפורמט JSON שמכילה גם את המפתח notification וגם את המפתח data:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

התאמה אישית של הודעה בכמה פלטפורמות

פרוטוקול ה-HTTP של 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 לא מבטיחה את סדר המסירה.

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

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

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

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

כדי לסמן הודעה כניתנת לכיווץ ב-Android, צריך לכלול את הפרמטר collapse_key במטען הייעודי (Payload) של ההודעות. כברירת מחדל, מפתח ההתכווצות הוא שם חבילת האפליקציה שרשום במסוף 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"
      }
    }
  }
}

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

• מסמכי תיעוד של נקודות APN
• הגדרה וניהול של עדיפות ההודעות (ב-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, המסך פועל ואין הגבלות של ויסות נתונים (throttle), ההודעה תימסר מיד.

אם המכשיר מחובר אבל במצב 'נמנום', הודעה בעדיפות נמוכה תישמר על ידי 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) נספרות (לא כולל 429s).
• המכסות הן לדקה, אבל הדקות האלה לא מותאמות לשעון.

מכסת ניטור

אתם יכולים לראות את המכסות, השימוש והשגיאות במסוף 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 QPS לכל פרויקט.

למידע על קצב שליחת ההודעות, ראו ויסות נתונים (throttle).

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

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

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

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

הגבלת התקשורת של הודעות שניתן לכיווץ

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

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

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

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