بروتوكول HTTP للمراسلة عبر السحابة الإلكترونية من Firebase

يوفّر هذا المستند مرجعًا لبنية HTTP المستخدَمة لنقل الرسائل من خادم التطبيقات إلى تطبيقات العملاء عبر Firebase Cloud Messaging.

عند استخدام بروتوكول HTTP القديم، يجب أن يوجّه خادم التطبيق جميع طلبات HTTP إلى نقطة النهاية هذه:

https://fcm.googleapis.com/fcm/send

تندرج المَعلمات والخيارات المتاحة ضمن الفئات الواسعة التالية:

بنية الرسائل الواردة

يقدّم هذا القسم بنية إرسال الرسائل إلى أسفل السلسلة وتفسير استجابات HTTP من Firebase Cloud Messaging.

رسائل HTTP للتحميل (بتنسيق JSON)

يسرد الجدول التالي الاستهدافات والخيارات وحمولة رسائل HTTP JSON.

الجدول 1: الاستهدافات والخيارات والحمولة لرسائل HTTP في مرحلة التحميل (JSON)

المَعلمة الاستخدام الوصف
الاستهدافات
to اختياري، سلسلة

تحدّد هذه المَعلمة مستلِم الرسالة.

يمكن أن تكون القيمة رمز تسجيل جهاز أو مفتاح إشعار لمجموعة أجهزة أو موضوع واحد (يسبقه /topics/). لإرسال الإشعار إلى مواضيع متعددة، استخدِم المَعلمة condition.

registration_ids
اختياري، مصفوفة من السلاسل

تحدِّد هذه المَعلمة مستلِم رسالة البث المتعدد، وهي رسالة يتم إرسالها إلى أكثر من رمز تسجيل واحد.

يجب أن تكون القيمة مصفوفة من الرموز المميّزة للتسجيل التي سيتم إرسال رسالة البث المتعدد إليها. يجب أن تحتوي الصفيف على رمز تسجيل واحد على الأقل و1,000 رمز تسجيل كحد أقصى. لإرسال رسالة إلى جهاز واحد، استخدِم المَعلمة to.

لا يُسمح برسائل البث المتعدد إلا باستخدام تنسيق HTTP JSON.

condition اختياري، سلسلة

تحدّد هذه المَعلمة تعبيرًا منطقيًا للشروط التي تحدد هدف الرسالة.

الشرط المتوافق: الموضوع، بتنسيق "‎'yourTopic' in topics". هذه القيمة غير حسّاسة لحالة الأحرف.

عوامل التشغيل المسموح بها: && و|| يمكن استخدام عاملَي تشغيل بحد أقصى في كل رسالة موضوع.
notification_key
تمّ إيقاف هذا العمود نهائيًا		 اختياري، سلسلة

تم إيقاف هذه المَعلمة نهائيًا. بدلاً من ذلك، استخدِم to لتحديد مستلمي الرسائل. لمزيد من المعلومات عن كيفية إرسال الرسائل إلى أجهزة متعدّدة، يُرجى الاطّلاع على مستندات منصّتك.
الخيارات
collapse_key اختياري، سلسلة

تحدد هذه المَعلمة مجموعة من الرسائل (مثلاً، باستخدام collapse_key: "Updates Available") التي يمكن تصغيرها، بحيث يتم إرسال الرسالة الأخيرة فقط عندما يمكن استئناف الإرسال. ويهدف ذلك إلى تجنُّب إرسال عددٍ كبير جدًا من الرسائل نفسها عندما يعود الجهاز إلى الاتصال بالإنترنت أو يصبح نشطًا.

يُرجى العلم أنّه لا يمكن ضمان ترتيب إرسال الرسائل.

ملاحظة: يُسمح بحد أقصى 4 مفاتيح مختلفة للاختصار في أي وقت. وهذا يعني أنّه يمكن أن تخزِّن FCM 4 رسائل مختلفة في الوقت نفسه لكل تطبيق عميل. وإذا تجاوزت هذا العدد، لا يمكن ضمان مفاتيح التصغير الأربعة التي ستحتفظ بها FCM.

priority اختياري، سلسلة

