درباره پیام های FCM

Firebase Cloud Messaging ( FCM ) طیف گسترده ای از گزینه ها و قابلیت های پیام رسانی را ارائه می دهد. اطلاعات موجود در این صفحه به شما کمک می کند تا انواع مختلف پیام های FCM و کارهایی که می توانید با آنها انجام دهید را درک کنید.

انواع پیام

با FCM ، می توانید دو نوع پیام به مشتریان ارسال کنید:

• پیام‌های اعلان، که گاهی اوقات به عنوان «پیام‌های نمایشی» در نظر گرفته می‌شوند. اینها توسط FCM SDK به طور خودکار مدیریت می شوند.
• پیام های داده، که توسط برنامه مشتری مدیریت می شود.

پیام های اعلان شامل مجموعه ای از کلیدهای از پیش تعریف شده قابل مشاهده توسط کاربر است. در مقابل، پیام‌های داده فقط شامل جفت‌های کلید-مقدار سفارشی تعریف‌شده توسط کاربر هستند. پیام‌های اعلان می‌توانند حاوی یک بار داده اختیاری باشند. حداکثر بار برای هر دو نوع پیام 4096 بایت است، به جز زمانی که پیام‌ها از کنسول Firebase ارسال می‌شود که محدودیت 1000 کاراکتری را اعمال می‌کند.

هنگامی که می‌خواهید 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!"
    }
  }
}

وقتی برنامه در پس‌زمینه است، پیام‌های اعلان به سینی اعلان تحویل داده می‌شوند. برای برنامه‌هایی که در پیش‌زمینه قرار دارند، پیام‌ها توسط یک عملکرد پاسخ به تماس مدیریت می‌شوند.

برای لیست کامل کلیدهای از پیش تعریف شده موجود برای پیام های اعلان ساختمان، به مستندات مرجع شی اعلان پروتکل HTTP v1 مراجعه کنید.

پیام های داده

کلید مناسب را با جفت های کلید-مقدار سفارشی خود تنظیم کنید تا یک بار داده به برنامه مشتری ارسال شود.

به عنوان مثال، در اینجا یک پیام با فرمت 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 تمام پارامترهای مشخص شده را در نظر می گیرد و پیام را برای هر پلتفرم سفارشی می کند.

زمان استفاده از فیلدهای مشترک

وقتی هستید از فیلدهای مشترک استفاده کنید:

• هدف قرار دادن نمونه های برنامه در همه پلتفرم ها - اپل، اندروید و وب
• ارسال پیام به موضوعات

همه نمونه های برنامه، صرف نظر از پلتفرم، می توانند فیلدهای مشترک زیر را تفسیر کنند:

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

زمان استفاده از فیلدهای مخصوص پلتفرم

زمانی که می خواهید از فیلدهای مخصوص پلتفرم استفاده کنید:

• فیلدها را فقط به پلتفرم های خاص ارسال کنید
• علاوه بر فیلدهای مشترک، فیلدهای مخصوص پلتفرم را ارسال کنید

هر زمان که می‌خواهید مقادیر را فقط به پلتفرم‌های خاصی ارسال کنید، از فیلدهای مشترک استفاده نکنید . از فیلدهای مخصوص پلتفرم استفاده کنید. به عنوان مثال، برای ارسال نوتیفیکیشن فقط به پلتفرم‌های اپل و وب اما نه برای اندروید، باید از دو مجموعه فیلد جداگانه، یکی برای اپل و دیگری برای وب استفاده کنید.

وقتی پیام هایی با گزینه های تحویل خاص ارسال می کنید، از فیلدهای مخصوص پلتفرم برای تنظیم آنها استفاده کنید. در صورت تمایل می توانید مقادیر مختلفی را برای هر پلتفرم مشخص کنید. با این حال، حتی زمانی که می‌خواهید اساساً مقدار یکسانی را در بین پلتفرم‌ها تنظیم کنید، باید از فیلدهای مخصوص پلتفرم استفاده کنید. این به این دلیل است که هر پلتفرم ممکن است مقدار را کمی متفاوت تفسیر کند - برای مثال، زمان برای زندگی در 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 سعی می‌کند پیام‌های با اولویت بالا را فوراً ارسال کند، حتی اگر دستگاه در حالت 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"
      }
    }
  }
}

برای جزئیات بیشتر پلتفرم خاص در مورد تنظیم اولویت پیام:

• اسناد APN
• تنظیم و مدیریت اولویت پیام (اندروید)
• فوریت پیام فشار وب

موارد استفاده حیاتی زندگی

APIهای FCM برای هشدارهای اضطراری یا سایر فعالیت‌های پرخطر که در آن استفاده یا خرابی APIها می‌تواند منجر به مرگ، آسیب‌های شخصی یا آسیب‌های محیطی شود (مانند عملکرد تأسیسات هسته‌ای، کنترل ترافیک هوایی یا سیستم‌های پشتیبانی حیات) طراحی نشده‌اند. هر گونه استفاده از این قبیل صراحتاً طبق بخش 4 ممنوع است. 7 از شرایط خدمات. شما تنها مسئول مدیریت مطابقت برنامه خود با شرایط و هرگونه آسیب ناشی از عدم رعایت شما هستید. Google APIها را «همان‌طور که هست» ارائه می‌کند و این حق را برای خود محفوظ می‌دارد که به هر دلیل و در هر زمان، APIها یا هر بخش یا ویژگی یا دسترسی شما به آن‌ها را بدون مسئولیت یا تعهد دیگری در قبال شما یا کاربرانتان قطع کند.

تنظیم طول عمر یک پیام

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 ثبت می کند.

برای دستگاه‌های Android با پیام‌رسانی مستقیم کانال فعال، اگر دستگاه بیش از یک ماه به FCM وصل نشده باشد، FCM همچنان پیام را می‌پذیرد اما فوراً آن را نادیده می‌گیرد. اگر دستگاه در عرض چهار هفته از آخرین پیام داده ای که به آن ارسال کرده اید متصل شود، کلاینت شما پاسخ تماس ()onDeletedMessages را دریافت می کند. سپس برنامه می‌تواند وضعیت را به درستی مدیریت کند، معمولاً با درخواست همگام‌سازی کامل از سرور برنامه.

در نهایت، زمانی که FCM تلاش می‌کند پیامی را به دستگاه ارسال کند و برنامه حذف شد، FCM فوراً آن پیام را کنار گذاشته و رمز ثبت نام را باطل می‌کند. تلاش‌های بعدی برای ارسال پیام به آن دستگاه منجر به خطای NotRegistered می‌شود.

گاز و سهمیه بندی

هدف ما این است که همیشه هر پیامی را که از طریق FCM ارسال می شود، ارائه دهیم. با این حال، ارائه هر پیام گاهی اوقات منجر به تجربه کلی ضعیف کاربر می شود. در موارد دیگر، ما باید مرزهایی را برای اطمینان از اینکه FCM یک سرویس مقیاس پذیر برای همه فرستنده ها ارائه می دهد، فراهم کنیم. انواع محدودیت ها و سهمیه های شرح داده شده در این بخش به ما کمک می کند تا این عوامل مهم را متعادل کنیم.

کاهش فشار پیام پایین دست

HTTP v1 API سهمیه‌های هر پروژه و در دقیقه را برای پیام‌رسانی پایین دستی معرفی کرد. سهمیه پیش‌فرض 600 هزار پیام در دقیقه، بیش از 99 درصد از توسعه‌دهندگان FCM پوشش می‌دهد و در عین حال از پایداری سیستم محافظت می‌کند و تأثیر پروژه‌های spiky را به حداقل می‌رساند.

الگوهای ترافیک تیره می تواند منجر به خطاهای بیش از حد سهمیه شود. در یک سناریوی بیش از سهمیه، سیستم کد وضعیت HTTP 429 (QUOTA_EXCEEDED) را تا زمانی که سهمیه در دقیقه بعد دوباره پر شود، ارائه می‌کند. 429 پاسخ نیز ممکن است در موقعیت‌های اضافه بار برگردانده شوند، بنابراین شما قویاً تشویق می‌شوید که 429 را طبق توصیه‌های منتشر شده مدیریت کنید.

توجه داشته باشید که:

• سهمیه پایین دستی پیام ها را اندازه گیری می کند نه درخواست ها.
• خطاهای مشتری (کد وضعیت HTTP 400-499) شمارش می شود (به استثنای 429s).
• سهمیه ها در هر دقیقه است، اما این دقیقه ها با ساعت هماهنگ نیستند.

