این صفحه راهنمایی‌های عیب‌یابی و پاسخ به پرسش‌های متداول درباره Cloud Messaging را ارائه می‌دهد.
تفاوت بین «سازنده اعلان‌ها» و FCM چیست؟
Firebase Cloud Messaging مجموعه کاملی از قابلیت‌های پیام‌رسانی را ازطریق کیت توسعه نرم‌افزار مشتری و پروتکل سرور HTTP ارائه می‌دهد. برای استقرار با الزامات پیام‌رسانی پیچیده‌تر، FCM انتخاب مناسبی است.
«سازنده اعلان‌ها» راهکار پیام‌رسانی سبک و بدون سروری است که روی Firebase Cloud Messaging ساخته شده است. با کنسول گرافیکی کاربرپسند و نیاز کمتر به کدنویسی، «سازنده اعلان‌ها» به کاربران امکان می‌دهد برای تعامل مجدد و حفظ کاربران، تقویت رشد برنامه، و پشتیبانی از پویش‌های بازاریابی پیام ارسال کنند.
| قابلیت‌ها | سازنده اعلان‌ها | Cloud Messaging | |
|---|---|---|---|
| هدف | تک‌دستگاه | ||
| مشتریان مشترک‌شده در موضوعات (مثلاً آب‌وهوا) | |||
| کارخواه‌ها در بخش کاربر ازپیش تعریف‌شده (برنامه، نسخه، زبان) | |||
| مشتریان در مخاطبان Analytics مشخص‌شده | |||
| مشتریان در گروه‌های دستگاه | |||
| بالادست از کارخواه به سرور | |||
| نوع پیام | اعلان‌های تا ۲ کیلوبایت | ||
| پیام‌های داده‌ای تا ۴ کیلوبایت | |||
| تحویل | فوری | ||
| زمان محلی دستگاه کارخواه در آینده | |||
| Analytics | مجموعه تجزیه‌وتحلیل «اعلان‌های» داخلی و تجزیه‌وتحلیل قیفی |
آیا برای استفاده از FCM باید از سرویس‌های دیگر Firebase استفاده کنم؟
می‌توانید از Firebase Cloud Messaging به‌عنوان مؤلفه‌ای مستقل، بدون استفاده از سرویس‌های دیگر Firebase، استفاده کنید.
چرا دستگاه‌های هدف من ظاهراً پیام‌ها را دریافت نمی‌کنند؟
وقتی به‌نظر می‌رسد دستگاه‌ها پیام‌ها را با موفقیت دریافت نکرده‌اند، ابتدا این دو علت احتمالی را بررسی کنید:
مدیریت پیام پیش‌زمینه برای پیام‌های اعلان. برنامه‌های کارخواه باید منطق مدیریت پیام را اضافه کنند تا پیام‌های اعلان را وقتی برنامه در پیش‌زمینه دستگاه است مدیریت کنند. جزئیات مربوط به iOS و Android را ببینید.
محدودیت‌های دیوار آتش شبکه. اگر سازمانتان دیوار آتشی دارد که ترافیک به یا از اینترنت را محدود می‌کند، باید آن را پیکربندی کنید تا اتصال با FCM را مجاز کند تا برنامه‌های مشتری Firebase Cloud Messaging شما بتوانند پیام دریافت کنند. درگاه‌هایی که باید باز شوند:
- 5228
- 5229
- 5230
FCM معمولاً از ۵۲۲۸ استفاده می‌کند، اما گاهی از ۵۲۲۹ و ۵۲۳۰ استفاده می‌کند. FCM نشانی‌های IP خاصی ارائه نمی‌دهد، بنابراین باید به دیواره آتش خود اجازه دهید اتصال‌های خروجی به همه نشانی‌های IP موجود در بلوک‌های IP فهرست‌شده در ASN ۱۵۱۶۹ Google را بپذیرد.
چرا
onMessageReceived در برنامه Android من فراخوانی نمی‌شود؟
وقتی برنامه‌تان در پس‌زمینه باشد، پیام‌های
اعلان
در سینی سیستم نمایش داده می‌شود و onMessageReceived فراخوانی نمی‌شود. برای
پیام‌های اعلان با بار داده، پیام اعلان در
سینی سیستم نمایش داده می‌شود و داده‌هایی که با پیام اعلان همراه بوده‌اند
می‌توانند از هدف راه‌اندازی‌شده هنگام ضربه زدن کاربر روی
اعلان بازیابی شوند.
برای اطلاعات بیشتر، دریافت و مدیریت پیام‌ها را ببینید.
چرا وقتی به نمونه برنامه فعالی که از نسخه پشتیبان بازیابی شده است پیام ارسال می‌کنم، خطای ۴۰۴ دریافت می‌کنم؟
FID (شناسه نصب Firebase) شناسه نمونه برنامه است. به‌طور پیش‌فرض، داده‌های «نصب Firebase» پشتیبان‌گیری و بازیابی می‌شود. بنابراین در مورد بازیابی، نمونه برنامه بازیابی‌شده و نمونه برنامه اصلی FID یکسانی دارند. ازآنجایی‌که FCM فقط یک کد برای هر FID ذخیره می‌کند، اگر هم نمونه برنامه اصلی و هم نمونه برنامه بازیابی‌شده درحال استفاده باشند، وقتی یک نمونه برنامه در FCM ثبت می‌شود، کد نمونه برنامه دیگر برداشته می‌شود که باعث خطای ۴۰۴ می‌شود.
به توسعه‌دهندگان توصیه می‌کنیم موارد زیر را در برنامه‌شان انجام دهند:
- مستثنی کردن
داده‌های نصب Firebase در نسخه پشتیبان. داده‌های نصب Firebase در فایل
PersistedInstallation....jsonذخیره می‌شود. نام فایل برای برنامه ثابت است. برای مثال،<exclude domain="file" path="PersistedInstallation.W0R...GQ.json" />
Apple اعلام کرد که پروتکل دودویی قدیمی را برای APN منسوخ می‌کند. آیا لازم است کاری انجام دهم؟
نه. Firebase Cloud Messaging در سال ۲۰۱۷ به پروتکل APN مبتنی بر HTTP/2 تغییر کرد. اگر از FCM برای ارسال اعلان به دستگاه‌های iOS استفاده می‌کنید، لازم نیست اقدامی انجام دهید.
سهمیه‌ها و محدودیت‌های FCM
چگونه می‌توانم در عرض ۲ دقیقه به پایگاه مشتریان بزرگ اطلاع دهم؟
این مورد استفاده پشتیبانی نمی‌شود. باید ترافیکتان را درطول ۵ دقیقه پخش کنید.
برنامه من رویدادها را به کاربران اطلاع می‌دهد و این پیام‌ها باید فوراً ارسال شوند تا از مدل کسب‌وکار من پشتیبانی شود. آیا می‌توانم سهمیه بیشتری دریافت کنم؟
متأسفانه به این دلیل نمی‌توانیم سهمیه را افزایش دهیم. باید ترافیکتان را درطول ۵ دقیقه پخش کنید تا از ترافیک جهشی جلوگیری شود.
پیام‌های من درباره رویدادهای زمان‌بندی‌شده است. چگونه می‌توانم همه ترافیک را در ابتدای ساعت ارسال کنم؟
توصیه می‌کنیم ارسال اعلان‌ها را حداقل ۵ دقیقه قبل‌از رویداد شروع کنید. یا پیام‌های داده ارسال کنید و آنالوگ پلاتفرم خود را از گرداننده onMessageReceived پیاده‌سازی کنید تا اعلان‌های محلی را ازقبل زمان‌بندی کنید.
چگونه می‌توانم مصرف سهمیه‌ام را پایش کنم؟
راهنمای Google Cloud را درباره نحوه نمودار کردن و پایش سنجه‌های سهمیه ببینید.
رسیدگی به خطاهای ۴۲۹ برای من و کسب‌وکارم دشوار است. آیا می‌توانم معافیت یا سهمیه بیشتری دریافت کنم تا خطای ۴۲۹ دریافت نکنم؟
بااینکه می‌دانیم محدودیت‌های سهمیه می‌تواند چالش‌برانگیز باشد، سهمیه‌ها برای حفظ قابلیت اطمینان سرویس حیاتی هستند و نمی‌توانیم معافیت اعطا کنیم. از تکرار مجدد برای رسیدگی صحیح به خطاهای ۴۲۹ استفاده کنید.
چقدر طول می‌کشد تا درخواست افزایش سهمیه من برآورده شود؟
درخواست افزایش سهمیه شما به استفاده‌تان از FCM بستگی دارد. در هر صورت، می‌توانید انتظار داشته باشید که ظرف چند روز کاری پاسخ دریافت کنید. در برخی موارد، ممکن است درباره استفاده شما از FCM و شرایط مختلف، رفت‌وبرگشت‌هایی وجود داشته باشد که می‌تواند فرایند را طولانی کند. اگر همه الزامات برآورده شده باشد، بیشتر درخواست‌ها ظرف ۲ هفته رسیدگی خواهد شد.
آیا می‌توانم برای رویدادی موقت سهمیه بیشتری دریافت کنم؟
می‌توانید برای پشتیبانی از رویدادی که حداکثر ۱ ماه طول می‌کشد، سهمیه اضافی درخواست کنید. درخواست را حداقل ۱ ماه قبل‌از رویداد و با جزئیات واضح درباره زمان شروع و پایان رویداد ارسال کنید و FCM تمام تلاش عملی خود را برای برآورده کردن درخواست انجام خواهد داد. درصورت اعطا، این افزایش سهمیه پس‌از تاریخ پایان رویداد برگردانده خواهد شد.
آیا سهمیه فعلی من ممکن است تغییر کند؟
اگرچه Google این کار را به‌راحتی انجام نمی‌دهد، اما ممکن است سهمیه‌ها درصورت نیاز برای محافظت از یکپارچگی سیستم تغییر کنند. درصورت امکان، Google پیش‌از اعمال چنین تغییراتی به شما اطلاع خواهد داد. مخاطبین Cloud MSA خود را به‌روز نگه دارید تا احتمال دریافت اعلامیه‌های خدمات افزایش یابد.
FCM منسوخ شدن میانای برنامه‌سازی کاربردی قدیمی
میاناهای برنامه‌سازی کاربردی سمت سرور در سپتامبر ۲۰۲۶ منسوخ می‌شوند
کدام میاناهای برنامه‌سازی کاربردی و ویژگی‌ها منسوخ شده‌اند و از رده خارج خواهند شد؟ اگر از این میاناهای برنامه‌سازی کاربردی استفاده می‌کنم، چه کاری باید انجام دهم؟
همه میاناهای برنامه‌سازی کاربردی سرور InstanceId و ویژگی گروه دستگاه منسوخ شده‌اند و در ۲۹ سپتامبر ۲۰۲۷ از رده خارج خواهند شد. جدول زیر جزئیات بیشتری درباره میاناهای برنامه‌سازی کاربردی/ویژگی‌های منسوخ‌شده و اقدام لازم نشان می‌دهد.
| نام میانای برنامه‌سازی کاربردی | نقطه پایانی میانای برنامه‌سازی کاربردی | استفاده موردنظر | تأثیر بر مشتری | اقدام لازم است |
|---|---|---|---|---|
| InstanceId info API | https://iid.googleapis.com/iid/info | دریافت اطلاعات مربوط به InstanceId / کد FCM | درخواست‌های ارسال‌شده به این میانای برنامه‌سازی کاربردی از ۲۹ سپتامبر ۲۰۲۷ ناموفق خواهد بود. | برای مشتریانی که از API برای اعتبارسنجی کد استفاده می‌کنند، از FCM V1 send API استفاده کنید و validate_only را روی true تنظیم کنید.
برای مشتریانی که از میانای برنامه‌سازی کاربردی برای دریافت اطلاعات اشتراک موضوع استفاده می‌کنند، به میانای برنامه‌سازی کاربردی جدید اشتراک موضوع منتقل شوید. |
| InstanceId topic subscription API | https://iid.googleapis.com/iid/v1/…/rel/topics https://iid.googleapis.com/iid/v1:batchAdd https://iid.googleapis.com/iid/v1:batchRemove |
مشترک کردن کد(های) امنیتی در موضوع ازطریق میانای برنامه‌سازی کاربردی اشتراک موضوع قدیمی. | درخواست‌های ارسال‌شده به این میانای برنامه‌سازی کاربردی از ۲۹ سپتامبر ۲۰۲۷ ناموفق خواهد بود. | برای اشتراک و لغو اشتراک موضوع، به API جدید سرور اشتراک موضوع FCM مهاجرت کنید. |
| میانای برنامه‌سازی کاربردی وارد کردن دسته‌ای InstanceId | https://iid.googleapis.com/iid/v1:batchImport | ایجاد دسته‌ای توکن‌های FCM برای iOS در سمت سرور. | درخواست‌های ارسال‌شده به این میانای برنامه‌سازی کاربردی از ۲۹ سپتامبر ۲۰۲۷ ناموفق خواهد بود.
ایجاد ثبت FCM از توکن‌های APN در سمت سرور پشتیبانی نخواهد شد. |
می‌توانید از سرویس APN Apple برای ارسال اعلان بااستفاده از توکن‌های APN استفاده کنید.
برای دریافت مزایای اضافی ارائه‌شده توسط FCM، برنامه‌تان را با FCM iOS SDK ادغام کنید که ثبت‌نام‌های FCM را در کارخواه ایجاد خواهد کرد. |
| میانای برنامه‌سازی کاربردی مدیریت گروه دستگاه | https://fcm.googleapis.com/fcm/notification https://fcm.googleapis.com/gcm/notification https://fcm.googleapis.com/iid/notification https://fcm.googleapis.com/notification |
درحال افزودن / برداشتن/ بازیابی اعضای گروه دستگاه. | درخواست‌های ارسال‌شده به این میانای برنامه‌سازی کاربردی از ۲۹ سپتامبر ۲۰۲۷ ناموفق خواهد بود. | راهنمای انتقال از این ویژگی را ببینید.
پیام‌ها همچنان می‌توانند به‌جای کدهای گروهی به ثبت‌های FCM فردی ارسال شوند. |
| ارسال گروه دستگاه | https://fcm.googleapis.com/v1/projects/…/messages:send | ارسال پیام به گروه‌های دستگاه بااستفاده از notification_key گروه. | این میانای برنامه‌سازی کاربردی همچنان کار خواهد کرد اما پس‌از ۲۹ سپتامبر ۲۰۲۷ از کدهای گروه دستگاه پشتیبانی نخواهد کرد. |
اگر از Firebase Admin SDK برای مدیریت اشتراک‌های موضوع استفاده می‌کنم، آیا تحت تأثیر این منسوخ شدن قرار خواهم گرفت؟ چه کاری باید انجام دهم؟
اگر از نسخه‌های قدیمی‌تر Firebase Admin SDK برای مدیریت اشتراک‌های موضوع استفاده می‌کنید، تحت تأثیر این منسوخ شدن قرار خواهید گرفت. باید Firebase Admin SDK خود را به نسخه‌های زیر ارتقا دهید:
| Platform | نسخه Admin SDK تحت‌تأثیر قرار گرفته است | نسخه کیت توسعه نرم‌افزار سرپرست برای ارتقا دادن |
|---|---|---|
| Node.js | <=14.4.0 | >=14.5.0 |
| پایتون | <=7.6.0 | >=7.7.0 |
| جاوا | <=9.10.0 | >=9.11.0 |
| رفتن | <=4.21.0 | >=4.22.0 |
| .NET | <=3.6.0 | >=3.7.0 |
آیا قبل‌از ۲۹ سپتامبر ۲۰۲۷ شاهد تنزل سرویس خواهم بود؟
نه. ۱۲ ماه فرصت دارید تا از میاناهای برنامه‌سازی کاربردی منسوخ‌شده به جایگزین‌ها منتقل شوید بدون اینکه هیچ‌گونه تنزل سرویسی داشته باشید. اکیداً توصیه می‌کنیم انتقال را در اسرع وقت برنامه‌ریزی کنید تا تحت تأثیر ازکاراندازی قرار نگیرید.
پس‌از ۲۹ سپتامبر ۲۰۲۷، هنگام فراخوانی میاناهای برنامه‌سازی کاربردی منسوخ‌شده، احتمالاً با خطا مواجه خواهید شد.
آیا کاربران جدید می‌توانند قبل‌از ازکاراندازی، میاناهای برنامه‌سازی کاربردی/ویژگی‌های منسوخ‌شده را آماده کار کنند؟
کاربران جدید می‌توانند قبل‌از ۱ ژانویه ۲۰۲۷، از ویژگی‌ها/میاناهای برنامه‌سازی کاربردی منسوخ‌شده استفاده کنند. پس‌از ۱ ژانویه ۲۰۲۷، کاربران جدید نمی‌توانند از میاناهای برنامه‌سازی کاربردی منسوخ‌شده استفاده کنند. کاربرانی که از میاناهای برنامه‌سازی کاربردی منسوخ‌شده استفاده می‌کنند می‌توانند تا ۲۹ سپتامبر ۲۰۲۷ به استفاده از آن‌ها ادامه دهند.
پرسشگان AndroidConfigV2
تا چه زمانی از AndroidConfig (v1) API قدیمی پشتیبانی خواهد شد؟
FCM قصد دارد تا چند سال پس‌از انتشار نسخه «دسترسی عمومی» (GA) AndroidConfigV2، به پشتیبانی از محموله‌های v1 AndroidConfig ادامه دهد. اگرچه زمان‌بندی انتقال چند سال طول می‌کشد،
AndroidConfigV2 تحویل اعلان قابل‌پیش‌بینی‌تری ارائه می‌دهد و
توصیه می‌شود در اسرع وقت انتقال را انجام دهید.
کدام نسخه‌های سیستم‌عامل Android توسط AndroidConfigV2 پشتیبانی می‌شوند؟
AndroidConfigV2 در همه نسخه‌های Android که Google از آن‌ها پشتیبانی می‌کند
پشتیبانی خواهد شد. وقتی «میانای برنامه‌سازی کاربردی» v1 قدیمی از رده خارج شود، همه دستگاه‌ها به‌جز دستگاه‌های قدیمی‌تر از ۱۰ سال پشتیبانی خواهند شد.
آیا AndroidConfigV2 محموله‌ها را به دستگاه‌هایی که فقط از میانای قدیمی v1 پشتیبانی می‌کنند ارسال می‌کند، و تغییرات را باید به چه ترتیبی عرضه کنم؟
بله. وقتی درخواست AndroidConfigV2 ارسال می‌کنید، FCM و GMS Core
به‌طور خودکار بار مفید را برای دستگاه‌هایی که کیت توسعه نرم‌افزار کارخواه قدیمی‌تر اجرا می‌کنند یا برای
برنامه‌هایی که هنوز onNotificationReceived() یا
onBackgroundSyncReceived() را لغو نکرده‌اند ترجمه می‌کنند و آن را بااستفاده از onMessageReceived() تحویل می‌دهند.
چرا AndroidConfigV2 نیاز دارد که اعلان‌ها را ازطریق FCM SDK برگرداند به‌جای اینکه مستقیماً NotificationManager.notify() را فراخوانی کند؟
با برگرداندن NotificationResponse به
کیت توسعه نرم‌افزار FCM متن‌باز، یا استفاده از FcmNotificationManager:
- برنامه شما یک پنجره اجرای محافظت‌شده برای رمزگشایی یا سفارشی‌سازی اعلان دریافت می‌کند.
- اگر زمان برنامه‌تان تمام شود، «هسته سرویس‌های تلفن همراه Google» با پست کردن
اعلان پشتیبان که در
remote_notification.notificationپیکربندی کرده‌اید، از تحویل به‌موقع اطمینان حاصل می‌کند.
آیا AndroidConfigV2 اعلان‌ها را زمانی که برنامه من در پیش‌زمینه است نسبت به زمانی که در پس‌زمینه است به‌طور متفاوتی مدیریت می‌کند؟
نه. برخلاف پیام‌های اعلان قدیمی نسخه ۱، AndroidConfigV2 مسیریابی پیام را براساس اینکه برنامه‌تان در پیش‌زمینه یا پس‌زمینه باشد تقسیم نمی‌کند.
وقتی RemoteNotification ارسال می‌کنید، اعلان به‌طور خودکار در هر دو حالت نمایش داده می‌شود، مگراینکه mutable_content: true را تنظیم کنید و صریحاً آن را در onNotificationReceived() بااستفاده از NotificationResponse.createEmpty() بی‌صدا کنید.
برنامه من چقدر زمان برای رسیدگی به RemoteNotification تغییرپذیر دارد؟
وقتی mutable_content: true روی RemoteNotification تنظیم شده باشد، برنامه‌تان حداکثر ۲۰ ثانیه در onNotificationReceived() فرصت دارد تا قبل‌از برگرداندن NotificationResponse، بار داده‌ها را رمزگشایی کند، دارایی‌های کوچک (مانند چهره‌نماها) را واکشی کند، یا با سرور برنامه‌تان تماس بگیرد. اگر فراخوانی برگشتی بیش‌از ۲۰ ثانیه طول بکشد، اجرا لغو می‌شود و «هسته GMS» به‌طور خودکار اعلان بازگشتی براساس بار خالص remote_notification.notification پست می‌کند.
اجرای سرکوب اعلان برای RemoteNotifications قابل‌تغییر چگونه کار می‌کند؟
برنامه‌ها می‌توانند با برگرداندن
NotificationResponse.suppress() از onNotificationReceived()، RemoteNotification را سرکوب کنند. برای مثال، وقتی گپی بی‌صدا می‌شود، فرستنده‌ای مسدود می‌شود، یا اعتبارسنجی محموله رمزگذاری‌شده سرتاسر ناموفق است.
- در پس‌زمینه: برنامه شما می‌تواند تا
۲۵٪ از پیام‌های
RemoteNotificationدریافتی را درطول یک پنجره متحرک سرکوب کند. اگر نرخ سرکوب پس‌زمینه برنامه‌تان از ۲۵٪ فراتر رود، «هسته خدمات Google Play» به‌طور خودکار اعلان احتیاطی را از بار دادهremote_notification.notificationارائه و پست می‌کند. - در پیش‌زمینه: می‌توانید همه «اعلان‌های ازراه‌دور» را درحالی‌که در پیش‌زمینه فعال هستید، سرکوب کنید. برای مثال، برای نمایش پنجره خبری درون‌برنامه یا به‌روزرسانی صفحه گپ باز به‌جای پست کردن اعلان سیستم.
آیا برنامه من می‌تواند چندین اعلان پست کند یا اعلان موجود را از یک RemoteNotification لغو کند؟
بله. برای لغو یا پست کردن چند اعلان، از موارد زیر استفاده کنید:
- لغو یک اعلان:
NotificationResponse.createCancel(tag, id)را ازonNotificationReceived()برگردانید تا اعلانی را که قبلاً پست شده است ببندید. - پست کردن چند اعلان یا ترکیب لغوها و پست‌ها:
getFcmNotificationManager(message)را درonNotificationReceived()فراخوانی کنید تاpostNow(tag, id, notification)وcancelNow(tag, id)را چندبار فراخوانی کنید و پس‌از تکمیل،manager.finished()را برگردانید.
آیا RemoteViews سفارشی می‌تواند با AndroidConfigV2 کار کند؟
بله، RemoteViews سفارشی با AndroidConfigV2 کار خواهد کرد.
onNotificationReceived() شیء استاندارد Android Notification را برمی‌گرداند، همه
میاناهای برنامه‌سازی کاربردی اعلان استاندارد Android، مثل setCustomContentView()، همچنان
پشتیبانی می‌شوند. توجه داشته باشید که RemoteViews و Views در حالت نگهداری هستند و توصیه می‌شود به Compose منتقل شوند.