این سند مرجعی برای دستور HTTP ارائه میدهد که برای ارسال پیامها از سرور برنامه شما به برنامههای مشتری از طریق Firebase Cloud Messaging استفاده میشود.
هنگام استفاده از پروتکل HTTP قدیمی، سرور برنامه شما باید تمام درخواست های HTTP را به این نقطه پایانی هدایت کند:
https://fcm.googleapis.com/fcm/send
پارامترها و گزینه های موجود در دسته های کلی زیر قرار می گیرند:
نحو پیام پایین دست
این بخش نحوی را برای ارسال پیامهای پاییندست و تفسیر پاسخهای HTTP از Firebase Cloud Messaging ارائه میدهد.
پیامهای HTTP پاییندست (JSON)
جدول زیر اهداف، گزینهها و بارگذاری پیامهای HTTP JSON را فهرست میکند.
پارامتر | استفاده | توضیحات | |
---|---|---|---|
اهداف | |||
to | اختیاری، رشته | این پارامتر گیرنده پیام را مشخص می کند. این مقدار می تواند نشانه ثبت نام دستگاه، کلید اعلان گروه دستگاه یا یک موضوع واحد (پیشوند با | |
registration_ids | اختیاری، آرایه ای از رشته ها | این پارامتر گیرنده یک پیام چندپخشی را مشخص می کند، پیامی که به بیش از یک نشانه ثبت ارسال می شود. مقدار باید آرایه ای از نشانه های ثبت نام باشد که پیام چندپخشی به آن ارسال شود. آرایه باید حداقل 1 و حداکثر 1000 نشانه ثبت نام داشته باشد. برای ارسال پیام به یک دستگاه، از پارامتر پیامهای چندپخشی فقط با استفاده از قالب HTTP JSON مجاز هستند. | |
condition | اختیاری، رشته | این پارامتر یک بیان منطقی از شرایطی را مشخص می کند که هدف پیام را تعیین می کند. شرایط پشتیبانی شده: موضوع، قالببندی شده به عنوان «موضوع شما» در موضوعات. این مقدار به حروف بزرگ و کوچک حساس نیست. اپراتورهای پشتیبانی شده: | |
notification_key منسوخ شده است | اختیاری، رشته | این پارامتر منسوخ شده است. در عوض، | |
گزینه ها | |||
collapse_key | اختیاری، رشته | این پارامتر گروهی از پیامها را شناسایی میکند (بهعنوان مثال، با توجه داشته باشید که هیچ تضمینی برای ترتیب ارسال پیام ها وجود ندارد. توجه: حداکثر 4 کلید کوچک کردن مختلف در هر زمان مجاز است. این بدان معنی است که FCM می تواند به طور همزمان 4 پیام مختلف را در هر برنامه مشتری ذخیره کند. اگر از این تعداد تجاوز کنید، هیچ تضمینی وجود ندارد که FCM کدام 4 کلید جمع شدنی را حفظ کند. | |
priority | اختیاری، رشته | اولویت پیام را تعیین می کند. مقادیر معتبر «نرمال» و «بالا» هستند. در پلتفرمهای اپل، این موارد با اولویتهای 5 و 10 APN مطابقت دارند. به طور پیشفرض، پیامهای اعلان با اولویت بالا و پیامهای داده با اولویت عادی ارسال میشوند. اولویت عادی مصرف باتری برنامه مشتری را بهینه می کند و باید از آن استفاده کرد مگر اینکه تحویل فوری لازم باشد. برای پیامهایی با اولویت معمولی، برنامه ممکن است پیام را با تاخیر نامشخصی دریافت کند. هنگامی که پیامی با اولویت بالا ارسال می شود، بلافاصله ارسال می شود و برنامه می تواند یک اعلان نمایش دهد. | |
content_available | اختیاری، بولی | در پلتفرمهای اپل، از این فیلد برای نمایش | |
mutable_content | اختیاری، JSON boolean | در پلتفرمهای اپل، از این فیلد برای نمایش | |
time_to_live | اختیاری، شماره | این پارامتر مشخص می کند که در صورت آفلاین بودن دستگاه، چه مدت (بر حسب ثانیه) پیام باید در فضای ذخیره سازی FCM نگهداری شود. حداکثر زمان پشتیبانی زنده 4 هفته و مقدار پیش فرض آن 4 هفته است. برای اطلاعات بیشتر، به تنظیم طول عمر پیام مراجعه کنید. | |
restricted_package_ (فقط اندروید) | اختیاری، رشته | این پارامتر نام بسته برنامه را مشخص می کند که در آن نشانه های ثبت باید برای دریافت پیام مطابقت داشته باشند. | |
dry_run | اختیاری، بولی | این پارامتر، وقتی روی مقدار پیش فرض | |
بار | |||
data | اختیاری، شی | این پارامتر جفت های سفارشی کلید-مقدار محموله پیام را مشخص می کند. برای مثال، با در پلتفرم های اپل، اگر پیام از طریق APN ارسال شود، نشان دهنده فیلدهای داده سفارشی است. اگر از طریق FCM ارسال شود، به عنوان فرهنگ لغت ارزش کلیدی در در Android، این منجر به یک کلید نباید یک کلمه رزرو شده باشد ("from"، "message_type" یا هر کلمه ای که با "google" یا "gcm" شروع می شود). از هیچ یک از کلمات تعریف شده در این جدول (مانند مقادیر در انواع رشته توصیه می شود. شما باید مقادیر موجود در اشیا یا سایر انواع داده های غیر رشته ای (مثلاً اعداد صحیح یا بولی) را به رشته تبدیل کنید. | |
notification | اختیاری، شی | این پارامتر جفتهای کلید-مقدار از پیش تعریفشده و قابل رویت کاربر از بار اعلان را مشخص میکند. برای جزئیات بیشتر به پشتیبانی بارگیری اعلان مراجعه کنید. برای اطلاعات بیشتر درباره گزینههای پیام اعلان و پیام داده، به انواع پیام مراجعه کنید. اگر یک بار اعلان ارائه شود، یا گزینه content_available برای پیامی به دستگاه Apple روی true تنظیم شده باشد، پیام از طریق APN ارسال می شود، در غیر این صورت از طریق FCM ارسال می شود. |
پشتیبانی محموله اعلان
جداول زیر کلیدهای از پیش تعریف شده موجود برای ساخت پیام های اعلان برای iOS و Android را فهرست می کند.
پارامتر | استفاده | توضیحات |
---|---|---|
title | اختیاری، رشته | عنوان اطلاعیه این فیلد در گوشی ها و تبلت ها قابل مشاهده نیست. |
body | اختیاری، رشته | متن متن اعلان. |
sound | اختیاری، رشته | زمانی که دستگاه اعلان را دریافت می کند، صدایی پخش می شود. رشته ای که فایل های صوتی را در بسته اصلی برنامه کلاینت یا در پوشه |
badge | اختیاری، رشته | مقدار نشان در نماد برنامه صفحه اصلی. اگر مشخص نشده باشد، نشان تغییر نمی کند. اگر روی |
click_action | اختیاری، رشته | اقدام مرتبط با کلیک کاربر بر روی اعلان. مربوط به |
subtitle | اختیاری، رشته | زیرنویس اطلاعیه |
body_loc_key | اختیاری، رشته | کلید رشته بدنه در منابع رشته برنامه برای بومی سازی متن متن به محلی سازی فعلی کاربر. مربوط به برای اطلاعات بیشتر به مرجع کلید Payload و محلی سازی محتوای اعلان های راه دور خود مراجعه کنید. |
body_loc_args | اختیاری، آرایه JSON به عنوان رشته | مقادیر رشته متغیری که به جای مشخص کننده های قالب در مربوط به برای اطلاعات بیشتر به مرجع کلید Payload و محلی سازی محتوای اعلان های راه دور خود مراجعه کنید. |
title_loc_key | اختیاری، رشته | کلید رشته عنوان در منابع رشته برنامه برای بومی سازی متن عنوان در محلی سازی فعلی کاربر. مربوط به برای اطلاعات بیشتر به مرجع کلید Payload و محلی سازی محتوای اعلان های راه دور خود مراجعه کنید. |
title_loc_args | اختیاری، آرایه JSON به عنوان رشته | مقادیر رشته متغیری که به جای مشخص کننده های قالب در مربوط به برای اطلاعات بیشتر به مرجع کلید Payload و محلی سازی محتوای اعلان های راه دور خود مراجعه کنید. |
پارامتر | استفاده | توضیحات |
---|---|---|
title | اختیاری، رشته | عنوان اطلاعیه |
body | اختیاری، رشته | متن متن اعلان. |
android_channel_id | اختیاری، رشته | شناسه کانال اعلان (جدید در Android O). قبل از دریافت هر گونه اعلان با این شناسه کانال، برنامه باید کانالی با این شناسه کانال ایجاد کند. اگر این شناسه کانال را در درخواست ارسال نکنید، یا اگر شناسه کانال ارائهشده هنوز توسط برنامه ایجاد نشده باشد، FCM از شناسه کانال مشخصشده در مانیفست برنامه استفاده میکند. |
icon | اختیاری، رشته | نماد اعلان نماد اعلان را برای |
sound | اختیاری، رشته | زمانی که دستگاه اعلان را دریافت می کند، صدایی پخش می شود. از |
tag | اختیاری، رشته | شناسه برای جایگزینی اعلانهای موجود در کشوی اعلان استفاده میشود. اگر مشخص نشده باشد، هر درخواست یک اعلان جدید ایجاد می کند. اگر مشخص شده باشد و اعلانی با همان برچسب قبلاً نشان داده شده باشد، اعلان جدید جایگزین اعلان موجود در کشوی اعلان می شود. |
color | اختیاری، رشته | رنگ نماد اعلان، که در قالب |
click_action | اختیاری، رشته | اقدام مرتبط با کلیک کاربر بر روی اعلان. اگر مشخص شده باشد، زمانی که کاربر روی اعلان کلیک می کند، یک فعالیت با فیلتر هدف منطبق راه اندازی می شود. |
body_loc_key | اختیاری، رشته | کلید رشته بدنه در منابع رشته برنامه برای بومی سازی متن متن به محلی سازی فعلی کاربر. برای اطلاعات بیشتر به منابع رشته مراجعه کنید. |
body_loc_args | اختیاری، آرایه JSON به عنوان رشته | مقادیر رشته متغیری که به جای مشخص کننده های قالب در برای اطلاعات بیشتر به قالببندی و استایلسازی مراجعه کنید. |
title_loc_key | اختیاری، رشته | کلید رشته عنوان در منابع رشته برنامه برای بومی سازی متن عنوان در محلی سازی فعلی کاربر. برای اطلاعات بیشتر به منابع رشته مراجعه کنید. |
title_loc_args | اختیاری، آرایه JSON به عنوان رشته | مقادیر رشته متغیری که به جای مشخص کننده های قالب در برای اطلاعات بیشتر به قالببندی و استایلسازی مراجعه کنید. |
پارامتر | استفاده | توضیحات |
---|---|---|
title | اختیاری، رشته | عنوان اطلاعیه |
body | اختیاری، رشته | متن متن اعلان. |
icon | اختیاری، رشته | URL مورد استفاده برای نماد اعلان. |
click_action | اختیاری، رشته | اقدام مرتبط با کلیک کاربر بر روی اعلان. برای همه مقادیر URL، HTTPS مورد نیاز است. |
پیامهای HTTP پاییندست (متن ساده)
جدول زیر نحوی را برای اهداف، گزینهها و بارگذاری در پیامهای HTTP متنی ساده فهرست میکند.
پارامتر | استفاده | توضیحات |
---|---|---|
اهداف | ||
registration_id | مورد نیاز، رشته | این پارامتر برنامه های سرویس گیرنده (توکن های ثبت نام) را که پیام را دریافت می کنند، مشخص می کند. ارسال پیام چندپخشی (ارسال به بیش از یک نشانه ثبت نام) فقط با استفاده از فرمت HTTP JSON مجاز است. |
گزینه ها | ||
collapse_key | اختیاری، رشته | برای جزئیات به جدول 1 مراجعه کنید. |
time_to_live | اختیاری، شماره | برای جزئیات به جدول 1 مراجعه کنید. |
restricted_package_name | اختیاری، رشته | برای جزئیات به جدول 1 مراجعه کنید. |
dry_run | اختیاری، بولی | برای جزئیات به جدول 1 مراجعه کنید. |
بار | ||
data.<key> | اختیاری، رشته | این پارامتر جفت های کلید-مقدار محموله پیام را مشخص می کند. هیچ محدودیتی در تعداد پارامترهای کلید-مقدار وجود ندارد، اما محدودیت اندازه پیام در کل 4096 بایت است. به عنوان مثال، در Android، کلید نباید یک کلمه رزرو شده باشد ("from"، "message_type" یا هر کلمه ای که با "google" یا "gcm" شروع می شود). از هیچ یک از کلمات تعریف شده در این جدول (مانند |
تفسیر پاسخ پیام پایین دستی
سرور برنامه باید سرصفحه پاسخ پیام و بدنه را برای تفسیر پاسخ پیام ارسال شده از FCM ارزیابی کند. جدول زیر پاسخ های احتمالی را توضیح می دهد.
پاسخ | توضیحات |
---|---|
200 | پیام با موفقیت پردازش شد. بدنه پاسخ حاوی جزئیات بیشتری در مورد وضعیت پیام است، اما قالب آن بستگی به JSON یا متن ساده درخواست دارد. برای جزئیات بیشتر به جدول 5 مراجعه کنید. |
400 | فقط برای درخواست های JSON اعمال می شود. نشان می دهد که درخواست را نمی توان به عنوان JSON تجزیه کرد، یا حاوی فیلدهای نامعتبر بود (به عنوان مثال، ارسال رشته ای که در آن عدد مورد انتظار بود). دلیل دقیق شکست در پاسخ توضیح داده شده است و قبل از امتحان مجدد درخواست باید به مشکل رسیدگی شود. |
401 | هنگام احراز هویت حساب فرستنده خطایی روی داد. |
5xx | خطاها در محدوده 500-599 (مانند 500 یا 503) نشان میدهند که هنگام تلاش برای پردازش درخواست، یک خطای داخلی در پشتیبان FCM رخ داده است، یا اینکه سرور موقتاً در دسترس نیست (مثلاً به دلیل وقفههای زمانی). فرستنده باید بعداً دوباره امتحان کند و هر سرصفحه Retry-After موجود در پاسخ را رعایت کند. سرورهای برنامه باید پسآف نمایی را پیادهسازی کنند. |
جدول زیر فیلدهای یک بدنه پاسخ پیام پایین دستی (JSON) را فهرست می کند.
پارامتر | استفاده | توضیحات |
---|---|---|
multicast_id | مورد نیاز، شماره | شناسه (شماره) منحصر به فرد که پیام چندپخشی را شناسایی می کند. |
success | مورد نیاز، شماره | تعداد پیام هایی که بدون خطا پردازش شدند. |
failure | مورد نیاز، شماره | تعداد پیام هایی که پردازش نشدند. |
results | مورد نیاز، آرایه ای از اشیاء | آرایه ای از اشیاء نشان دهنده وضعیت پیام های پردازش شده است. اشیاء به همان ترتیب درخواست فهرست می شوند (یعنی برای هر شناسه ثبت در درخواست، نتیجه آن در همان فهرست در پاسخ ذکر می شود).
|
پارامتر | استفاده | توضیحات |
---|---|---|
message_id | اختیاری، شماره | شناسه پیام موضوع زمانی که FCM با موفقیت درخواست را دریافت کرد و تلاش میکند به همه دستگاههای مشترک ارسال کند. |
error | اختیاری، رشته | خطایی که هنگام پردازش پیام رخ داد. مقادیر ممکن را می توان در جدول 9 یافت. |
پارامتر | استفاده | توضیحات |
---|---|---|
id | مورد نیاز، رشته | این پارامتر شناسه پیام منحصر به فرد FCM را مشخص می کند که با موفقیت پردازش شده است. |
registration_id | اختیاری، رشته | این پارامتر رمز ثبت نام برنامه مشتری را مشخص می کند که پیام پردازش شده و به آن ارسال شده است. |
پارامتر | استفاده | توضیحات |
---|---|---|
Error | مورد نیاز، رشته | این پارامتر مقدار خطا را هنگام پردازش پیام برای گیرنده مشخص می کند. برای جزئیات به جدول 9 مراجعه کنید. |
کدهای پاسخ خطای پیام پایین دست
جدول زیر کدهای پاسخ خطا را برای پیام های پایین دستی فهرست می کند.
خطا | کد HTTP | اقدام توصیه شده |
---|---|---|
رمز ثبت نام وجود ندارد | 200 + خطا: MissingRegistration | بررسی کنید که درخواست حاوی یک نشانه ثبت نام باشد (در registration_id در یک پیام متنی ساده، یا در قسمت to یا registration_ids در JSON). |
رمز ثبت نام معتبر است | 200 + خطا:InvalidRegistration | فرمت رمز ثبت نامی که به سرور ارسال می کنید را بررسی کنید. مطمئن شوید که با نشانه ثبت نامی که برنامه مشتری از ثبت نام در Firebase Notifications دریافت می کند مطابقت دارد. از کوتاه کردن یا اضافه کردن کاراکترهای اضافی خودداری کنید. |
دستگاه ثبت نشده | 200 + خطا: ثبت نشده است | یک نشانه ثبت نام موجود ممکن است در تعدادی از سناریوها معتبر نباشد، از جمله:
|
نام بسته نامعتبر است | 200 + خطا:InvalidPackageName | مطمئن شوید که پیام به یک نشانه ثبتی که نام بسته آن با مقدار ارسال شده در درخواست مطابقت دارد، خطاب شده است. |
خطای احراز هویت | 401 | حساب فرستنده مورد استفاده برای ارسال پیام تأیید اعتبار نمی شود. علل احتمالی عبارتند از:
|
فرستنده ناسازگار | 200 + خطا: MismatchSenderId | یک نشانه ثبت نام به گروه خاصی از فرستندگان گره خورده است. هنگامی که یک برنامه مشتری برای FCM ثبت نام می کند، باید مشخص کند که کدام فرستنده مجاز به ارسال پیام است. هنگام ارسال پیام به برنامه مشتری باید از یکی از آن شناسه های فرستنده استفاده کنید. اگر به فرستنده دیگری بروید، نشانههای ثبتنام موجود کار نمیکنند. |
JSON نامعتبر است | 400 | بررسی کنید که پیام JSON به درستی قالب بندی شده باشد و حاوی فیلدهای معتبر باشد (به عنوان مثال، مطمئن شوید که نوع داده مناسب ارسال شده است). |
پارامترهای نامعتبر | 400 + خطا:InvalidParameters | بررسی کنید که پارامترهای ارائه شده دارای نام و نوع مناسبی باشند. |
پیام خیلی بزرگ است | 200 + خطا: MessageTooBig | بررسی کنید که حجم کل دادههای محموله موجود در یک پیام از محدودیتهای FCM تجاوز نکند: 4096 بایت برای اکثر پیامها، یا 2048 بایت در مورد پیامها به موضوعات. این شامل کلیدها و مقادیر می شود. |
کلید داده نامعتبر است | 200 + خطا: InvalidDataKey | بررسی کنید که دادههای محموله حاوی کلیدی (مانند from ، یا gcm ، یا هر مقداری که پیشوند google است) نباشد که به صورت داخلی توسط FCM استفاده میشود. توجه داشته باشید که برخی از کلمات (مانند collapse_key ) نیز توسط FCM استفاده میشوند اما در payload مجاز هستند، در این صورت مقدار payload با مقدار FCM لغو میشود. |
زمان نامعتبر برای زندگی | 200 + خطا: InvalidTtl | بررسی کنید که مقدار استفاده شده در time_to_live یک عدد صحیح باشد که نشان دهنده مدت زمان در ثانیه بین 0 تا 2,419,200 (4 هفته) است. |
تایم اوت | 5xx یا 200 + خطا: در دسترس نیست | سرور نتوانست به موقع درخواست را پردازش کند. همان درخواست را دوباره امتحان کنید، اما باید:
فرستنده هایی که مشکل ایجاد می کنند در معرض خطر قرار گرفتن در لیست سیاه هستند. |
خطای سرور داخلی | 500 یا 200 + خطا:InternalServerError | سرور هنگام تلاش برای پردازش درخواست با خطایی مواجه شد. میتوانید با پیروی از شرایط ذکر شده در «Timeout»، همان درخواست را دوباره امتحان کنید (به ردیف بالا مراجعه کنید). اگر خطا ادامه داشت، لطفاً با پشتیبانی Firebase تماس بگیرید. |
نرخ پیام دستگاه بیش از حد است | 200 + خطا: DeviceMessageRate فراتر رفت | نرخ پیام به یک دستگاه خاص بسیار بالا است. اگر یک برنامه اپل پیام هایی را با سرعتی بیش از حد مجاز APN ارسال کند، ممکن است این پیام خطا را دریافت کند تعداد پیامهای ارسال شده به این دستگاه را کاهش دهید و برای ارسال مجدد از عقبنشینی نمایی استفاده کنید. |
نرخ پیام موضوعات بیشتر شد | 200 + خطا: TopicsMessage Rate فراتر رفت | نرخ پیام به مشترکین یک موضوع خاص بسیار زیاد است. تعداد پیام های ارسال شده برای این موضوع را کاهش دهید و برای ارسال مجدد از عقب نشینی نمایی استفاده کنید. |
اعتبارنامه های APN نامعتبر | 200 + خطا: InvalidApnsCredential | پیامی که برای دستگاه Apple مورد نظر است ارسال نشد زیرا کلید احراز هویت APN های مورد نیاز آپلود نشده بود یا منقضی شده است. اعتبار اعتبارنامه توسعه و تولید خود را بررسی کنید. |
مدیریت گروه دستگاه
جدول زیر کلیدهای ایجاد گروه های دستگاه و افزودن و حذف اعضا را فهرست می کند. برای اطلاعات بیشتر، راهنمای پلتفرم، iOS+ یا Android خود را ببینید.
پارامتر | استفاده | توضیحات |
---|---|---|
operation | مورد نیاز، رشته | عملیات اجرا می شود. مقادیر معتبر create ، add و remove می شوند. |
notification_key_name | مورد نیاز، رشته | نام تعریف شده توسط کاربر گروه دستگاه برای ایجاد یا تغییر. |
notification_key | مورد نیاز (به جز برای عملیات create ، رشته | شناسه منحصر به فرد گروه دستگاه. این مقدار در پاسخ برای یک عملیات create موفقیت آمیز برگردانده می شود و برای تمام عملیات های بعدی در گروه دستگاه لازم است. |
registration_ids | مورد نیاز، آرایه از رشته ها | نشانههای دستگاه برای افزودن یا حذف. اگر تمام نشانه های ثبت نام موجود را از یک گروه دستگاه حذف کنید، FCM گروه دستگاه را حذف می کند. |