سهمیه نظارت

می‌توانید سهمیه، استفاده و خطاها را در Google Cloud Console مشاهده کنید:

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 مراجعه کنید.

محدودیت پیام موضوع

نرخ اضافه/حذف اشتراک موضوع به 3000 QPS در هر پروژه محدود شده است.

برای نرخ‌های ارسال پیام، به Fanout Throttling مراجعه کنید.

دریچه گاز فان اوت

پیام Fanout فرآیند ارسال پیام به چندین دستگاه است، مانند زمانی که موضوعات و گروه‌ها را هدف قرار می‌دهید، یا زمانی که از سازنده Notifications برای هدف قرار دادن مخاطبان یا بخش‌های کاربر استفاده می‌کنید.

پیام fanout آنی نیست و بنابراین گاهی اوقات شما چندین fanout به طور همزمان در حال انجام است. تعداد پیام‌های هم‌زمان در هر پروژه را به 1000 محدود می‌کنیم. پس از آن، ممکن است درخواست‌های fanout اضافی را رد کنیم یا fanout درخواست‌ها را تا زمانی که برخی از Fanout‌های در حال انجام کامل تکمیل شوند به تعویق بیاندازیم.

نرخ واقعی fanout قابل دستیابی تحت تأثیر تعداد پروژه هایی است که همزمان درخواست fanout می کنند. نرخ fanout 10000 QPS برای یک پروژه غیر معمول نیست، اما این عدد تضمینی نیست و نتیجه کل بار روی سیستم است. توجه به این نکته مهم است که ظرفیت fanout موجود بین پروژه‌ها تقسیم می‌شود و نه بین درخواست‌های fanout. بنابراین، اگر پروژه شما دارای دو fanout در حال انجام باشد، هر fanout فقط نیمی از نرخ fanout موجود را خواهد دید. روش توصیه شده برای به حداکثر رساندن سرعت فن‌آوت این است که هر بار فقط یک فن‌آوت فعال در حال انجام باشد.

خفه کردن پیام تاشو

همانطور که در بالا توضیح داده شد، پیام‌های جمع‌شونده اعلان‌هایی بدون محتوا هستند که برای جمع شدن روی یکدیگر طراحی شده‌اند. در صورتی که یک برنامه‌نویس به طور مکرر همان پیام را برای یک برنامه تکرار کند، پیام‌ها را به تأخیر می‌اندازیم تا تأثیر آن بر باتری کاربر کاهش یابد.

برای مثال، اگر تعداد زیادی درخواست همگام‌سازی ایمیل جدید را به یک دستگاه ارسال کنید، ممکن است درخواست همگام‌سازی ایمیل بعدی را چند دقیقه به تأخیر بیندازیم تا دستگاه بتواند با سرعت متوسط ​​پایین‌تری همگام‌سازی شود. این دریچه گاز به شدت برای محدود کردن تاثیر باتری تجربه شده توسط کاربر انجام می شود.

اگر مورد استفاده شما به الگوهای ارسال پشت سر هم زیاد نیاز دارد، پیام های غیرقابل جمع شدن ممکن است انتخاب مناسبی باشند. برای چنین پیام‌هایی، حتماً محتوا را در چنین پیام‌هایی قرار دهید تا هزینه باتری کاهش یابد.

ما پیام‌های جمع‌شونده را به 20 پیام در هر برنامه در هر دستگاه محدود می‌کنیم و هر 3 دقیقه یک پیام را دوباره پر می‌کنیم.

خفه کردن سرور XMPP

ما نرخ اتصال شما به سرورهای FCM XMPP را به 400 اتصال در دقیقه در هر پروژه محدود می کنیم. این نباید برای تحویل پیام مشکلی ایجاد کند، اما برای اطمینان از ثبات سیستم مهم است. برای هر پروژه، FCM اجازه 2500 اتصال را به صورت موازی می دهد.

برای پیام‌رسانی بالادستی با XMPP، FCM پیام‌های بالادستی را به 1500000 در دقیقه در هر پروژه محدود می‌کند تا از بارگذاری بیش از حد سرورهای مقصد بالادست جلوگیری کند.

ما پیام‌های بالادستی را برای هر دستگاه در 1000 در دقیقه محدود می‌کنیم تا در برابر تخلیه باتری در اثر رفتار بد برنامه محافظت کنیم.

حداکثر نرخ پیام به یک دستگاه

برای اندروید، می‌توانید تا 240 پیام در دقیقه و 5000 پیام در ساعت به یک دستگاه واحد ارسال کنید. این آستانه بالا به این منظور است که امکان انبوه ترافیک کوتاه مدت را فراهم می کند، مانند زمانی که کاربران به سرعت از طریق چت در حال تعامل هستند. این محدودیت از تخلیه ناخواسته باتری روی دستگاه خطا در ارسال منطق جلوگیری می کند.

برای 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) یا بازرسی بسته Stateful (SPI) را اجرا می کند، یک بازه زمانی 30 دقیقه ای یا بیشتر برای اتصالات ما از طریق پورت های 5228-5230 اعمال کنید. این ما را قادر می‌سازد تا ضمن کاهش مصرف باتری دستگاه‌های تلفن همراه کاربران، اتصال قابل اعتمادی را ارائه دهیم.

تعاملات VPN و قابلیت دور زدن

Firebase Cloud Messaging اقدامات مختلفی را انجام می‌دهد تا اطمینان حاصل کند که اتصال پیام‌رسان فشاری از تلفن به سرور قابل اعتماد و تا حد امکان در دسترس است. استفاده از VPN این تلاش را پیچیده می کند.

VPN ها اطلاعات اساسی را که FCM برای تنظیم اتصال خود برای به حداکثر رساندن قابلیت اطمینان و عمر باتری نیاز دارد، پنهان می کند. در برخی موارد VPN ها به طور فعال اتصالات طولانی مدت را قطع می کنند که منجر به تجربه کاربری بد به دلیل پیام های از دست رفته یا تاخیر یا هزینه بالای باتری می شود. هنگامی که VPN به گونه‌ای پیکربندی شده است که به ما امکان انجام این کار را می‌دهد، ما VPN را با استفاده از یک اتصال رمزگذاری شده (از طریق شبکه وای فای پایه یا LTE) دور می‌زنیم تا از یک تجربه قابل اعتماد و سازگار با باتری اطمینان حاصل کنیم. استفاده FCM از VPN های قابل عبور مختص کانال FCM Push Notification است. سایر ترافیک های FCM ، مانند ترافیک ثبت نام، در صورت فعال بودن از VPN استفاده می کنند. هنگامی که اتصال FCM VPN را دور می زند، مزایای بیشتری را که VPN ممکن است ارائه دهد، مانند پوشاندن IP، از دست می دهد.

VPN های مختلف روش های مختلفی برای کنترل اینکه آیا می توان آن را دور زد یا خیر، خواهند داشت. برای دریافت دستورالعمل، با اسناد مربوط به VPN خاص خود مشورت کنید.

اگر VPN برای دور زدن پیکربندی نشده باشد، Firebase Cloud Messaging از شبکه VPN برای اتصال به سرور استفاده خواهد کرد. این ممکن است منجر به مدت‌هایی شود که پیام‌ها با تأخیر مواجه می‌شوند و ممکن است منجر به مصرف باتری بیشتر شود زیرا Cloud Messaging برای حفظ اتصال از طریق اتصال VPN کار می‌کند.

اعتبارنامه

بسته به ویژگی‌های FCM که پیاده‌سازی می‌کنید، ممکن است به اعتبارنامه‌های زیر از پروژه Firebase خود نیاز داشته باشید:

Firebase Cloud Messaging ( FCM ) طیف گسترده ای از گزینه ها و قابلیت های پیام رسانی را ارائه می دهد. اطلاعات موجود در این صفحه به شما کمک می کند تا انواع مختلف پیام های FCM و کارهایی که می توانید با آنها انجام دهید را درک کنید.

انواع پیام

با FCM ، می توانید دو نوع پیام به مشتریان ارسال کنید:

• پیام‌های اعلان، که گاهی اوقات به عنوان «پیام‌های نمایشی» در نظر گرفته می‌شوند. اینها توسط FCM SDK به طور خودکار مدیریت می شوند.
• پیام های داده، که توسط برنامه مشتری مدیریت می شود.