لضبط أولوية الرسالة. القيم الصالحة هي "عادي" و "مرتفع". على منصات Apple، تتوافق هذه الإعدادات مع أولويتَي APN‏ 5 و10.

يتم تلقائيًا إرسال رسائل الإشعارات بأولوية عالية، ويتم إرسال رسائل البيانات بأولوية عادية. تعمل الأولوية العادية على تحسين استهلاك تطبيق العميل للبطارية، ويجب استخدامها ما لم يكن مطلوبًا التسليم الفوري. بالنسبة إلى الرسائل ذات الأولوية العادية، قد يتلقّى التطبيق الرسالة مع تأخُّر غير محدّد.

عند إرسال رسالة ذات أولوية عالية، يتم إرسالها على الفور، ويمكن للتطبيق عرض إشعار.

content_available اختياري، منطقي

على منصات Apple، استخدِم هذا الحقل لتمثيل content-available في حملات APNs. عند إرسال إشعار أو رسالة وضبط هذا الخيار على true، يتم تنشيط تطبيق العميل غير النشط، ويتم إرسال الرسالة من خلال APNs كإشعار صامت وليس من خلال FCM. يُرجى العِلم أنّه لا يمكن ضمان إرسال الإشعارات الصامتة في خدمات APN، ويمكن أن تعتمد على عوامل مثل تفعيل المستخدم لميزة "وضع خفض استهلاك الطاقة" أو إغلاق التطبيق بشكلٍ قسري وما إلى ذلك. وعلى أجهزة Android، تؤدي رسائل البيانات إلى تنشيط التطبيق تلقائيًا. على Chrome: غير متاح حاليًا
mutable_content اختياري، منطقي بتنسيق JSON

على منصات Apple، استخدِم هذا الحقل لتمثيل mutable-content في حمولة APNs. عند إرسال إشعار وضبط هذا الخيار على true، يمكن تعديل محتوى الإشعار قبل عرضه، باستخدام إضافة تطبيق "خدمة الإشعارات". سيتم تجاهل هذه المَعلمة على Android والويب.

time_to_live اختياري، رقم

تحدِّد هذه المَعلمة المدة (بالثواني) التي يجب الاحتفاظ فيها بالرسالة في مساحة تخزين FCM إذا كان الجهاز غير متصل بالإنترنت. الحد الأقصى المسموح به لوقت الصلاحية هو 4 أسابيع، والقيمة التلقائية هي 4 أسابيع. لمزيد من المعلومات، يُرجى الاطّلاع على ضبط مدة صلاحية الرسالة.
restricted_package_
name (أجهزة Android فقط)		 اختياري، سلسلة تحدِّد هذه المَعلمة اسم حزمة التطبيق الذي يجب أن تتطابق فيه علامات تسجيل التطبيق لتلقّي الرسالة.
dry_run اختياري، منطقي

عند ضبط هذه المَعلمة على true، يُتاح للمطوّرين اختبار طلب بدون إرسال رسالة فعليًا.

ستكون القيمة التلقائية false.
حمولة البيانات
data اختياري، عنصر

تحدِّد هذه المَعلمة أزواج المفاتيح والقيم المخصّصة لحمولة الرسالة.

على سبيل المثال، مع data:{"score":"3x1"}:

على منصات Apple، إذا تم إرسال الرسالة من خلال APNs، فإنّها تمثّل حقول البيانات المخصّصة. إذا تم إرساله من خلال FCM، سيتم تمثيله كقائمة مفاتيح قيم في AppDelegate application:didReceiveRemoteNotification:.

على نظام التشغيل Android، سيؤدي ذلك إلى إضافة سمة إضافية للنشاط باسم score وقيمة السلسلة 3x1.

يجب ألّا يكون المفتاح كلمة محجوزة ("from" أو "message_type" أو أي كلمة تبدأ بحرف "google" أو "gcm"). لا تستخدِم أيًا من الكلمات المحدّدة في هذا الجدول (مثل collapse_key).

