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

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

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

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

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

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

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

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

אפשרויות משלוח

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

פרטי כניסה

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

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

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