پیام های اعلان شامل مجموعه ای از کلیدهای از پیش تعریف شده قابل مشاهده توسط کاربر است. در مقابل، پیام‌های داده فقط شامل جفت‌های کلید-مقدار سفارشی تعریف‌شده توسط کاربر هستند. پیام‌های اعلان می‌توانند حاوی یک بار داده اختیاری باشند. حداکثر بار برای هر دو نوع پیام 4096 بایت است، به جز زمانی که پیام‌ها از کنسول Firebase ارسال می‌شود که محدودیت 1000 کاراکتری را اعمال می‌کند.

هنگامی که می‌خواهید 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!"
    }
  }
}

وقتی برنامه در پس‌زمینه است، پیام‌های اعلان به سینی اعلان تحویل داده می‌شوند. برای برنامه‌هایی که در پیش‌زمینه قرار دارند، پیام‌ها توسط یک عملکرد پاسخ به تماس مدیریت می‌شوند.

برای لیست کامل کلیدهای از پیش تعریف شده موجود برای پیام های اعلان ساختمان، به مستندات مرجع شی اعلان پروتکل HTTP v1 مراجعه کنید.

پیام های داده

کلید مناسب را با جفت های کلید-مقدار سفارشی خود تنظیم کنید تا یک بار داده به برنامه مشتری ارسال شود.

به عنوان مثال ، در اینجا یک پیام با فرمت JSON در همان برنامه IM همانطور که در بالا وجود دارد ، که در آن اطلاعات در کلید data مشترک محصور شده است و انتظار می رود برنامه مشتری محتوا را تفسیر کند:

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

مثال بالا استفاده از قسمت data سطح بالا یا مشترک را نشان می دهد که توسط مشتری در کلیه سیستم عامل هایی که پیام را دریافت می کنند ، تفسیر می شود. در هر سیستم عامل ، برنامه مشتری بار داده را در یک عملکرد پاسخ به تماس دریافت می کند.

رمزگذاری برای پیام های داده

لایه حمل و نقل Android (به معماری FCM مراجعه کنید) از رمزگذاری نقطه به نقطه استفاده می کند. بسته به نیاز شما ، ممکن است تصمیم بگیرید رمزگذاری پایان به پایان را به پیام های داده اضافه کنید. FCM یک راه حل پایان به پایان ارائه نمی دهد. با این حال ، راه حل های خارجی مانند مویرگی یا DTL وجود دارد.

پیام های اعلان با بار داده اختیاری

هر دو از نظر برنامه ای یا از طریق کنسول 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 ، که فقط توسط نمونه های برنامه در حال اجرا بر روی پلت فرم مشخص شده تفسیر می شوند.

بلوک های خاص پلتفرم به شما انعطاف پذیری می دهد تا پیام ها را برای سیستم عامل های مختلف شخصی سازی کنید تا اطمینان حاصل شود که در هنگام دریافت به درستی از آنها برخورد می شوند. BACEND FCM تمام پارامترهای مشخص شده را در نظر می گیرد و پیام را برای هر سیستم عامل سفارشی می کند.

چه زمانی از زمینه های مشترک استفاده کنید

در صورتی که از زمینه های مشترک استفاده کنید:

• هدف قرار دادن نمونه های برنامه در همه سیستم عامل ها - اپل ، اندروید و وب
• ارسال پیام به موضوعات

همه نمونه های برنامه ، صرف نظر از پلتفرم ، می توانند زمینه های مشترک زیر را تفسیر کنند:

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

چه زمانی از زمینه های خاص پلت فرم استفاده کنید

وقتی می خواهید از فیلدهای خاص پلتفرم استفاده کنید:

• ارسال قسمت ها فقط به سیستم عامل های خاص
• علاوه بر زمینه های مشترک ، زمینه های خاص سیستم عامل را ارسال کنید

هر زمان که می خواهید فقط به سیستم عامل های خاص مقادیر ارسال کنید ، از زمینه های مشترک استفاده نکنید . از زمینه های خاص پلتفرم استفاده کنید. به عنوان مثال ، برای ارسال یک اعلان فقط به سیستم عامل های اپل و وب اما نه به Android ، باید از دو مجموعه جداگانه از فیلد ، یکی برای اپل و دیگری برای وب استفاده کنید.

هنگامی که در حال ارسال پیام با گزینه های تحویل خاص هستید ، برای تنظیم آنها از قسمت های خاص پلتفرم استفاده کنید. در صورت تمایل می توانید مقادیر مختلفی را برای هر پلتفرم مشخص کنید. با این حال ، حتی وقتی می خواهید اساساً همان مقدار را در سیستم عامل ها تنظیم کنید ، باید از فیلدهای خاص پلتفرم استفاده کنید. این امر به این دلیل است که هر پلتفرم ممکن است مقدار کمی متفاوت را تفسیر کند-برای مثال ، زمان به زندگی در اندروید به عنوان زمان انقضا در ثانیه تنظیم می شود ، در حالی که در اپل به عنوان تاریخ انقضا تعیین شده است.

مثال: پیام اعلان با گزینه های تحویل خاص سیستم عامل

درخواست ارسال V1 زیر یک عنوان و محتوای اعلان مشترک را به همه سیستم عامل ها ارسال می کند ، اما همچنین برخی از موارد اضافی پلتفرم را ارسال می کند. به طور خاص ، درخواست:

• برای سیستم عامل های اندرویدی و وب ، در حالی که اولویت پیام APNS (Apple Platforms) را برای تنظیم کم تنظیم می کند ، تنظیم می کند.
• کلیدهای مناسب را برای تعریف نتیجه یک کاربر در اعلان در 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 ارائه می دهد و گزینه های مشابهی را در سیستم عامل های اپل و وب امکان پذیر می کند. به عنوان مثال ، رفتار پیام "Collapsible" از طریق collapse_key FCM ، در اپل از طریق apns-collapse-id ، و در JavaScript/Web از طریق Topic ، در Android پشتیبانی می شود. برای جزئیات بیشتر ، به توضیحات در این بخش و مستندات مرجع مربوطه مراجعه کنید.

پیام های غیر قابل جمع شدن و قابل جمع شدن

یک پیام غیر قابل سقوط نشان می دهد که هر پیام جداگانه به دستگاه تحویل داده می شود. یک پیام غیر قابل جمع شدن ، برخی از مطالب مفید را ارائه می دهد ، بر خلاف یک پیام قابل جمع شدن مانند "پینگ" بدون محتوا به برنامه تلفن همراه برای تماس با سرور برای واکشی داده ها.

برخی از موارد استفاده معمولی از پیام های غیر قابل جمع شدن ، پیام های گپ یا پیام های مهم هستند. به عنوان مثال ، در یک برنامه IM ، شما می خواهید هر پیام را ارسال کنید ، زیرا هر پیام دارای محتوای متفاوتی است.

برای اندروید محدودیت 100 پیام وجود دارد که می توانند بدون فروپاشی ذخیره شوند. در صورت رسیدن به حد ، تمام پیام های ذخیره شده دور ریخته می شوند. هنگامی که دستگاه به صورت آنلاین برگردد ، پیام خاصی دریافت می کند که نشان می دهد به حد رسیده است. سپس برنامه می تواند با درخواست همگام سازی کامل از سرور برنامه ، وضعیت را به درستی اداره کند.

یک پیام قابل جمع شدن پیامی است که در صورت ارسال هنوز به دستگاه ممکن است با یک پیام جدید جایگزین شود.

موارد استفاده متداول از پیام های قابل جمع شدن پیام هایی است که برای گفتن یک برنامه تلفن همراه برای همگام سازی داده های سرور استفاده می شود. یک مثال می تواند یک برنامه ورزشی باشد که کاربران را با آخرین امتیاز به روز می کند. فقط جدیدترین پیام مرتبط است.

برای علامت گذاری یک پیام به صورت قابل جمع شدن در Android ، پارامتر collapse_key را در Payload Message وارد کنید. به طور پیش فرض ، کلید Collapse نام بسته برنامه است که در کنسول Firebase ثبت شده است. سرور FCM می تواند به طور همزمان چهار پیام قابل جمع شدن مختلف را در هر دستگاه ذخیره کند که هر کدام دارای یک کلید فروپاشی متفاوت هستند. اگر از این شماره فراتر بروید ، FCM فقط چهار کلید فروپاشی را نگه می دارد ، بدون اینکه تضمینی در مورد کدام یک از آنها نگهداری شود.