يُنصح باستخدام القيم في أنواع السلاسل. عليك تحويل القيم في الكائنات أو أنواع البيانات الأخرى غير السلاسل (مثل الأعداد الصحيحة أو القيم المنطقية) إلى سلاسل.
notification اختياري، عنصر تحدّد هذه المَعلمة أزواج المفاتيح والقِيم المحدّدة مسبقًا والتي تظهر للمستخدمين في الحمولة البرمجية للإشعار. اطّلِع على تفاصيل التوافق مع الحمولة في الإشعار. لمزيد من المعلومات عن خيارات رسالة الإشعار ورسالة البيانات، يُرجى قراءة مقالة أنواع الرسائل. في حال توفّر حمولة إشعار أو ضبط الخيار content_available على true لرسالة مُرسَلة إلى جهاز Apple ، يتم إرسال الرسالة من خلال APNs، وإلا يتم إرسالها من خلال FCM.

إتاحة الحمولة في الإشعار

تسرد الجداول التالية مفاتيح الإعداد المُسبَق المتاحة لإنشاء رسائل الإشعارات لنظامَي التشغيل iOS وAndroid.

الجدول 2(أ): نظام التشغيل iOS: مفاتيح رسائل الإشعارات

المَعلمة الاستخدام الوصف
title اختياري، سلسلة

عنوان الإشعار.

لا يظهر هذا الحقل على الهواتف والأجهزة اللوحية.

body اختياري، سلسلة

النص الأساسي للإشعار

sound اختياري، سلسلة

الصوت الذي سيتم تشغيله عندما يتلقّى الجهاز الإشعار

سلسلة تحدّد ملفات الصوت في الحِزمة الرئيسية لتطبيق العميل أو في مجلد Library/Sounds لحاويات بيانات التطبيق اطّلِع على مكتبة مطوّري تطبيقات iOS للحصول على مزيد من المعلومات.

badge اختياري، سلسلة

قيمة الشارة على رمز التطبيق في الشاشة الرئيسية

إذا لم يتم تحديدها، لن يتم تغيير الشارة.

في حال ضبطها على 0، تتم إزالة الشارة.

click_action اختياري، سلسلة

الإجراء المرتبط بنقرة أحد المستخدِمين على الإشعار

يتوافق مع category في حمولة APNs.

subtitle اختياري، سلسلة

العنوان الفرعي للإشعار

body_loc_key اختياري، سلسلة

مفتاح سلسلة النص في موارد سلاسل التطبيق لاستخدامه في تعريب نص النص إلى اللغة المحوَّلة حاليًا للمستخدم

يتوافق مع loc-key في حمولة APNs.

اطّلِع على مرجع مفتاح الحمولة و نقل محتوى الإشعارات عن بُعد إلى لغة أخرى للحصول على مزيد من المعلومات.

body_loc_args اختياري، مصفوفة JSON بالتنسيق السلسلة

قيم سلاسل متغيّرة لاستخدامها بدلاً من محدّدات التنسيق في body_loc_key لاستخدامها في ترجمة النص الأساسي إلى اللغة المحوَّلة حاليًا للمستخدم

يتوافق مع loc-args في حمولة APNs.

اطّلِع على مرجع مفتاح الحمولة و نقل محتوى الإشعارات عن بُعد إلى لغات مختلفة للحصول على مزيد من المعلومات.

title_loc_key اختياري، سلسلة

مفتاح سلسلة العنوان في موارد سلاسل التطبيق لاستخدامه في تعريب نص العنوان إلى اللغة المحوَّلة حاليًا للمستخدم

يتوافق مع title-loc-key في حمولة APNs.

اطّلِع على مرجع مفتاح الحمولة و نقل محتوى الإشعارات عن بُعد إلى لغة أخرى للحصول على مزيد من المعلومات.

title_loc_args اختياري، مصفوفة JSON بالتنسيق السلسلة

قيم سلاسل متغيّرة لاستخدامها بدلاً من محدّدات التنسيق في title_loc_key لاستخدامها في ترجمة نص العنوان إلى اللغة المُستخدَمة حاليًا لدى المستخدم

يتوافق مع title-loc-args في حمولة APNs.

