بروتوكول 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 خطأ أو أكثر: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 خادم الربط. نفِّذ ميزة "الرقود الأسي الثنائي" في آلية إعادة المحاولة. (على سبيل المثال، إذا انتظرت ثانية واحدة قبل المحاولة الأولى، انتظِر ثانيتين على الأقل قبل المحاولة التالية، ثم 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" مجموعة الأجهزة.