پیام های موضوع بدون بار به طور پیش فرض قابل جمع شدن هستند. پیام های اعلان همیشه قابل جمع شدن هستند و پارامتر collapse_key نادیده می گیرند.

از کدوم استفاده کنم؟

پیام های قابل جمع شدن از نظر عملکرد انتخاب بهتری هستند ، مشروط بر اینکه برنامه شما نیازی به استفاده از پیام های غیر قابل جمع شدن ندارد. با این حال ، اگر از پیام های قابل جمع شدن استفاده می کنید ، به یاد داشته باشید که FCM فقط اجازه می دهد تا حداکثر چهار کلید مختلف فروپاشی توسط FCM در هر نشانه ثبت نام در هر زمان معین استفاده شود. شما نباید از این تعداد تجاوز کنید ، یا این می تواند عواقب غیرقابل پیش بینی را به همراه داشته باشد.

تنظیم اولویت یک پیام

شما دو گزینه برای اختصاص اولویت تحویل به پیام های پایین دست دارید: اولویت عادی و بالا. گرچه رفتار کمی در سکوها متفاوت است ، تحویل پیام های اولویت دار و با اولویت مانند این کار می کند:

• اولویت عادی پیام های اولویت عادی بلافاصله هنگامی که برنامه در پیش زمینه قرار دارد ، تحویل می شوند. برای برنامه های پس زمینه ، تحویل ممکن است به تأخیر بیفتد. برای پیام های حساس به زمان کمتر ، مانند اعلان های ایمیل جدید ، نگه داشتن UI در همگام سازی یا همگام سازی داده های برنامه در پس زمینه ، اولویت تحویل عادی را انتخاب کنید.

• اولویت بالا 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"
      }
    }
  }
}

برای جزئیات بیشتر در مورد پلتفرم در تنظیم اولویت پیام:

• مستندات APNS
• اولویت پیام (Android) را تنظیم و مدیریت کنید
• فوریت پیام فشار وب

موارد استفاده مهم زندگی

API های FCM برای هشدارهای اضطراری یا سایر فعالیتهای پرخطر طراحی نشده اند که در آن استفاده یا عدم موفقیت API ها می تواند منجر به مرگ ، آسیب شخصی یا آسیب های زیست محیطی شود (مانند عملکرد امکانات هسته ای ، کنترل ترافیک هوایی یا سیستم های پشتیبانی از زندگی). هر نوع استفاده صریحاً در بخش 4 ممنوع است. الف. 7 از شرایط خدمات. شما فقط مسئولیت مدیریت پیروی از برنامه خود با شرایط و هرگونه خسارت ناشی از عدم رعایت خود را بر عهده دارید. Google API ها را "همانطور که هست" فراهم می کند ، و این حق را برای خود محفوظ می دارد که به هر دلیلی و در هر زمان ، بدون مسئولیت یا تعهد دیگری در قبال شما یا کاربران خود ، API یا هر بخشی یا ویژگی یا دسترسی شما را قطع کند.

تنظیم طول عمر یک پیام

FCM معمولاً بلافاصله پس از ارسال پیام ها ارسال می شود. با این حال، این ممکن است همیشه امکان پذیر نباشد. به عنوان مثال ، اگر این سیستم عامل Android باشد ، دستگاه می تواند خاموش ، آفلاین یا در غیر این صورت در دسترس نباشد. یا FCM ممکن است عمداً پیام ها را به تأخیر بیندازد تا از مصرف برنامه بیش از حد و تأثیر منفی بر عمر باتری جلوگیری کند.

وقتی این اتفاق بیفتد ، FCM پیام را ذخیره می کند و به محض امکان امکان پذیر است. در حالی که این امر در بیشتر موارد خوب است ، برخی از برنامه ها وجود دارد که ممکن است یک پیام دیر هنگام نیز تحویل داده نشود. به عنوان مثال ، اگر پیام یک تماس تلفنی یا یک اعلان چت ویدیویی است ، فقط برای مدت زمان کوتاه قبل از خاتمه تماس معنی دار است. یا اگر پیام دعوت به یک رویداد است ، اگر پس از پایان این رویداد دریافت شود ، بی فایده است.

در Android و Web/JavaScript می توانید حداکثر طول عمر یک پیام را مشخص کنید. مقدار باید مدت زمان 0 تا 2419،200 ثانیه (28 روز) باشد و مطابق با حداکثر مدت زمانی باشد که FCM برای ارسال پیام برای ارسال پیام و تلاش برای ارسال پیام است. درخواست هایی که حاوی این قسمت به طور پیش فرض تا حداکثر مدت چهار هفته نیستند.

در اینجا برخی از کاربردهای ممکن برای این ویژگی آورده شده است:

• چت ویدیویی تماسهای ورودی
• وقایع دعوت منقضی شده
• رویدادهای تقویم

یکی دیگر از مزیت های مشخص کردن طول عمر یک پیام این است که FCM پیام قابل جمع شدن را به پیام هایی با مقدار زمان به زنده 0 ثانیه اعمال نمی کند. FCM بهترین تلاش برای ارسال پیام هایی را فراهم می کند که باید "اکنون یا هرگز" تحویل داده شوند. به خاطر داشته باشید که مقدار time_to_live 0 به معنای پیام هایی است که بلافاصله نمی توانند تحویل داده شوند. با این حال ، از آنجا که چنین پیامهایی هرگز ذخیره نمی شوند ، این بهترین تأخیر برای ارسال پیام های اعلان را فراهم می کند.

در اینجا نمونه ای از درخواستی است که شامل TTL است:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    },
    "apns":{
      "headers":{
        "apns-expiration":"1604750400"
      }
    },
    "android":{
      "ttl":"4500s"
    },
    "webpush":{
      "headers":{
        "TTL":"4500"
      }
    }
  }
}

طول عمر یک پیام

هنگامی که یک سرور برنامه پیامی را به FCM ارسال می کند و شناسه پیام را پس می گیرد ، به این معنی نیست که پیام قبلاً به دستگاه تحویل داده شده است. در عوض ، این بدان معنی است که برای تحویل پذیرفته شده است. آنچه بعد از پذیرش پیام برای پیام اتفاق می افتد بستگی به عوامل زیادی دارد.

در بهترین سناریو ، اگر دستگاه به FCM وصل شود ، صفحه نمایش روشن است و محدودیت های لرزان وجود ندارد ، پیام بلافاصله تحویل داده می شود.

اگر دستگاه متصل باشد اما در Doze ، یک پیام با اولویت پایین توسط FCM ذخیره می شود تا اینکه دستگاه از Doze خارج نشود. و این جایی است که پرچم collapse_key نقش ایفا می کند: اگر در حال حاضر پیامی با همان کلید فروپاشی (و نشانه ثبت نام) ذخیره شده و در انتظار تحویل وجود دارد ، پیام قدیمی دور ریخته می شود و پیام جدید جای خود را می گیرد (یعنی پیام قدیمی توسط نسخه جدید فرو می رود). با این حال ، اگر کلید فروپاشی تنظیم نشده باشد ، پیام های جدید و قدیمی برای تحویل آینده ذخیره می شوند.

اگر دستگاه به FCM وصل نشود ، پیام تا برقراری اتصال ذخیره می شود (دوباره با احترام به قوانین کلید فروپاشی). هنگامی که اتصال برقرار شد ، FCM تمام پیام های در حال تعلیق را به دستگاه تحویل می دهد. اگر دستگاه هرگز دوباره به هم وصل نشود (به عنوان مثال ، در صورت تنظیم مجدد کارخانه) ، پیام در نهایت از بین می رود و از ذخیره FCM دور می شود. زمان پیش فرض چهار هفته است ، مگر اینکه پرچم time_to_live تنظیم شود.

برای به دست آوردن بینش بیشتر در مورد تحویل پیام:

برای به دست آوردن بینش بیشتر در مورد تحویل پیام ها در سیستم عامل های Android یا Apple ، به داشبورد گزارش FCM مراجعه کنید ، که تعداد پیام های ارسال شده و باز شده در دستگاه های اپل و اندرویدی را به همراه داده های "برداشت" (اعلان های دیده شده توسط کاربران) برای برنامه های Android ثبت می کند.