اطّلِع على مرجع مفتاح الحمولة و نقل محتوى الإشعارات عن بُعد إلى لغة أخرى للحصول على مزيد من المعلومات.

الجدول 2(ب): Android - مفاتيح رسائل الإشعارات

المَعلمة الاستخدام الوصف
title اختياري، سلسلة

عنوان الإشعار.

body اختياري، سلسلة

النص الأساسي للإشعار

android_channel_id اختياري، سلسلة

معرّف قناة الإشعار (ميزة جديدة في Android O)

يجب أن ينشئ التطبيق قناة باستخدام معرّف القناة هذا قبل تلقّي أي إشعار باستخدامه.

إذا لم ترسِل معرّف القناة هذا في الطلب، أو إذا لم يكن التطبيق قد أنشأ معرّف القناة الذي تم تقديمه بعد، سيستخدم FCM معرّف القناة المحدّد في ملف بيان التطبيق.

icon اختياري، سلسلة

رمز الإشعار

تُستخدَم لضبط رمز الإشعار على myicon للمورد القابل للرسم myicon. في حال عدم إرسال هذا المفتاح في الطلب، FCM يعرض رمز مشغّل التطبيقات المحدّد في بيان تطبيقك.

sound اختياري، سلسلة

الصوت الذي سيتم تشغيله عندما يتلقّى الجهاز الإشعار

يتيح استخدام "default" أو اسم ملف لمصدر صوت مضمّن في التطبيق. يجب أن تكون ملفات الصوت متوفّرة في /res/raw/.

tag اختياري، سلسلة

المعرّف المستخدَم لاستبدال الإشعارات الحالية في درج الإشعارات

في حال عدم تحديده، ينشئ كل طلب إشعارًا جديدًا.

إذا تم تحديده وكان هناك إشعار يحمل العلامة نفسها معروضًا، سيحل الإشعار الجديد محل الإشعار الحالي في أدراج الإشعارات.

color اختياري، سلسلة

لون رمز الإشعار، مُعبَّرًا عنه بتنسيق #rrggbb

click_action اختياري، سلسلة

الإجراء المرتبط بنقرة أحد المستخدِمين على الإشعار

إذا تم تحديده، يتم تشغيل نشاط يتضمّن فلتر أهداف مطابقًا عند نقر المستخدم على الإشعار.

body_loc_key اختياري، سلسلة

مفتاح سلسلة النص في موارد سلاسل التطبيق لاستخدامه في تعريب نص النص إلى اللغة المحوَّلة حاليًا للمستخدم

اطّلِع على موارد السلاسل للحصول على مزيد من المعلومات.

body_loc_args اختياري، مصفوفة JSON بالتنسيق السلسلة

قيم سلاسل متغيّرة لاستخدامها بدلاً من محدّدات التنسيق في body_loc_key لاستخدامها في ترجمة النص الأساسي إلى اللغة المحوَّلة حاليًا للمستخدم

يمكنك الاطّلاع على التنسيق والتصميم للحصول على مزيد من المعلومات.

title_loc_key اختياري، سلسلة

مفتاح سلسلة العنوان في موارد سلاسل التطبيق لاستخدامه في تعريب نص العنوان إلى اللغة المحوَّلة حاليًا للمستخدم

اطّلِع على موارد السلاسل للحصول على مزيد من المعلومات.

title_loc_args اختياري، مصفوفة JSON بالتنسيق السلسلة

قيم سلاسل متغيّرة لاستخدامها بدلاً من محدّدات التنسيق في title_loc_key لاستخدامها في ترجمة نص العنوان إلى اللغة المُستخدَمة حاليًا لدى المستخدم

يمكنك الاطّلاع على التنسيق والتصميم للحصول على مزيد من المعلومات.

الجدول 2(ج): الويب (JavaScript) - مفاتيح رسائل الإشعارات

المَعلمة الاستخدام الوصف
title اختياري، سلسلة

عنوان الإشعار.

body اختياري، سلسلة

النص الأساسي للإشعار

icon اختياري، سلسلة

عنوان URL المراد استخدامه لرمز الإشعار.

click_action اختياري، سلسلة

الإجراء المرتبط بنقرة أحد المستخدِمين على الإشعار

