Firebase Cloud Messaging (FCM) طیف گسترده ای از گزینه ها و قابلیت های پیام رسانی را ارائه می دهد. اطلاعات موجود در این صفحه به شما کمک می کند تا انواع مختلف پیام های FCM و کارهایی که می توانید با آنها انجام دهید را درک کنید.
انواع پیام
با FCM می توانید دو نوع پیام را به مشتریان ارسال کنید:
- پیام‌های اعلان، که گاهی اوقات به عنوان «پیام‌های نمایشی» در نظر گرفته می‌شوند. اینها توسط FCM SDK به طور خودکار مدیریت می شوند.
- پیام های داده، که توسط برنامه مشتری مدیریت می شود.
پیام های اعلان شامل مجموعه ای از کلیدهای از پیش تعریف شده قابل مشاهده توسط کاربر است. در مقابل، پیام‌های داده فقط شامل جفت‌های کلید-مقدار سفارشی تعریف‌شده توسط کاربر هستند. پیام‌های اعلان می‌توانند حاوی یک بار داده اختیاری باشند. حداکثر بار برای هر دو نوع پیام 4000 بایت است، به جز زمانی که پیام‌ها از کنسول Firebase ارسال می‌شود که محدودیت 1024 کاراکتری را اعمال می‌کند.
| از سناریو استفاده کنید | نحوه ارسال | |
|---|---|---|
| پیام اعلان | FCM SDK زمانی که برنامه در پس‌زمینه اجرا می‌شود، پیام را از طرف برنامه مشتری به دستگاه‌های کاربر نهایی نمایش می‌دهد. در غیر این صورت، اگر برنامه هنگام دریافت اعلان در پیش زمینه اجرا شود، کد برنامه رفتار را تعیین می کند. پیام‌های اعلان دارای مجموعه‌ای از کلیدهای قابل مشاهده برای کاربر و یک بار داده اختیاری از جفت‌های کلید-مقدار سفارشی هستند. |
|
| پیام داده | برنامه مشتری مسئول پردازش پیام های داده است. پیام های داده فقط دارای جفت های سفارشی کلید-مقدار بدون نام کلید رزرو شده هستند (به زیر مراجعه کنید). | در یک محیط مطمئن مانند توابع Cloud یا سرور برنامه‌تان، از 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 (به معماری FCM مراجعه کنید) از رمزگذاری نقطه به نقطه استفاده می کند. بسته به نیازتان، ممکن است تصمیم بگیرید که رمزگذاری سرتاسری را به پیام‌های داده اضافه کنید. FCM راه حل سرتاسری ارائه نمی دهد. با این حال، راه حل های خارجی مانند مویرگی یا DTLS وجود دارد.
پیام‌های اعلان با بار داده اختیاری
هم به صورت برنامه‌نویسی و هم از طریق کنسول Firebase، می‌توانید پیام‌های اعلان ارسال کنید که حاوی یک بار اختیاری از جفت‌های کلید-مقدار سفارشی است. در آهنگساز Notifications ، از فیلدهای داده سفارشی در گزینه های پیشرفته استفاده کنید.
رفتار برنامه هنگام دریافت پیام‌هایی که شامل اعلان‌ها و بارهای داده می‌شوند به این بستگی دارد که آیا برنامه در پس‌زمینه یا پیش‌زمینه قرار دارد – اساساً فعال بودن یا نبودن آن در زمان دریافت.
- در پس‌زمینه ، برنامه‌ها بار اعلان را در سینی اعلان دریافت می‌کنند و تنها زمانی که کاربر روی اعلان ضربه می‌زند، محموله داده را مدیریت می‌کنند.
- زمانی که برنامه شما در پیش زمینه است ، یک شیء پیام با هر دو بار در دسترس دریافت می کند.
در اینجا یک پیام با فرمت JSON حاوی کلید notification و کلید data است:
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"title":"Portugal vs. Denmark",
"body":"great match!"
},
"data" : {
"Nick" : "Mario",
"Room" : "PortugalVSDenmark"
}
}
}سفارشی کردن پیام در پلتفرم ها
Firebase Admin SDK و پروتکل FCM v1 HTTP هر دو به درخواست های پیام شما اجازه می دهند تمام فیلدهای موجود در شی message را تنظیم کنند. این شامل:
- مجموعه ای مشترک از فیلدها که باید توسط همه نمونه های برنامه ای که پیام را دریافت می کنند تفسیر شوند.
- مجموعه‌هایی از فیلدهای مخصوص پلتفرم، مانند
AndroidConfigوWebpushConfig، که فقط توسط نمونه‌های برنامه‌ای که در پلتفرم مشخص‌شده اجرا می‌شوند تفسیر می‌شوند.
بلوک‌های مخصوص پلتفرم به شما انعطاف‌پذیری می‌دهند تا پیام‌ها را برای پلتفرم‌های مختلف سفارشی کنید تا اطمینان حاصل کنید که هنگام دریافت به‌درستی با آنها برخورد می‌شود. پشتیبان FCM تمام پارامترهای مشخص شده را در نظر می گیرد و پیام را برای هر پلتفرم سفارشی می کند.
زمان استفاده از فیلدهای مشترک
وقتی هستید از فیلدهای مشترک استفاده کنید:
- هدف قرار دادن نمونه های برنامه در همه پلتفرم ها - اپل، اندروید و وب
- ارسال پیام به موضوعات
همه نمونه های برنامه، صرف نظر از پلتفرم، می توانند فیلدهای مشترک زیر را تفسیر کنند:
زمان استفاده از فیلدهای خاص پلتفرم
زمانی که می خواهید از فیلدهای مخصوص پلتفرم استفاده کنید:
- فیلدها را فقط به پلتفرم های خاص ارسال کنید
- علاوه بر فیلدهای مشترک، فیلدهای مخصوص پلتفرم را ارسال کنید
هر زمان که می‌خواهید مقادیر را فقط به پلتفرم‌های خاصی ارسال کنید، از فیلدهای مشترک استفاده نکنید . از فیلدهای مخصوص پلتفرم استفاده کنید. به عنوان مثال، برای ارسال نوتیفیکیشن فقط به پلتفرم‌های اپل و وب اما نه برای اندروید، باید از دو مجموعه فیلد جداگانه، یکی برای اپل و دیگری برای وب استفاده کنید.
وقتی پیام هایی با گزینه های تحویل خاص ارسال می کنید، از فیلدهای مخصوص پلتفرم برای تنظیم آنها استفاده کنید. در صورت تمایل می توانید مقادیر مختلفی را برای هر پلتفرم مشخص کنید. با این حال، حتی زمانی که می‌خواهید اساساً مقدار یکسانی را در بین پلتفرم‌ها تنظیم کنید، باید از فیلدهای مخصوص پلتفرم استفاده کنید. این به این دلیل است که هر پلتفرم ممکن است مقدار را کمی متفاوت تفسیر کند - برای مثال، زمان برای زندگی در Android به عنوان زمان انقضا بر حسب ثانیه تنظیم می شود، در حالی که در اپل به عنوان تاریخ انقضا تنظیم می شود.
مثال: پیام اعلان با گزینه های تحویل خاص پلت فرم
درخواست ارسال v1 زیر یک عنوان اعلان و محتوای مشترک را به همه پلتفرم‌ها ارسال می‌کند، اما برخی موارد لغو خاص پلتفرم را نیز ارسال می‌کند. به طور خاص، درخواست:
- مدت زمان طولانی را برای پلتفرم‌های اندروید و وب تعیین می‌کند، در حالی که اولویت پیام APN (پلتفرم‌های اپل) را روی تنظیمات کم تنظیم می‌کند.
- کلیدهای مناسب را برای تعیین نتیجه ضربه زدن کاربر روی اعلان در اندروید و اپل تنظیم می کند — به ترتیب
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 فراهم می‌کند و امکان گزینه‌های مشابه را در پلتفرم‌های اپل و وب فراهم می‌کند. برای مثال، رفتار پیام «تاشدنی» در Android از طریق collapse_key FCM، در Apple از طریق apns-collapse-id و در JavaScript/Web از طریق Topic پشتیبانی می‌شود. برای جزئیات، به توضیحات در این بخش و مستندات مرجع مرتبط مراجعه کنید.
پیام های تاشو و غیر قابل جمع شدن
یک پیام غیرقابل جمع شدن نشان می دهد که هر پیام جداگانه به دستگاه تحویل داده می شود. یک پیام غیرقابل جمع کردن، محتوای مفیدی را ارائه می‌کند، برخلاف پیام‌های جمع‌شونده مانند پینگ بدون محتوا به برنامه تلفن همراه برای تماس با سرور برای واکشی داده‌ها.
برخی از موارد استفاده معمول از پیام‌های غیرقابل جمع شدن، پیام‌های چت یا پیام‌های مهم هستند. به عنوان مثال، در یک برنامه IM، می خواهید هر پیامی را تحویل دهید، زیرا هر پیام دارای محتوای متفاوتی است.
برای اندروید محدودیت 100 پیام وجود دارد که می توان آنها را بدون جمع کردن ذخیره کرد. در صورت رسیدن به حد مجاز، همه پیام های ذخیره شده حذف می شوند. هنگامی که دستگاه دوباره آنلاین می شود، پیام خاصی دریافت می کند که نشان می دهد به محدودیت رسیده است. سپس برنامه می‌تواند وضعیت را به درستی مدیریت کند، معمولاً با درخواست همگام‌سازی کامل از سرور برنامه.
پیام جمع‌شدنی پیامی است که اگر هنوز به دستگاه ارسال نشده باشد، ممکن است با یک پیام جدید جایگزین شود.
موارد استفاده رایج از پیام‌های جمع‌شونده، پیام‌هایی هستند که به برنامه تلفن همراه می‌گویند داده‌های سرور را همگام‌سازی کند. یک مثال می تواند یک برنامه ورزشی باشد که کاربران را با آخرین امتیاز به روز می کند. فقط جدیدترین پیام مرتبط است.
برای علامت‌گذاری پیام به‌عنوان قابل جمع‌شدگی در Android، پارامتر collapse_key را در بار پیام اضافه کنید. به طور پیش‌فرض، کلید collapse نام بسته برنامه ثبت شده در کنسول 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 پیام را ذخیره می کند و به محض اینکه امکان پذیر باشد، آن را تحویل می دهد. در حالی که این در اکثر موارد خوب است، برخی از برنامه‌ها هستند که ممکن است هرگز پیام دیرهنگام برای آنها ارسال نشود. به عنوان مثال، اگر پیام یک تماس ورودی یا اعلان چت تصویری باشد، فقط برای مدت کوتاهی قبل از پایان تماس معنادار است. یا اگر پیام دعوت به یک رویداد باشد، اگر بعد از پایان رویداد دریافت شود، بی فایده است.
در اندروید و وب/جاوا اسکریپت، می توانید حداکثر طول عمر یک پیام را مشخص کنید. مدت زمان باید از 0 تا 2419200 ثانیه (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 تنظیم شده باشد.
برای دریافت بینش بیشتر در مورد تحویل یک پیام:
برای دریافت اطلاعات بیشتر در مورد تحویل پیام‌ها در پلتفرم‌های Android یا Apple، به داشبورد گزارش FCM مراجعه کنید، که تعداد پیام‌های ارسال‌شده و بازشده در دستگاه‌های Apple و Android را همراه با داده‌های «impressions» (اعلان‌هایی که کاربران مشاهده می‌کنند) را ثبت می‌کند. برنامه های اندروید
برای دستگاه‌های Android با پیام‌رسانی مستقیم کانال فعال، اگر دستگاه بیش از یک ماه به FCM وصل نشده باشد، FCM همچنان پیام را می‌پذیرد اما فوراً آن را نادیده می‌گیرد. اگر دستگاه در عرض چهار هفته از آخرین پیام داده ای که به آن ارسال کرده اید متصل شود، کلاینت شما پاسخ تماس ()onDeletedMessages را دریافت می کند. سپس برنامه می‌تواند وضعیت را به درستی مدیریت کند، معمولاً با درخواست همگام‌سازی کامل از سرور برنامه.
در نهایت، زمانی که FCM تلاش می‌کند پیامی را به دستگاه ارسال کند و برنامه حذف شد، FCM فوراً آن پیام را کنار گذاشته و رمز ثبت نام را باطل می‌کند. تلاش‌های بعدی برای ارسال پیام به آن دستگاه منجر به خطای NotRegistered می‌شود.
دریچه گیری و پوسته پوسته شدن
هدف ما این است که همیشه هر پیامی را که از طریق FCM ارسال می شود، ارائه دهیم. با این حال، ارائه هر پیام گاهی اوقات منجر به تجربه کلی ضعیف کاربر می شود. در موارد دیگر، ما باید مرزهایی را برای اطمینان از اینکه FCM یک سرویس مقیاس پذیر برای همه فرستنده ها ارائه می دهد، فراهم کنیم.
خفه کردن پیام تاشو
همانطور که در بالا توضیح داده شد، پیام‌های جمع‌شونده اعلان‌هایی بدون محتوا هستند که برای جمع شدن روی یکدیگر طراحی شده‌اند. در صورتی که یک برنامه‌نویس به طور مکرر همان پیام را برای یک برنامه تکرار کند، پیام‌ها را به تأخیر می‌اندازیم تا تأثیر آن بر باتری کاربر کاهش یابد.
برای مثال، اگر تعداد زیادی درخواست همگام‌سازی ایمیل جدید را به یک دستگاه ارسال کنید، ممکن است درخواست همگام‌سازی ایمیل بعدی را چند دقیقه به تأخیر بیندازیم تا دستگاه بتواند با سرعت متوسط پایین‌تری همگام‌سازی شود. این دریچه گاز به شدت برای محدود کردن تاثیر باتری تجربه شده توسط کاربر انجام می شود.
اگر مورد استفاده شما به الگوهای ارسال پشت سر هم زیاد نیاز دارد، پیام های غیرقابل جمع شدن ممکن است انتخاب مناسبی باشند. برای چنین پیام‌هایی، حتماً محتوا را در چنین پیام‌هایی قرار دهید تا هزینه باتری کاهش یابد.
ما پیام‌های جمع‌شونده را به 20 پیام در هر برنامه در هر دستگاه محدود می‌کنیم و هر 3 دقیقه یک پیام را دوباره پر می‌کنیم.
خفه کردن سرور XMPP
ما نرخ اتصال شما به سرورهای FCM XMPP را به 400 اتصال در دقیقه در هر پروژه محدود می کنیم. این نباید برای تحویل پیام مشکلی ایجاد کند، اما برای اطمینان از ثبات سیستم ما مهم است.
برای هر پروژه، FCM اجازه 2500 اتصال را به صورت موازی می دهد.
حداکثر نرخ پیام به یک دستگاه
برای اندروید، می‌توانید تا 240 پیام در دقیقه و 5000 پیام در ساعت به یک دستگاه واحد ارسال کنید. این آستانه بالا به این منظور است که امکان انبوه ترافیک کوتاه مدت را فراهم می کند، مانند زمانی که کاربران به سرعت از طریق چت در حال تعامل هستند. این محدودیت از تخلیه ناخواسته باتری روی دستگاه خطا در ارسال منطق جلوگیری می کند.
برای iOS، زمانی که نرخ از محدودیت‌های APN فراتر رود، خطا را برمی‌گردانیم.
محدودیت پیام بالادستی
ما پیام‌های بالادستی را در 1500000 در دقیقه در هر پروژه محدود می‌کنیم تا از بارگذاری بیش از حد سرورهای مقصد بالادست جلوگیری کنیم.
ما پیام‌های بالادستی را برای هر دستگاه در 1000 در دقیقه محدود می‌کنیم تا در برابر تخلیه باتری در اثر رفتار بد برنامه محافظت کنیم.
محدودیت پیام موضوع
نرخ اضافه/حذف اشتراک موضوع به 3000 QPS در هر پروژه محدود شده است.
برای نرخ‌های ارسال پیام، به Fanout Throttling مراجعه کنید.
دریچه گاز فان اوت
پیام Fanout فرآیند ارسال پیام به چندین دستگاه است، مانند زمانی که موضوعات و گروه‌ها را هدف قرار می‌دهید، یا زمانی که از سازنده Notifications برای هدف قرار دادن مخاطبان یا بخش‌های کاربر استفاده می‌کنید.
پیام fanout آنی نیست و بنابراین گاهی اوقات شما چندین fanout به طور همزمان در حال انجام است. تعداد پیام‌های همزمان در هر پروژه را به 1000 محدود می‌کنیم. پس از آن، ممکن است درخواست‌های fanout اضافی را رد کنیم یا fanout درخواست‌ها را تا زمانی که برخی از Fanoutهای در حال انجام کامل تکمیل شوند به تعویق بیاندازیم.
نرخ واقعی fanout قابل دستیابی تحت تأثیر تعداد پروژه هایی است که همزمان درخواست fanout می کنند. نرخ fanout 10000 QPS برای یک پروژه غیر معمول نیست، اما این عدد تضمینی نیست و نتیجه کل بار روی سیستم است. توجه به این نکته مهم است که ظرفیت fanout موجود بین پروژه‌ها تقسیم می‌شود و نه بین درخواست‌های fanout. بنابراین، اگر پروژه شما دارای دو 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
فایروال های ترجمه آدرس شبکه و/یا بازرسی بسته Stateful:
اگر شبکه شما ترجمه آدرس شبکه (NAT) یا بازرسی بسته Stateful (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 یا سرور برنامه‌تان، از 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 (به معماری FCM مراجعه کنید) از رمزگذاری نقطه به نقطه استفاده می کند. بسته به نیازتان، ممکن است تصمیم بگیرید که رمزگذاری سرتاسری را به پیام‌های داده اضافه کنید. FCM راه حل سرتاسری ارائه نمی دهد. با این حال، راه حل های خارجی مانند مویرگی یا DTLS وجود دارد.
پیام‌های اعلان با بار داده اختیاری
هم به صورت برنامه‌نویسی و هم از طریق کنسول Firebase، می‌توانید پیام‌های اعلان ارسال کنید که حاوی یک بار اختیاری از جفت‌های کلید-مقدار سفارشی است. در آهنگساز Notifications ، از فیلدهای داده سفارشی در گزینه های پیشرفته استفاده کنید.
رفتار برنامه هنگام دریافت پیام‌هایی که شامل اعلان‌ها و بارهای داده می‌شوند به این بستگی دارد که آیا برنامه در پس‌زمینه یا پیش‌زمینه قرار دارد – اساساً فعال بودن یا نبودن آن در زمان دریافت.
- در پس‌زمینه ، برنامه‌ها بار اعلان را در سینی اعلان دریافت می‌کنند و تنها زمانی که کاربر روی اعلان ضربه می‌زند، محموله داده را مدیریت می‌کنند.
- زمانی که برنامه شما در پیش زمینه است ، یک شیء پیام با هر دو بار در دسترس دریافت می کند.
در اینجا یک پیام با فرمت JSON حاوی کلید notification و کلید data است:
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"title":"Portugal vs. Denmark",
"body":"great match!"
},
"data" : {
"Nick" : "Mario",
"Room" : "PortugalVSDenmark"
}
}
}سفارشی کردن پیام در پلتفرم ها
Firebase Admin SDK و پروتکل FCM v1 HTTP هر دو به درخواست های پیام شما اجازه می دهند تمام فیلدهای موجود در شی message را تنظیم کنند. این شامل:
- مجموعه ای مشترک از فیلدها که باید توسط همه نمونه های برنامه ای که پیام را دریافت می کنند تفسیر شوند.
- مجموعه‌هایی از فیلدهای مخصوص پلتفرم، مانند
AndroidConfigوWebpushConfig، که فقط توسط نمونه‌های برنامه‌ای که در پلتفرم مشخص‌شده اجرا می‌شوند تفسیر می‌شوند.
بلوک‌های مخصوص پلتفرم به شما انعطاف‌پذیری می‌دهند تا پیام‌ها را برای پلتفرم‌های مختلف سفارشی کنید تا اطمینان حاصل کنید که هنگام دریافت به‌درستی با آنها برخورد می‌شود. پشتیبان FCM تمام پارامترهای مشخص شده را در نظر می گیرد و پیام را برای هر پلتفرم سفارشی می کند.
زمان استفاده از فیلدهای مشترک
وقتی هستید از فیلدهای مشترک استفاده کنید:
- هدف قرار دادن نمونه های برنامه در همه پلتفرم ها - اپل، اندروید و وب
- ارسال پیام به موضوعات
همه نمونه های برنامه، صرف نظر از پلتفرم، می توانند فیلدهای مشترک زیر را تفسیر کنند:
چه زمانی از فیلدهای مخصوص پلتفرم استفاده کنیم
زمانی که می خواهید از فیلدهای مخصوص پلتفرم استفاده کنید:
- فیلدها را فقط به پلتفرم های خاص ارسال کنید
- علاوه بر فیلدهای مشترک، فیلدهای مخصوص پلتفرم را ارسال کنید
هر زمان که می‌خواهید مقادیر را فقط به پلتفرم‌های خاصی ارسال کنید، از فیلدهای مشترک استفاده نکنید . از فیلدهای مخصوص پلتفرم استفاده کنید. به عنوان مثال، برای ارسال نوتیفیکیشن فقط به پلتفرم‌های اپل و وب اما نه برای اندروید، باید از دو مجموعه فیلد جداگانه، یکی برای اپل و دیگری برای وب استفاده کنید.
وقتی پیام هایی با گزینه های تحویل خاص ارسال می کنید، از فیلدهای مخصوص پلتفرم برای تنظیم آنها استفاده کنید. در صورت تمایل می توانید مقادیر مختلفی را برای هر پلتفرم مشخص کنید. با این حال، حتی زمانی که می‌خواهید اساساً مقدار یکسانی را در بین پلتفرم‌ها تنظیم کنید، باید از فیلدهای مخصوص پلتفرم استفاده کنید. این به این دلیل است که هر پلتفرم ممکن است مقدار را کمی متفاوت تفسیر کند - برای مثال، زمان برای زندگی در Android به عنوان زمان انقضا بر حسب ثانیه تنظیم می شود، در حالی که در اپل به عنوان تاریخ انقضا تنظیم می شود.
مثال: پیام اعلان با گزینه های تحویل خاص پلت فرم
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:
| شناسه پروژه | 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. |