برای دستگاه های Android با پیام کانال مستقیم فعال شده است ، اگر دستگاه بیش از یک ماه به FCM وصل نشده باشد ، FCM هنوز هم پیام را می پذیرد اما بلافاصله آن را دور می کند. اگر دستگاه ظرف چهار هفته از آخرین پیام داده ای که برای آن ارسال کرده اید متصل شود ، مشتری شما پاسخ به تماس ondeletedmessages () دریافت می کند. سپس برنامه می تواند با درخواست همگام سازی کامل از سرور برنامه ، وضعیت را به درستی اداره کند.

سرانجام ، هنگامی که FCM سعی در ارسال پیام به دستگاه کرد و برنامه حذف شد ، FCM آن پیام را بلافاصله دور می کند و نشانه ثبت نام را باطل می کند. تلاش های آینده برای ارسال پیام به آن دستگاه منجر به یک خطای NotRegistered شود.

پرتاب و سهمیه

هدف ما این است که همیشه هر پیام ارسال شده از طریق FCM را تحویل دهیم. با این حال ، ارائه هر پیام گاهی اوقات به یک تجربه کلی کاربر ضعیف منجر می شود. در موارد دیگر ، ما باید مرزهایی را فراهم کنیم تا اطمینان حاصل شود که FCM یک سرویس مقیاس پذیر برای همه فرستنده ها ارائه می دهد. انواع محدودیت ها و سهمیه های شرح داده شده در این بخش به ما کمک می کند تا این عوامل مهم را متعادل کنیم.

پیام پایین دست

HTTP V1 API سهمیه های هر پروژه ، در هر دقیقه برای پیام رسانی پایین دست را معرفی کرد. سهمیه پیش فرض پیام های 600K در دقیقه بیش از 99 ٪ از توسعه دهندگان FCM ضمن محافظت از ثبات سیستم و به حداقل رساندن تأثیر پروژه های سنبله.

الگوهای ترافیک تند و تیز می تواند منجر به سهمیه از خطاها شود. در یک سناریوی سهمیه بیش از حد ، این سیستم در خدمت کد وضعیت HTTP 429 (سهمیه_کسید) تا زمانی که سهمیه در دقیقه بعد دوباره پر شود. 429 پاسخ نیز ممکن است در شرایط اضافه بار برگردانده شود ، بنابراین شما به شدت تشویق می شوید که طبق توصیه های منتشر شده 429 را اداره کنید.

توجه داشته باشید که:

• سهمیه پایین دست پیام ها را اندازه گیری می کند ، نه درخواست.
• خطاهای مشتری (کد وضعیت HTTP 400-499) شمارش شده است (به استثنای 429s).
• سهمیه ها در هر دقیقه است ، اما این دقیقه ها به ساعت تراز نمی شوند.

سهمیه نظارت

شما می توانید سهمیه ، استفاده و خطاها را در کنسول Google Cloud مشاهده کنید:

1. به کنسول Google Cloud بروید
2. API و خدمات را انتخاب کنید
3. از لیست جدول ، API پیام رسانی Cloud Firebase را انتخاب کنید
4. سهمیه و محدودیت های سیستم را انتخاب کنید.

توجه: این نمودارها دقیقاً با چند دقیقه سهمیه تراز نشده اند ، به این معنی که ممکن است 429s ارائه شود که به نظر می رسد ترافیک زیر سهمیه است.

درخواست افزایش سهمیه

قبل از افزایش سهمیه ، اطمینان حاصل کنید که:

• استفاده شما به طور مرتب 80 ٪ سهمیه برای حداقل 5 دقیقه متوالی در روز است.
• شما نسبت به خطای مشتری 5 ٪ به خصوص در هنگام ترافیک اوج دارید.
• شما به بهترین روشها برای ارسال پیام در مقیاس پایبند هستید.

اگر این معیارها را رعایت کنید ، می توانید درخواست افزایش سهمیه را برای حداکثر +25 ٪ ارسال کنید و FCM هر تلاش عملی را برای تحقق درخواست انجام می دهد (هیچ افزایش نمی تواند تضمین شود).

اگر به دلیل راه اندازی قریب الوقوع یا رویداد موقت به سهمیه پیام رسانی پایین دست نیاز دارید ، حداقل 15 روز قبل از سهمیه خود درخواست کنید تا زمان کافی برای رسیدگی به درخواست اجازه دهید. برای درخواست های بزرگ (> پیام 18 متر در دقیقه) ، حداقل 30 روز اخطار لازم است. راه اندازی و درخواست های ویژه رویدادهای ویژه هنوز هم نسبت به خطای مشتری و نیازهای بهترین شیوه ها مشمول هستند.

همچنین به سؤالات متداول درباره سهمیه های FCM مراجعه کنید.

محدودیت پیام موضوع

نرخ افزودن/حذف اشتراک موضوع به 3000 QP در هر پروژه محدود می شود.

برای نرخ ارسال پیام ، به Fanout Throttling مراجعه کنید.

فندق

Fanout پیام فرایند ارسال پیام به چندین دستگاه است ، مانند زمانی که موضوعات و گروه ها را هدف قرار می دهید ، یا هنگام استفاده از آهنگساز Notifications برای هدف قرار دادن مخاطبان یا بخش های کاربر.

Fanout پیام فوری نیست و بنابراین گاهی اوقات شما به طور همزمان در حال پیشرفت هستید. ما تعداد هواداران پیام همزمان در هر پروژه را به 1000 محدود می کنیم. پس از آن ، ما ممکن است درخواست های اضافی را رد کنیم یا درخواست درخواست ها را تا زمانی که برخی از فن های در حال پیشرفت کامل شوند ، رد کنیم.

نرخ واقعی دستیابی قابل دستیابی تحت تأثیر تعداد پروژه هایی است که به طور همزمان درخواست می کنند. نرخ فن 10،000 QP در یک پروژه فردی غیر معمول نیست ، اما این تعداد ضمانتی نیست و نتیجه بار کل سیستم است. توجه به این نکته حائز اهمیت است که ظرفیت فن موجود در بین پروژه ها تقسیم می شود و نه در درخواست های فن. بنابراین ، اگر پروژه شما دارای دو فن در حال انجام باشد ، هر یک از طرفداران فقط نیمی از نرخ فن موجود را مشاهده می کنند. روش پیشنهادی برای به حداکثر رساندن سرعت فن خود این است که فقط یک بار در حال انجام یک طرفداری فعال باشد.

پیام قابل جمع شدن

همانطور که در بالا توضیح داده شد ، پیام های قابل جمع شدن اعلان های عاری از محتوا هستند که برای سقوط در بالای یکدیگر طراحی شده اند. در صورتی که یک توسعه دهنده بیش از حد همان پیام را به یک برنامه تکرار کند ، ما پیام های (دریچه گاز) را به تأخیر می اندازیم تا تأثیر باتری کاربر را کاهش دهد.

به عنوان مثال ، اگر تعداد زیادی درخواست همگام سازی ایمیل جدید را به یک دستگاه واحد ارسال کنید ، ممکن است درخواست همگام سازی ایمیل بعدی را چند دقیقه به تأخیر بیندازیم تا دستگاه بتواند با نرخ متوسط ​​پایین همگام سازی شود. این پرتاب به طور جدی برای محدود کردن تأثیر باتری که توسط کاربر تجربه شده است انجام می شود.

اگر مورد استفاده شما به الگوهای ارسال پشت سر هم نیاز دارد ، پیام های غیر قابل جمع شدن ممکن است انتخاب مناسبی باشد. برای چنین پیام هایی ، برای کاهش هزینه باتری ، حتماً محتوا را در چنین پیام هایی قرار دهید.

ما پیام های قابل جمع شدن را برای پشت سر گذاشتن 20 پیام در هر برنامه در هر دستگاه محدود می کنیم ، با استفاده از 1 پیام هر 3 دقیقه.

سرور XMPP

ما نرخ اتصال را می توانیم به سرورهای FCM XMPP به 400 اتصال در هر دقیقه در هر پروژه محدود کنیم. این نباید مسئله ای برای تحویل پیام باشد ، اما برای اطمینان از ثبات سیستم مهم است. برای هر پروژه ، FCM اجازه می دهد 2500 اتصال به طور موازی.