يجب استخدام بروتوكول HTTPS لجميع قيم عناوين URL.

رسائل HTTP للتحميل (نص عادي)

يسرد الجدول التالي بنية الاستهدافات والخيارات وحمولة البيانات في رسائل HTTP للتحميل بتنسيق ملف txt.

الجدول 3: الاستهدافات والخيارات وحمولة رسائل HTTP النصية العادية في مرحلة التسليم

المَعلمة الاستخدام الوصف
الاستهدافات
registration_id مطلوب، سلسلة

تحدِّد هذه المَعلمة تطبيقات العميل (رموز تسجيل) التي تتلقّى الرسالة.

يُسمح بالرسائل عبر البث المتعدد (الإرسال إلى أكثر من رمز تنشيط تسجيل واحد) باستخدام تنسيق HTTP JSON فقط.
الخيارات
collapse_key اختياري، سلسلة اطّلِع على الجدول 1 للاطّلاع على التفاصيل.
time_to_live اختياري، رقم اطّلِع على الجدول 1 للاطّلاع على التفاصيل.
restricted_package_name اختياري، سلسلة اطّلِع على الجدول 1 للاطّلاع على التفاصيل.
dry_run اختياري، منطقي اطّلِع على الجدول 1 للاطّلاع على التفاصيل.
حمولة البيانات
data.<key> اختياري، سلسلة

تحدِّد هذه المَعلمة أزواج المفاتيح والقيم لحمولة الرسالة. ما مِن حدّ أقصى لعدد مَعلمات المفتاح والقيمة، ولكن هناك حدّ أقصى لحجم الرسالة يبلغ 4096 بايت.

على سبيل المثال، في Android، سيؤدي "data.score"."3x1" إلى إضافة score باسم score مع القيمة 3x1.

يجب ألّا يكون المفتاح كلمة محجوزة ("from" أو "message_type" أو أي كلمة تبدأ بحرف "google" أو "gcm"). لا تستخدِم أيًا من الكلمات المحدّدة في هذا الجدول (مثل collapse_key).

تفسير ردّ على رسالة في مرحلة ما بعد المعالجة

يجب أن يُقيِّم خادم التطبيق كلّ من عنوان استجابة الرسالة والنص لتفسير استجابة الرسالة المُرسَلة من FCM. يوضّح الجدول التالي الردود المحتمَلة.

الجدول 4: عنوان استجابة رسالة HTTP في الاتجاه الخلفي

الردّ الوصف
200 تمت معالجة الرسالة بنجاح. سيتضمّن نص الاستجابة المزيد من التفاصيل عن حالة الرسالة، ولكن سيعتمد تنسيقه على ما إذا كان الطلب بتنسيق JSON أو نصًا عاديًا. اطّلِع على الجدول 5 لمزيد من التفاصيل.
400 لا ينطبق ذلك إلا على طلبات JSON. يشير ذلك إلى أنّه تعذّر تحليل الطلب كملف JSON أو أنّه يحتوي على حقول غير صالحة (على سبيل المثال، تمّ إدخال سلسلة بدلاً من رقم). يتم وصف سبب الانهيار الدقيق في الردّ، ويجب معالجة المشكلة قبل إعادة محاولة إرسال الطلب.
401 حدث خطأ أثناء مصادقة حساب المُرسِل.
5xx تشير الأخطاء في النطاق من 500 إلى 599 (مثل 500 أو 503) إلى أنّه حدث خطأ داخلي في الخلفية في FCM أثناء محاولة معالجة الطلب، أو أنّ الخادم غير متاح مؤقتًا (على سبيل المثال، بسبب انتهاء المهلة). على المُرسِلمحاولة إرسال الرسالة مجددًا لاحقًا، مع مراعاة أي عنوان Retry-After مُدرَج في الردّ. يجب أن تطبِّق خوادم التطبيقات استراتيجية الانتظار الأسي.

يسرد الجدول التالي الحقول في نص استجابة الرسالة للمسار إلى أسفل السلسلة العميقة (JSON).

الجدول 5: محتوى استجابة رسالة HTTP للتحميل (بتنسيق JSON)

