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

يوفر هذا المستند مرجعًا لبنية HTTP المستخدمة لتمرير الرسائل من خادم تطبيقك إلى تطبيقات العميل عبر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase".

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

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

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

بنية الرسالة بعد بيع البيانات

يوفّر هذا القسم بنية إرسال الرسائل النهائية وتفسير استجابات HTTP من "المراسلة عبر السحابة الإلكترونية من Firebase".

رسائل HTTP النهائية (JSON)

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

الجدول 1. الأهداف والخيارات وحمولة رسائل HTTP التي تعرض البيانات (JSON)

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

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

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

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

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

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

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

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

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

شرط مسموح به: الموضوع، منسَّق على أنّه "yourTopic" في المواضيع. وهذه القيمة غير حساسة لحالة الأحرف.

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

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

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

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

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

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

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

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

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

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

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

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

time_to_live رقم اختياري

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

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

تكون القيمة التلقائية false.
الحمولة
data كائن اختياري

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

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

على أنظمة Apple الأساسية، إذا تم إرسال الرسالة عبر أسماء نقاط الوصول (APN)، ستمثِّل حقول البيانات المخصَّصة. وفي حال إرسالها من خلال "المراسلة عبر السحابة الإلكترونية من Firebase"، سيتم تمثيلها كقاموس للقيمة الرئيسية في AppDelegate application:didReceiveRemoteNotification:.

في نظام التشغيل Android، قد ينتج عن ذلك إجراء إضافي يُسمى score مع قيمة السلسلة 3x1.

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

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

دعم حمولة الإشعارات

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

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

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

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

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

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

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

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

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

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

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

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

ولن يتم تغيير الشارة في حال عدم تحديدها.

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

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

الإجراء المرتبط بالنقر على الإشعار

يتطابق مع category في حمولة أسماء نقاط الوصول.

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

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

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

تمثّل هذه السمة مفتاح السلسلة الأساسية في موارد سلسلة التطبيق المطلوب استخدامها لترجمة النص الأساسي حسب الأقلمة الحالية للمستخدم.

يتطابق مع loc-key في حمولة أسماء نقاط الوصول.

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

body_loc_args اختياري، مصفوفة JSON كسلسلة

قيم سلسلة المتغير التي سيتم استخدامها بدلاً من محدِّدات التنسيق في body_loc_key لاستخدامها في أقلمة النص الأساسي مع الأقلمة الحالية للمستخدم

يتطابق مع loc-args في حمولة أسماء نقاط الوصول.

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

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

تمثّل هذه السمة مفتاح سلسلة العنوان في موارد سلسلة التطبيق المطلوب استخدامها لترجمة نص العنوان حسب الأقلمة الحالية للمستخدم.

يتطابق مع title-loc-key في حمولة أسماء نقاط الوصول.

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

title_loc_args اختياري، مصفوفة JSON كسلسلة

قيم سلسلة المتغير التي سيتم استخدامها بدلاً من محدِّدات التنسيق في title_loc_key لاستخدامها في أقلمة نص العنوان حسب الأقلمة الحالية للمستخدم

يتطابق مع title-loc-args في حمولة أسماء نقاط الوصول.

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

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

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

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

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

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

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

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

يجب أن ينشئ التطبيق قناة تحتوي على معرّف القناة هذا قبل تلقّي أي إشعار يتضمّن معرّف القناة هذا.

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

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

رمز الإشعار.

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

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 عبر النص العادي.

الجدول 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 مع قيمة السلسلة 3x1.

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

تفسير ردّ على الرسالة

يجب أن يقيّم خادم التطبيق كلاً من عنوان استجابة الرسالة والنص لتفسير استجابة الرسالة المُرسَلة من "المراسلة عبر السحابة الإلكترونية من Firebase". يصف الجدول التالي الردود المحتملة.

الجدول 4. عنوان استجابة رسالة HTTP لانتقال البيانات

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

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

الجدول 5. نص استجابة رسالة HTTP لتدفق البيانات (JSON)

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

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

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

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

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

الجدول 8. استجابة خطأ لنص استجابة رسالة HTTP لنقطة البيع (نص عادي).

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

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

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

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

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

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

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

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

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

قلِّل عدد الرسائل المرسَلة إلى هذا الجهاز واستخدِم وضع الرقود الأسي لإعادة محاولة الإرسال.
تم تجاوز معدل الرسائل في المواضيع 200 + خطأ:
TopicsMessageRate
تم تجاوز العدد		 معدل الرسائل المرسلة إلى المشتركين في موضوع معين مرتفع جدًا. قلِّل عدد الرسائل المُرسَلة لهذا الموضوع واستخدِم خوارزمية الرقود الأسي لإعادة محاولة الإرسال.
بيانات اعتماد APN غير صالحة 200 + الخطأ:
InvalidApnsCredentials 		تعذّر إرسال رسالة موجَّهة إلى جهاز Apple لأنّ مفتاح مصادقة أسماء نقاط الوصول (APN) المطلوب لم يتم تحميله أو انتهت صلاحيته. تحقَّق من صلاحية بيانات الاعتماد الخاصة بالتطوير والإنتاج.

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

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

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

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