برای پیام رسانی بالادست با XMPP ، FCM پیام های بالادست را با 1500،000/دقیقه در هر پروژه محدود می کند تا از بارگذاری بیش از حد سرورهای مقصد بالادست جلوگیری شود.

ما پیام های بالادست را در هر دستگاه در 1000 دقیقه/دقیقه محدود می کنیم تا در برابر تخلیه باتری از رفتار بد برنامه محافظت کنیم.

حداکثر نرخ پیام به یک دستگاه واحد

برای Android می توانید حداکثر 240 پیام در دقیقه و 5000 پیام در ساعت را به یک دستگاه واحد ارسال کنید. این آستانه بالا به معنای اجازه دادن به انفجارهای کوتاه مدت از ترافیک است ، مانند زمانی که کاربران به سرعت در حال تعامل با چت هستند. این حد از ارسال خطاها در ارسال منطق از تخلیه سهواً باتری روی یک دستگاه جلوگیری می کند.

برای iOS ، هنگامی که نرخ بیش از حد APNS باشد ، خطایی را برمی گردانیم.

درگاه های FCM و فایروال شما

اگر سازمان شما دارای فایروال برای محدود کردن ترافیک به اینترنت یا از طریق اینترنت است ، باید آن را پیکربندی کنید تا دستگاه های تلفن همراه بتوانند با FCM ارتباط برقرار کنند تا دستگاه های موجود در شبکه شما پیام دریافت کنند. FCM به طور معمول از پورت 5228 استفاده می کند ، اما گاهی اوقات از 443 ، 5229 و 5230 استفاده می کند.

برای دستگاه های متصل به شبکه شما ، FCM IP های خاصی را ارائه نمی دهد زیرا دامنه IP ما بیش از حد تغییر می کند و قوانین فایروال شما می تواند از تاریخ خارج شود و بر تجربه کاربران شما تأثیر بگذارد. در حالت ایده آل ، درگاه های AllowList 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
• دستگاه-provisioning.googleapis.com
• FirebaseInstallations.googleapis.com

ترجمه آدرس شبکه و/یا فایروال بازرسی بسته بندی شده:

اگر شبکه شما ترجمه آدرس شبکه (NAT) یا بازرسی بسته بندی شده (SPI) را پیاده سازی می کند ، یک زمان 30 دقیقه یا بزرگتر را برای اتصالات ما از طریق پورت های 5228-5230 پیاده سازی کنید. این امر ما را قادر می سازد ضمن کاهش مصرف باتری دستگاه های تلفن همراه کاربران ، اتصال قابل اعتماد را ارائه دهیم.

تعامل VPN و قابلیت عبور

Firebase Cloud Messaging اقدامات مختلفی را انجام می دهد تا اطمینان حاصل شود که اتصال پیام رسانی از تلفن به سرور قابل اعتماد و در هر زمان ممکن است. استفاده از VPN این تلاش را پیچیده می کند.

VPNS اطلاعات اساسی را که FCM برای تنظیم اتصال خود برای به حداکثر رساندن قابلیت اطمینان و عمر باتری نیاز دارد ، ماسک می کند. در بعضی موارد ، VPN ها به طور فعال اتصالات طولانی مدت را می شکنند که منجر به تجربه بد کاربر به دلیل پیام های از دست رفته یا تأخیر یا هزینه باتری بالا می شود. هنگامی که VPN پیکربندی شده است تا به ما اجازه دهد این کار را انجام دهیم ، ما VPN را با استفاده از یک اتصال رمزگذاری شده (از طریق شبکه پایه WiFi یا LTE) دور می زنیم تا از یک تجربه مناسب و باتری مطمئن اطمینان حاصل کنیم. استفاده FCM از VPN های قابل تحمل مختص کانال اعلان فشار FCM است. سایر ترافیک FCM ، مانند ترافیک ثبت نام ، در صورت فعال بودن از VPN استفاده می کند. هنگامی که اتصال FCM از VPN عبور می کند ، مزایای اضافی را که VPN ممکن است ارائه دهد ، مانند نقاب IP از دست می دهد.

VPN های مختلف روش های مختلفی برای کنترل اینکه آیا می توان آن را دور زد یا خیر ، خواهند داشت. برای دستورالعمل با مستندات مربوط به VPN خاص خود مشورت کنید.

اگر VPN پیکربندی نشده باشد ، قابل عبور باشد ، Firebase Cloud Messaging برای اتصال به سرور از شبکه VPN استفاده می کند. این ممکن است به دوره هایی منجر شود که پیام ها به تأخیر بیفتند و ممکن است منجر به استفاده بیشتر باتری شود زیرا Cloud Messaging برای حفظ اتصال از طریق اتصال VPN کار می کند.

اعتبارنامه

بسته به اینکه FCM از ویژگی های شما استفاده می کنید ، ممکن است به اعتبار زیر از پروژه Firebase خود نیاز داشته باشید:

Firebase Cloud Messaging ( FCM ) طیف گسترده ای از گزینه ها و قابلیت های پیام رسانی را ارائه می دهد. اطلاعات موجود در این صفحه برای کمک به شما در درک انواع مختلف پیام های FCM و آنچه می توانید با آنها انجام دهید ، در نظر گرفته شده است.

انواع پیام

با FCM می توانید دو نوع پیام را به مشتری ارسال کنید:

• پیام های اعلان ، که گاهی اوقات به عنوان "پیام های نمایش" فکر می شود. اینها توسط FCM SDK به طور خودکار انجام می شود.
• پیام های داده ، که توسط برنامه مشتری اداره می شوند.

پیام های اعلان شامل مجموعه ای از کلیدهای از پیش تعریف شده قابل مشاهده توسط کاربر است. در مقابل ، پیام های داده فقط شامل جفت های ارزش کلید سفارشی تعریف شده توسط کاربر هستند. پیام‌های اعلان می‌توانند حاوی یک بار داده اختیاری باشند. حداکثر بار برای هر دو نوع پیام 4096 بایت است ، به جز هنگام ارسال پیام از کنسول Firebase ، که محدودیت 1000 کاراکتر را اعمال می کند.

هنگامی که می خواهید FCM SDK هنگام اجرای برنامه شما در پس زمینه ، از پیام های اعلان استفاده کنید ، هنگام نمایش برنامه شما به طور خودکار یک اعلان را کنترل کند. هنگامی که می خواهید پیام ها را با کد برنامه مشتری خود پردازش کنید ، از پیام های داده استفاده کنید.

FCM می تواند یک پیام اعلان از جمله بار داده اختیاری را ارسال کند. در چنین مواردی ، FCM با نشان دادن بار اعلان ، و برنامه مشتری بار داده را کنترل می کند.

پیام های اطلاع رسانی

برای آزمایش یا برای بازاریابی و تعامل مجدد کاربر ، می توانید پیام های اعلان را با استفاده از کنسول Firebase ارسال کنید . کنسول Firebase تست A/B مبتنی بر تجزیه و تحلیل را برای کمک به شما در اصلاح و بهبود پیام های بازاریابی فراهم می کند.

برای ارسال پیام های اعلان با استفاده از Admin SDK یا پروتکل های FCM ، کلید notification را با مجموعه از پیش تعریف شده لازم از گزینه های ارزش کلید برای قسمت قابل مشاهده کاربر از پیام اعلان تنظیم کنید. به عنوان مثال ، در اینجا یک پیام اعلان با فرمت JSON در یک برنامه IM وجود دارد. کاربر می تواند انتظار داشته باشد که با عنوان "پرتغال در مقابل دانمارک" و متن "Great Match!" در دستگاه:

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

پیام های اعلان هنگامی که برنامه در پس زمینه است به سینی اعلان تحویل داده می شود. برای برنامه های موجود در پیش زمینه ، پیام ها توسط یک عملکرد پاسخ به تماس انجام می شوند.

برای لیست کامل کلیدهای از پیش تعریف شده در دسترس برای پیام های اعلان ساختمان ، به اسناد مرجع اطلاع رسانی پروتکل HTTP V1 مراجعه کنید.

پیام های داده

کلید مناسب را با جفت های ارزش کلید سفارشی خود تنظیم کنید تا یک بار داده را به برنامه مشتری ارسال کنید.

به عنوان مثال ، در اینجا یک پیام با فرمت JSON در همان برنامه IM همانطور که در بالا وجود دارد ، که در آن اطلاعات در کلید data مشترک محصور شده است و انتظار می رود برنامه مشتری محتوا را تفسیر کند:

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