المَعلمة الاستخدام الوصف
multicast_id مطلوب، رقم معرّف فريد (رقم) يحدّد رسالة البث المتعدد
success مطلوب، رقم عدد الرسائل التي تمت معالجتها بدون خطأ
failure مطلوب، رقم عدد الرسائل التي تعذّرت معالجتها
results مطلوبة، مصفوفة من العناصر صفيف من العناصر التي تمثّل حالة الرسائل التي تمت معالجتها يتم إدراج العناصر بالترتيب نفسه للطلب (أي لكل رقم تعريف تسجيل في الطلب، يتم إدراج نتيجته في الفهرس نفسه في الاستجابة).
  • message_id: سلسلة تحدّد معرّفًا فريدًا لكل رسالة تمت معالجتها بنجاح
  • error: سلسلة تحدّد الخطأ الذي حدث أثناء معالجة الرسالة للمستلِم. يمكن العثور على القيم المحتمَلة في الجدول 9.

الجدول 6: نص استجابة HTTP لرسالة الموضوع (بتنسيق JSON)

المَعلمة الاستخدام الوصف
message_id اختياري، رقم رقم تعريف رسالة الموضوع عندما يتلقّى FCM الطلب بنجاح ويحاول إرساله إلى جميع الأجهزة المشترِكة.
error اختياري، سلسلة خطأ حدث أثناء معالجة الرسالة يمكن العثور على القيم المحتمَلة في الجدول 9.

الجدول 7: استجابة ناجحة لنص استجابة رسالة HTTP في مرحلة ما بعد المعالجة (نص عادي)

المَعلمة الاستخدام الوصف
id مطلوب، سلسلة تحدِّد هذه المَعلمة معرّف الرسالة الفريد FCM الذي تمت معالجته بنجاح.
registration_id اختياري، سلسلة تحدِّد هذه المَعلمة الرمز المميَّز للتسجيل لتطبيق العميل الذي تمت معالجة الرسالة وإرسالها إليه.

الجدول 8: استجابة الخطأ لنص استجابة رسالة HTTP في مرحلة ما بعد المعالجة (نص عادي)

المَعلمة الاستخدام الوصف
Error مطلوب، سلسلة تحدّد هذه المَعلمة قيمة الخطأ أثناء معالجة الرسالة للمستلِم. اطّلِع على الجدول 9 للاطّلاع على التفاصيل.

رموز الاستجابة للأخطاء في الرسائل الواردة

يسرد الجدول التالي رموز استجابة الخطأ للرسائل الواردة.

الجدول 9: رموز الاستجابة للأخطاء في الرسائل الواردة

خطأ رمز HTTP الإجراء المقترَح
عدم توفّر الرمز المميّز للتسجيل ‎200 + error:MissingRegistration تأكَّد من أنّ الطلب يحتوي على رمز مميّز للتسجيل (في registration_id في رسالة نصية عادية، أو في حقل to أو registration_ids بتنسيق JSON).
رمز تسجيل غير صالح ‎200 + error:InvalidRegistration تحقّق من تنسيق الرمز المميّز للتسجيل الذي ترسله إلى الخادم. تأكَّد من أنّه يتطابق مع رمز تسجيل التطبيق الذي يتلقّاه تطبيق العميل من التسجيل في Firebase الإشعارات. لا تقتطع العنوان أو تُضِف إليه أحرفًا إضافية.
جهاز غير مسجَّل 200 + error:NotRegistered قد يتوقف رمز تسجيل حالي عن العمل في عدد من السيناريوهات، بما في ذلك:
  • إذا ألغى تطبيق العميل تسجيله في FCM
  • إذا تم إلغاء تسجيل تطبيق العميل تلقائيًا، ما قد يحدث في حال إلغاء تثبيت التطبيق من قِبل المستخدم على سبيل المثال، في نظام التشغيل iOS، إذا أبلغت خدمة APNs Feedback Service عن رمز APNs على أنّه غير صالح.
  • إذا انتهت صلاحية الرمز المميّز للتسجيل (على سبيل المثال، قد تقرّر Google إعادة تحميل الرموز المميّزة للتسجيل، أو انتهت صلاحية الرمز المميّز لخدمات APNs على أجهزة iOS).
  • إذا تم تحديث تطبيق العميل ولكن لم يتم ضبط الإصدار الجديد لتلقّي الرسائل
