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

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

انواع پیام

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

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

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

	از سناریو استفاده کنید	نحوه ارسال
پیام اعلان	FCM SDK زمانی که برنامه در پس‌زمینه اجرا می‌شود، پیام را از طرف برنامه مشتری به دستگاه‌های کاربر نهایی نمایش می‌دهد. در غیر این صورت، اگر برنامه هنگام دریافت اعلان در پیش زمینه اجرا شود، کد برنامه رفتار را تعیین می کند. پیام‌های اعلان دارای مجموعه‌ای از کلیدهای قابل مشاهده برای کاربر و یک بار داده اختیاری از جفت‌های کلید-مقدار سفارشی هستند.	در یک محیط قابل اعتماد مانند Cloud Functions یا سرور برنامه خود، از Admin SDK یا HTTP v1 API استفاده کنید. کلید notification را تنظیم کنید. ممکن است بار داده اختیاری داشته باشد. همیشه تاشو چند نمونه از اعلان‌های نمایش و ارسال بارهای درخواستی را ببینید. از آهنگساز اعلان ها استفاده کنید: متن پیام، عنوان و غیره را وارد کرده و ارسال کنید. با ارائه داده های سفارشی، بار داده اختیاری را اضافه کنید.
پیام داده	برنامه مشتری مسئول پردازش پیام های داده است. پیام های داده فقط دارای جفت های سفارشی کلید-مقدار بدون نام کلید رزرو شده هستند (به زیر مراجعه کنید).	در یک محیط قابل اعتماد مانند Cloud Functions یا سرور برنامه خود، از Admin SDK یا پروتکل‌های سرور FCM استفاده کنید. در درخواست ارسال، کلید data را تنظیم کنید.

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

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

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

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

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

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

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

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

پیام های داده

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

اطمینان حاصل کنید که از هیچ کلمه رزرو شده در جفت های کلید-مقدار سفارشی خود استفاده نمی کنید. کلمات رزرو شده عبارتند از "from"، "notification"، "message_type"، یا هر کلمه ای که با "google" یا "gcm" شروع می شود.

به عنوان مثال، در اینجا یک پیام با فرمت 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 پشتیبانی می‌شود. برای جزئیات، به توضیحات در این بخش و مستندات مرجع مرتبط مراجعه کنید.

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

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

FCM سفارش تحویل را تضمین نمی کند.

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

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

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

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

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

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

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

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

	از سناریو استفاده کنید	نحوه ارسال
غیر قابل جمع شدن	هر پیامی برای برنامه مشتری مهم است و باید تحویل داده شود.	به جز پیام های اعلان، همه پیام ها به طور پیش فرض غیرقابل جمع شدن هستند.
تاشو	هنگامی که یک پیام جدیدتر وجود دارد که یک پیام قدیمی و مرتبط با برنامه مشتری را بی ربط نشان می دهد، FCM پیام قدیمی را جایگزین می کند. برای مثال: پیام‌هایی که برای شروع همگام‌سازی داده‌ها از سرور استفاده می‌شوند، یا پیام‌های اعلان قدیمی.	پارامتر مناسب را در درخواست پیام خود تنظیم کنید: collapseKey در اندروید apns-collapse-id در اپل Topic در وب collapse_key در پروتکل‌های قدیمی (همه پلتفرم‌ها)

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

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

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

• اولویت بالا FCM سعی می‌کند پیام‌های با اولویت بالا را فوراً ارسال کند، حتی اگر دستگاه در حالت Doze باشد. پیام های با اولویت بالا برای محتوای حساس به زمان و قابل مشاهده توسط کاربر هستند.

هنگام ارسال پیام های داده به دستگاه های اپل، اولویت باید روی 5 یا اولویت عادی تنظیم شود. پیام‌هایی که با اولویت بالا ارسال می‌شوند توسط بخش پشتیبان FCM با خطای INVALID_ARGUMENT رد می‌شوند.

در اینجا نمونه‌ای از یک پیام اولویت معمولی است که از طریق پروتکل FCM HTTP v1 ارسال می‌شود تا به مشترک مجله اطلاع دهد که محتوای جدید برای دانلود در دسترس است:

{
  "message":{
    "topic":"subscriber-updates",
    "notification":{
      "body" : "This week's edition is now available.",
      "title" : "NewsMagazine.com",
    },
    "data" : {
      "volume" : "3.21.15",
      "contents" : "http://www.news-magazine.com/world-week/21659772"
    },
    "android":{
      "priority":"normal"
    },
    "apns":{
      "headers":{
        "apns-priority":"5"
      }
    },
    "webpush": {
      "headers": {
        "Urgency": "high"
      }
    }
  }
}

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

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

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

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 با پیام‌رسانی مستقیم کانال فعال، اگر دستگاه بیش از یک ماه به 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

احتیاط: ارسال پیام‌ها (از جمله پیام‌های بالادست) با APIهای قدیمی FCM XMPP و HTTP در 20 ژوئن 2023 منسوخ شد و از ژوئن 2024 حذف خواهد شد . اگر از APIهای ارسال FCM قدیمی استفاده می‌کنید، اکیداً توصیه می‌کنیم به API HTTP v1 مهاجرت کنید یا از Admin SDK برای ایجاد درخواست‌های ارسال استفاده کنید.

ما نرخ اتصال شما به سرورهای 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 اعمال کنید. این ما را قادر می‌سازد تا ضمن کاهش مصرف باتری دستگاه‌های تلفن همراه کاربران، اتصال قابل اعتمادی را ارائه دهیم.

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

تعاملات 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 شما، که در درخواست ها به نقطه پایانی FCM v1 HTTP استفاده می شود. این مقدار در قسمت تنظیمات کنسول Firebase موجود است.
رمز ثبت نام	یک رشته رمز منحصر به فرد که هر نمونه برنامه مشتری را شناسایی می کند. رمز ثبت نام برای پیام‌رسانی یک دستگاه و گروه دستگاه لازم است. توجه داشته باشید که نشانه های ثبت نام باید مخفی نگه داشته شوند.
شناسه فرستنده	یک مقدار عددی منحصربه‌فرد که هنگام ایجاد پروژه Firebase خود ایجاد می‌شود و در برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase موجود است. شناسه فرستنده برای شناسایی هر فرستنده ای که می تواند به برنامه مشتری پیام ارسال کند، استفاده می شود.
نشانه دسترسی	یک توکن کوتاه مدت OAuth 2.0 که درخواست ها را به API HTTP v1 مجاز می کند. این نشانه با یک حساب خدماتی مرتبط است که به پروژه Firebase شما تعلق دارد. برای ایجاد و چرخاندن نشانه‌های دسترسی، مراحل توضیح داده شده در مجوز ارسال درخواست‌ها را دنبال کنید.
کلید سرور (برای پروتکل‌های قدیمی **منسوخ شده**)	یک کلید سرور که به سرور برنامه شما اجازه دسترسی به خدمات Google را می‌دهد، از جمله ارسال پیام از طریق پروتکل‌های قدیمی Firebase Cloud Messaging . مهم: کلید سرور را در هیچ کجای کد مشتری خود وارد نکنید. همچنین، مطمئن شوید که فقط از کلیدهای سرور برای مجوز دادن به سرور برنامه خود استفاده می کنید. کلیدهای اندروید، پلتفرم اپل و مرورگر توسط FCM رد می شوند.