مثال بالا استفاده از قسمت data سطح بالا یا مشترک را نشان می دهد که توسط مشتری در کلیه سیستم عامل هایی که پیام را دریافت می کنند ، تفسیر می شود. در هر سیستم عامل ، برنامه مشتری بار داده را در یک عملکرد پاسخ به تماس دریافت می کند.

رمزگذاری برای پیام های داده

لایه حمل و نقل Android (به معماری FCM مراجعه کنید) از رمزگذاری نقطه به نقطه استفاده می کند. بسته به نیاز شما ، ممکن است تصمیم بگیرید رمزگذاری پایان به پایان را به پیام های داده اضافه کنید. FCM یک راه حل پایان به پایان ارائه نمی دهد. با این حال ، راه حل های خارجی مانند مویرگی یا DTL وجود دارد.

پیام های اعلان با بار داده اختیاری

هر دو از نظر برنامه ای یا از طریق کنسول 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 ، که فقط توسط نمونه های برنامه در حال اجرا بر روی پلت فرم مشخص شده تفسیر می شوند.

بلوک های خاص پلتفرم به شما انعطاف پذیری می دهد تا پیام ها را برای سیستم عامل های مختلف شخصی سازی کنید تا اطمینان حاصل شود که در هنگام دریافت به درستی از آنها برخورد می شوند. BACEND FCM تمام پارامترهای مشخص شده را در نظر می گیرد و پیام را برای هر سیستم عامل سفارشی می کند.

چه زمانی از زمینه های مشترک استفاده کنید

در صورتی که از زمینه های مشترک استفاده کنید:

• هدف قرار دادن نمونه های برنامه در همه سیستم عامل ها - اپل ، اندروید و وب
• ارسال پیام به موضوعات

همه نمونه های برنامه ، صرف نظر از پلتفرم ، می توانند زمینه های مشترک زیر را تفسیر کنند:

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

چه زمانی از زمینه های خاص پلت فرم استفاده کنید

وقتی می خواهید از فیلدهای خاص پلتفرم استفاده کنید:

• ارسال قسمت ها فقط به سیستم عامل های خاص
• علاوه بر زمینه های مشترک ، زمینه های خاص سیستم عامل را ارسال کنید

هر زمان که می خواهید فقط به سیستم عامل های خاص مقادیر ارسال کنید ، از زمینه های مشترک استفاده نکنید . از زمینه های خاص پلتفرم استفاده کنید. به عنوان مثال ، برای ارسال یک اعلان فقط به سیستم عامل های اپل و وب اما نه به Android ، باید از دو مجموعه جداگانه از فیلد ، یکی برای اپل و دیگری برای وب استفاده کنید.

When you are sending messages with specific delivery options , use platform-specific fields to set them. You can specify different values per platform if you want. However, even when you want to set essentially the same value across platforms, you must use platform-specific fields. This is because each platform may interpret the value slightly differently—for example, time-to-live is set on Android as an expiration time in seconds, while on Apple it is set as an expiration date .

Example: notification message with platform-specific delivery options

The following v1 send request sends a common notification title and content to all platforms, but also sends some platform-specific overrides. Specifically, the request:

• sets a long time-to-live for Android and Web platforms, while setting the APNs (Apple platforms) message priority to a low setting
• sets the appropriate keys to define the result of a user tap on the notification on Android and Apple — click_action , and category , 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 .

گزینه های تحویل

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.

از کدوم استفاده کنم؟

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.

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.

• اولویت بالا 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:

• APNs documentation
• Set and manage message priority (Android)
• Web push message urgency

Life critical use cases

The FCM APIs are not designed for emergency alerts or other high-risk activities where the use or failure of the APIs could result in death, personal injury, or environmental damage (such as the operation of nuclear facilities, air traffic control, or life support systems). Any such use is expressly prohibited under Section 4. a. 7 of the Terms of Service. You are solely responsible for managing your app's compliance with the Terms, and any damages resulting from your noncompliance. Google provides the APIs "as is," and reserves the right to discontinue the APIs or any portion or feature or your access thereto, for any reason and at any time, without liability or other obligation to you or your users.

Setting the lifespan of a message

FCM usually delivers messages immediately after they are sent. با این حال، این ممکن است همیشه امکان پذیر نباشد. 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
• رویدادهای تقویم

Another advantage of specifying the lifespan of a message is that FCM doesn't apply collapsible message throttling to messages with a time-to-live value of 0 seconds. FCM provides best effort handling of 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 quotas

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. The types of limits and quotas described in this section help us balance these important factors.

Downstream message throttling

The HTTP v1 API introduced per-project, per-minute quotas for downstream messaging. The default quota of 600k messages per minute covers over 99% of FCM developers while protecting the stability of the system and minimizing the impact of spiky projects.

Spiky traffic patterns can result in quota exceeded errors. In an over quota scenario, the system serves HTTP status code 429 (QUOTA_EXCEEDED) until the quota is refilled in the following minute. 429 responses may also be returned in overload situations, so you are strongly encouraged to handle 429s according to published recommendations .

توجه داشته باشید که:

• The downstream quota measures messages, not requests.
• Client errors (HTTP status code 400-499) are counted (excluding 429s).
• Quotas are per-minute, but these minutes are not aligned to the clock.

Monitoring quota

You can view quota, usage, and errors on the Google Cloud Console:

1. به کنسول Google Cloud بروید
2. Select APIs & services
3. From the table list, select Firebase Cloud Messaging API
4. Select QUOTA & SYSTEM LIMITS .

NOTE: These graphs are not precisely time aligned with quota minutes, meaning 429s may be served when traffic appears to be below quota.

درخواست افزایش سهمیه

Before requesting a quota increase, ensure that:

• Your usage is regularly ≥ 80% of quota for at least 5 consecutive minutes per day.
• You have < 5% client error ratio, especially during peak traffic.
• You adhere to the best practices for sending messages at scale .

If you meet these criteria, you can submit a quota increase request for up to +25% and FCM will make every practical effort to fulfill the request (no increase can be guaranteed).

If you need more downstream messaging quota due to an impending launch or temporary event, request your quota at least 15 days in advance to allow sufficient time to handle the request. For large requests (>18M messages per minute), at least 30 days of notice is required. Launches and special event requests are still subject to the client error ratio and best practices requirements.

See also the FAQ about FCM quotas .

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.

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 the system. For each project, FCM allows 2500 connections in parallel.

For upstream messaging with XMPP, FCM limits 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.

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.

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.

VPN interactions and bypassability

Firebase Cloud Messaging takes various steps to ensure that the push messaging connection from the phone to the server is reliable and available as often as possible. The use of a VPN complicates this effort.

VPNs mask the underlying information that FCM needs to tune its connection to maximize reliability & battery life. In some cases VPNs actively break long lived connections resulting in a bad user experience due to missed or delayed messages or a high battery cost. When the VPN is configured to allow us to do so, we bypass the VPN using an encrypted connection (over the base network wifi or LTE) so as to ensure a reliable, battery friendly experience. FCM 's usage of bypassable VPNs is specific to the FCM Push Notification channel. Other FCM traffic, such as registration traffic, uses the VPN if it is active. When the FCM connection bypasses the VPN it loses additional benefits the VPN may provide, such as IP masking.

Different VPNs will have different methods for controlling whether or not it can be bypassed. Consult the documentation for your specific VPN for instructions.

If the VPN is not configured to be bypassable then Firebase Cloud Messaging will use the VPN network in order to connect to the server. This may result in periods of time where messages are delayed and may result in more battery usage as Cloud Messaging works to maintain the connection over the VPN connection.

اعتبارنامه

Depending on which FCM features you implement, you may need the following credentials from your Firebase project:

Firebase Cloud Messaging ( FCM ) offers a broad range of messaging options and capabilities. The information in this page is intended to help you understand the different types of FCM messages and what you can do with them.

انواع پیام

With FCM , you can send two types of messages to clients:

• Notification messages, sometimes thought of as "display messages." These are handled by the FCM SDK automatically.
• Data messages, which are handled by the client app.

پیام های اعلان شامل مجموعه ای از کلیدهای از پیش تعریف شده قابل مشاهده توسط کاربر است. Data messages, by contrast, contain only your user-defined custom key-value pairs. پیام‌های اعلان می‌توانند حاوی یک بار داده اختیاری باشند. Maximum payload for both message types is 4096 bytes, except when sending messages from the Firebase console, which enforces a 1000 character limit.