في جميع هذه الحالات، عليك إزالة هذا الرمز المميّز للتسجيل من ملف برمجي التطبيق وإيقاف استخدامه لإرسال الرسائل.
اسم الحزمة غير صالح ‎200 + error:InvalidPackageName تأكَّد من أنّ الرسالة مُرسَلة إلى رمز مميّز للتسجيل يتطابق اسم حِزمته مع القيمة التي تم تمريرها في الطلب.
خطأ في المصادقة 401 تعذّر مصادقة حساب المُرسِل المستخدَم لإرسال رسالة. في ما يلي الأسباب المحتمَلة:
  • لا يتوفّر رأس التفويض أو أنّ بنية طلب HTTP غير صالحة.
  • مشروع Firebase الذي ينتمي إليه مفتاح الخادم المحدّد غير صحيح.
  • مفاتيح الخوادم القديمة فقط: نشأ الطلب من خادم غير مدرَج في القائمة البيضاء لعناوين IP لمفاتيح الخوادم.
تأكَّد من أنّ الرمز المميّز الذي ترسله داخل عنوان Authentication هو مفتاح الخادم الصحيح المرتبط بمشروعك. اطّلِع على مقالة التحقّق من صلاحية مفتاح الخادم لمعرفة التفاصيل. إذا كنت تستخدم مفتاح خادم قديمًا، ننصحك بالترقية إلى مفتاح جديد لا يحتوي على قيود عناوين IP. يُرجى الاطّلاع على نقل مفاتيح الخادم القديم.
المُرسِل غير متطابق 200 + error:MismatchSenderId يرتبط الرمز المميَّز للتسجيل بمجموعة معيّنة من المُرسِلين. عند تسجيل تطبيق العميل لنظام FCM، يجب أن يحدِّد المُرسِلين المسموح لهم بإرسال الرسائل. يجب استخدام أحد معرّفات المُرسِل هذه عند إرسال الرسائل إلى تطبيق العميل. وفي حال التبديل إلى مُرسِل مختلف، لن تعمل الرموز المميّزة الحالية للتسجيل.
ملف JSON غير صالح 400 تأكَّد من أنّ رسالة JSON منسَّقة بشكل صحيح وتتضمّن حقولًا صالحة (على سبيل المثال، التأكّد من إدخال نوع البيانات الصحيح).
المَعلمات غير الصالحة 400 + error:InvalidParameters تأكَّد من أنّ المَعلمات المقدَّمة لها الاسم والنوع الصحيحان.
الرسالة كبيرة جدًا 200 + error:MessageTooBig تأكَّد من أنّ إجمالي حجم بيانات الحمولة المضمّنة في الرسالة لا يتجاوز حدود FCM: 4096 بايت لمعظم الرسائل، أو 2048 بايت في حالة الرسائل المرسَلة إلى المواضيع. ويشمل ذلك كلاً من المفاتيح والقيم.
مفتاح بيانات غير صالح الخطأ 200 والخطأ ‎+200:
InvalidDataKey		 تأكَّد من أنّ بيانات الحمولة لا تحتوي على مفتاح (مثل from أو gcm أو أي قيمة تبدأ بالرمز google) يستخدمه FCM داخليًا. يُرجى العِلم أنّ بعض الكلمات (مثل collapse_key) تُستخدَم أيضًا من قِبل FCM ولكن يُسمح بها في الحمولة، وفي هذه الحالة ستُلغى قيمة الحمولة بقيمة FCM.
وقت الاستبدال غير صالح ‎200 + error:InvalidTtl تأكَّد من أنّ القيمة المستخدَمة في time_to_live هي عدد صحيح يمثّل مدّة بالثواني تتراوح بين 0 و2,419,200 (4 أسابيع).
انتهت المهلة خطأ 5xx أو 200 أو أكثر:غير متاح

تعذّر على الخادم معالجة الطلب في الوقت المحدّد. يمكنك إعادة محاولة إرسال الطلب نفسه، ولكن عليك إجراء ما يلي:

  • يجب الالتزام بعنوان Retry-After إذا كان مضمّنًا في الاستجابة من FCM Connection Server.
  • نفِّذ ميزة "الرقود الأسي الثنائي" في آلية إعادة المحاولة. (على سبيل المثال، إذا انتظرت ثانية واحدة قبل المحاولة الأولى، انتظِر ثانيتين على الأقل قبل المحاولة التالية، ثم 4 ثوانٍ، وهكذا). إذا كنت ترسل رسائل متعددة، يمكنك تأخير كل رسالة بشكل مستقل بمقدار عشوائي إضافي لتجنُّب تقديم طلب جديد لجميع الرسائل في الوقت نفسه.

ويواجه المُرسِلون الذين يتسببون في حدوث مشاكل خطر إدراجهم في القائمة السوداء.
حدث خطأ في الخادم الداخلي 500 أو 200 + error:InternalServerError واجه الخادم خطأً أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة تنفيذ الطلب نفسه باتّباع المتطلبات الواردة في "المهلة" (راجِع الصف أعلاه). إذا استمر ظهور الخطأ ، يُرجى التواصل مع فريق دعم Firebase.
تجاوز معدّل إرسال الرسائل على الجهاز الخطأ 200 والخطأ ‎+:
DeviceMessageRate
تجاوز الحدّ المسموح به

معدّل الرسائل المرسَلة إلى جهاز معيّن مرتفع جدًا. إذا كان أحد تطبيقات Apple يرسل الرسائل بمعدّل يتجاوز الحدود المسموح بها في APNs، قد تظهر له رسالة الخطأ هذه.

يمكنك تقليل عدد الرسائل المُرسَلة إلى هذا الجهاز واستخدام فاصل زمني متصاعد لإعادة محاولة الإرسال.
تجاوز معدّل إرسال الرسائل في Topics خطأ 200 أو أكثر:
TopicsMessageRate
تم تجاوزه		 معدّل الرسائل المرسَلة إلى المشتركين في موضوع معيّن مرتفع جدًا. يمكنك تقليل عدد الرسائل المُرسَلة لهذا الموضوع واستخدام أسلوب التراجع الدليلي لإعادة محاولة الإرسال.
بيانات اعتماد APNs غير صالحة 200 خطأ أو أكثر:
InvalidApnsCredential 		تعذّر إرسال رسالة مستهدفة لجهاز Apple لأنّه لم يتم تحميل مفتاح مصادقة APNs المطلوب أو انتهت صلاحيته. تحقّق من صلاحية بيانات اعتمادك في مرحلة التطوير والإصدار العلني.

إدارة مجموعة الأجهزة

يسرد الجدول التالي مفاتيح إنشاء مجموعات الأجهزة وإضافة الأعضاء وإزالتهم. لمزيد من المعلومات، اطّلِع على دليل المنصّة التي تستخدمها، سواء كانت iOS والإصدارات الأحدث أو Android.

الجدول 10: مفاتيح إدارة مجموعات الأجهزة

المَعلمة الاستخدام الوصف
operation مطلوب، سلسلة العملية المطلوب تنفيذها.القيم الصالحة هي create add وremove.
notification_key_name مطلوب، سلسلة الاسم الذي يحدّده المستخدم لمجموعة الأجهزة المطلوب إنشاؤها أو تعديلها.
notification_key مطلوب (باستثناء عملية create والسلسلة المعرّف الفريد لمجموعة الأجهزة يتم عرض هذه القيمة في الاستجابة لنجاح عملية create ، وهي مطلوبة لجميع العمليات اللاحقة على مجموعة الأجهزة.
registration_ids مطلوب، مصفوفة من السلاسل رموز الأجهزة التي تريد إضافتها أو إزالتها إذا أزلت جميع رموزها المميَّزة الحالية للتسجيل من مجموعة أجهزة، تحذف خدمة "إرسال الرسائل إلى الأجهزة الجوّالة من Google" مجموعة الأجهزة.