Use notification messages when you want the FCM SDK to handle displaying a notification automatically when your app is running in the background. Use data messages when you want to process the messages with your own client app code.

FCM can send a notification message including an optional data payload. In such cases, FCM handles displaying the notification payload, and the client app handles the data payload.

پیام های اطلاع رسانی

For testing or for marketing and user re-engagement, you can send notification messages using the Firebase console . The Firebase console provides analytics-based A/B testing to help you refine and improve marketing messages.

To programmatically send notification messages using the Admin SDK or the FCM protocols, set the notification key with the necessary predefined set of key-value options for the user-visible part of the notification message. For example, here is a JSON-formatted notification message in an IM app. The user can expect to see a message with the title "Portugal vs. Denmark" and the text "great match!" on the device:

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

Notification messages are delivered to the notification tray when the app is in the background. For apps in the foreground, messages are handled by a callback function.

See the HTTP v1 Protocol notification object reference documentation for the full list of predefined keys available for building notification messages.

پیام های داده

Set the appropriate key with your custom key-value pairs to send a data payload to the client app.

For example, here is a JSON-formatted message in the same IM app as above, where the information is encapsulated in the common data key and the client app is expected to interpret the content:

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

The above example shows usage of the top-level, or common data field, which is interpreted by clients on all platforms that receive the message. On each platform, the client app receives the data payload in a callback function.

Encryption for data messages

The Android Transport Layer (see FCM architecture ) uses point-to-point encryption. Depending on your needs, you may decide to add end-to-end encryption to data messages. FCM does not provide an end-to-end solution. However, there are external solutions available such as Capillary or DTLS .

Notification messages with optional data payload

Both programmatically or via the Firebase console, you can send notification messages that contain an optional payload of custom key-value pairs. In the Notifications composer , use the Custom data fields in Advanced options .

App behavior when receiving messages that include both notification and data payloads depends on whether the app is in the background or the foreground—essentially, whether or not it is active at the time of receipt.

• When in the background , apps receive the notification payload in the notification tray, and only handle the data payload when the user taps on the notification.
• When in the foreground , your app receives a message object with both payloads available.

Here is a JSON-formatted message containing both the notification key and the data key:

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

Customizing a message across platforms

The Firebase Admin SDK and the FCM v1 HTTP protocol both allow your message requests to set all fields available in the message object. این شامل:

• a common set of fields to be interpreted by all app instances that receive the message.
• platform-specific sets of fields, such as AndroidConfig and WebpushConfig , interpreted only by app instances running on the specified platform.

Platform-specific blocks give you flexibility to customize messages for different platforms to ensure that they are handled correctly when received. The FCM backend will take all specified parameters into account and customize the message for each platform.

When to use common fields

Use common fields when you're:

• Targeting app instances on all platforms — Apple, Android, and web
• Sending messages to topics

All app instances, regardless of platform, can interpret the following common fields:

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

When to use platform-specific fields

Use platform-specific fields when you want to:

• Send fields only to particular platforms
• Send platform-specific fields in addition to the common fields

Whenever you want to send values only to particular platforms, don't use common fields; use platform-specific fields. For example, to send a notification only to Apple platforms and web but not to Android, you must use two separate sets of fields, one for Apple and one for web.

When you are sending messages with specific delivery options , use platform-specific fields to set them. You can specify different values per platform if you want. However, even when you want to set essentially the same value across platforms, you must use platform-specific fields. This is because each platform may interpret the value slightly differently—for example, time-to-live is set on Android as an expiration time in seconds, while on Apple it is set as an expiration date .

Example: notification message with platform-specific delivery options

The following v1 send request sends a common notification title and content to all platforms, but also sends some platform-specific overrides. Specifically, the request:

• sets a long time-to-live for Android and Web platforms, while setting the APNs (Apple platforms) message priority to a low setting
• sets the appropriate keys to define the result of a user tap on the notification on Android and Apple — click_action , and category , 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 .

گزینه های تحویل

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.

از کدوم استفاده کنم؟

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.

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.

• اولویت بالا 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:

• APNs documentation
• Set and manage message priority (Android)
• Web push message urgency

Life critical use cases

The FCM APIs are not designed for emergency alerts or other high-risk activities where the use or failure of the APIs could result in death, personal injury, or environmental damage (such as the operation of nuclear facilities, air traffic control, or life support systems). Any such use is expressly prohibited under Section 4. a. 7 of the Terms of Service. You are solely responsible for managing your app's compliance with the Terms, and any damages resulting from your noncompliance. Google provides the APIs "as is," and reserves the right to discontinue the APIs or any portion or feature or your access thereto, for any reason and at any time, without liability or other obligation to you or your users.

Setting the lifespan of a message

FCM usually delivers messages immediately after they are sent. با این حال، این ممکن است همیشه امکان پذیر نباشد. 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
• رویدادهای تقویم

Another advantage of specifying the lifespan of a message is that FCM doesn't apply collapsible message throttling to messages with a time-to-live value of 0 seconds. FCM provides best effort handling of 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 quotas

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. The types of limits and quotas described in this section help us balance these important factors.

Downstream message throttling

The HTTP v1 API introduced per-project, per-minute quotas for downstream messaging. The default quota of 600k messages per minute covers over 99% of FCM developers while protecting the stability of the system and minimizing the impact of spiky projects.

Spiky traffic patterns can result in quota exceeded errors. In an over quota scenario, the system serves HTTP status code 429 (QUOTA_EXCEEDED) until the quota is refilled in the following minute. 429 responses may also be returned in overload situations, so you are strongly encouraged to handle 429s according to published recommendations .

توجه داشته باشید که:

• The downstream quota measures messages, not requests.
• Client errors (HTTP status code 400-499) are counted (excluding 429s).
• Quotas are per-minute, but these minutes are not aligned to the clock.

Monitoring quota

You can view quota, usage, and errors on the Google Cloud Console:

1. به کنسول Google Cloud بروید
2. Select APIs & services
3. From the table list, select Firebase Cloud Messaging API
4. Select QUOTA & SYSTEM LIMITS .

NOTE: These graphs are not precisely time aligned with quota minutes, meaning 429s may be served when traffic appears to be below quota.

درخواست افزایش سهمیه

Before requesting a quota increase, ensure that:

• Your usage is regularly ≥ 80% of quota for at least 5 consecutive minutes per day.
• You have < 5% client error ratio, especially during peak traffic.
• You adhere to the best practices for sending messages at scale .

If you meet these criteria, you can submit a quota increase request for up to +25% and FCM will make every practical effort to fulfill the request (no increase can be guaranteed).

If you need more downstream messaging quota due to an impending launch or temporary event, request your quota at least 15 days in advance to allow sufficient time to handle the request. For large requests (>18M messages per minute), at least 30 days of notice is required. Launches and special event requests are still subject to the client error ratio and best practices requirements.

See also the FAQ about FCM quotas .

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.

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 the system. For each project, FCM allows 2500 connections in parallel.

For upstream messaging with XMPP, FCM limits 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.

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.

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.

VPN interactions and bypassability

Firebase Cloud Messaging takes various steps to ensure that the push messaging connection from the phone to the server is reliable and available as often as possible. The use of a VPN complicates this effort.

VPNs mask the underlying information that FCM needs to tune its connection to maximize reliability & battery life. In some cases VPNs actively break long lived connections resulting in a bad user experience due to missed or delayed messages or a high battery cost. When the VPN is configured to allow us to do so, we bypass the VPN using an encrypted connection (over the base network wifi or LTE) so as to ensure a reliable, battery friendly experience. FCM 's usage of bypassable VPNs is specific to the FCM Push Notification channel. Other FCM traffic, such as registration traffic, uses the VPN if it is active. When the FCM connection bypasses the VPN it loses additional benefits the VPN may provide, such as IP masking.

Different VPNs will have different methods for controlling whether or not it can be bypassed. Consult the documentation for your specific VPN for instructions.

If the VPN is not configured to be bypassable then Firebase Cloud Messaging will use the VPN network in order to connect to the server. This may result in periods of time where messages are delayed and may result in more battery usage as Cloud Messaging works to maintain the connection over the VPN connection.

اعتبارنامه

Depending on which FCM features you implement, you may need the following credentials from your Firebase project: