يوفر هذا المستند مرجعًا لبنية XMPP المستخدمة لتمرير الرسائل بين خادم التطبيق وتطبيقات العميل والمراسلة عبر السحابة الإلكترونية من Firebase (FCM). يجب أن يتصل خادم التطبيق بنقاط النهاية التالية:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
تندرج المعلمات والخيارات المتاحة ضمن هذه الفئات:
- بنية الرسائل بعد البث
- رموز الاستجابة للأخطاء في رسائل أثناء البث
- بنية رسالة Upstream
- رسائل التحكّم في "المراسلة عبر السحابة الإلكترونية من Firebase"
بنية الرسالة بعد استلامها
يوفر هذا القسم بنية إرسال الرسائل التي تأتي بعد استلام الرسالة.
رسائل XMPP المرسَلة لاحقًا (بتنسيق JSON)
يسرد الجدول التالي الأهداف والخيارات وحمولة رسائل XMPP بتنسيق JSON.
المَعلمة | الاستخدام | الوصف | |
---|---|---|---|
الهدف | |||
to |
اختياري، سلسلة |
تحدّد هذه المعلمة مُستلِم الرسالة.
يمكن أن تكون القيمة رمزًا مميّزًا لتسجيل جهاز أو مفتاح إشعارات لمجموعة أجهزة أو موضوعًا واحدًا (مسبقًا بـ |
|
condition |
اختياري، سلسلة | تحدّد هذه المعلمة تعبيرًا منطقيًا للشروط التي تحدد هدف الرسالة. الشرط المتوافق: موضوع، تم تنسيقه كـ "'yourTopic' في المواضيع". وهذه القيمة غير حساسة لحالة الأحرف. عوامل التشغيل المتوافقة: |
|
الخيارات | |||
message_id |
مطلوب، سلسلة | تحدد هذه المعلمة رسالة بشكل فريد في اتصال XMPP. |
|
collapse_key |
اختياري، سلسلة | تحدد هذه المعلمة مجموعة من الرسائل (مثلاً، مع
وليس هناك ما يضمن ترتيب إرسال الرسائل. ملاحظة: يُسمح باستخدام 4 مفاتيح تصغير مختلفة كحد أقصى في أي وقت. ويعني هذا أنّ خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" يمكنها تخزين 4 رسائل مختلفة في الوقت نفسه لكل تطبيق عميل. وفي حال تجاوز هذا العدد، ليس هناك ما يضمن الاحتفاظ بـ 4 مفاتيح مصغّرة للتصغير. |
|
priority |
اختياري، سلسلة | لضبط أولوية الرسالة. القيمتان الصالحتان هما "عادي" و "مرتفع". على منصات Apple، تتوافق هذه مع الأولويات 5 و10 لأسماء نقاط الوصول. بشكل افتراضي، يتم إرسال رسائل الإشعارات ذات أولوية عالية، ويتم إرسال رسائل البيانات بأولوية عادية. تعمل الأولوية العادية على تحسين استهلاك بطارية تطبيق العميل ويجب استخدامها ما لم يكن التسليم الفوري مطلوبًا. بالنسبة إلى الرسائل ذات الأولوية العادية، قد يتلقّى التطبيق الرسالة بتأخير غير محدّد. عند إرسال رسالة ذات أولوية عالية، يتم إرسالها على الفور، ويمكن للتطبيق عرض إشعار. |
|
content_available |
اختياري، منطقية | على منصات Apple، استخدِم هذا الحقل لتمثيل |
|
mutable_content |
اختياري، قيمة JSON منطقية | على منصات Apple، استخدِم هذا الحقل لتمثيل
|
|
time_to_live |
اختياري، رقم | تحدد هذه المعلمة المدة (بالثواني) التي يجب الاحتفاظ بالرسالة في مساحة تخزين FCM إذا كان الجهاز غير متصل بالإنترنت. الحد الأقصى لوقت توفّر الدعم هو 4 أسابيع، والقيمة التلقائية هي 4 أسابيع. لمزيد من المعلومات، يُرجى الاطّلاع على ضبط عمر الرسالة. |
|
dry_run |
اختياري، منطقية | وعند ضبط هذه المَعلمة على ستكون القيمة التلقائية |
|
الحمولة | |||
data |
عنصر اختياري | تحدد هذه المعلمة أزواج المفتاح/القيمة لحمولة الرسالة. مثلاً، باستخدام " على أنظمة Apple الأساسية، إذا تم تسليم الرسالة من خلال أسماء نقاط الوصول (APN)، فإنّها تمثِّل حقول البيانات المخصّصة. إذا تم إرسالها من خلال ميزة "المراسلة عبر السحابة الإلكترونية من Firebase"، يتم تمثيلها كقاموس قيمة رئيسية في على نظام التشغيل Android، ينتج عن ذلك هدف إضافي باسم يجب ألا يكون المفتاح كلمة محجوزة ("from" أو "message_type" أو أي كلمة تبدأ بـ "google" أو "gcm"). لا تستخدِم أيًا من الكلمات المحدّدة في هذا الجدول
(مثل ويُنصَح باستخدام القيم في أنواع السلاسل. وعليك تحويل القيم في العناصر أو أنواع البيانات الأخرى التي ليست سلسلة (مثل الأعداد الصحيحة أو القيم المنطقية) إلى سلسلة. |
|
notification |
عنصر اختياري | تحدّد هذه المَعلمة أزواج المفتاح/القيمة المحدّدة مسبقًا والمرئية للمستخدم
لحمولة الإشعارات. يمكنك الاطّلاع على إمكانية استخدام حمولة الإشعارات لمعرفة التفاصيل. لمزيد من المعلومات
حول خيارات رسالة الإشعار ورسائل البيانات، يُرجى الاطّلاع على
أنواع الرسائل. في حال تقديم حمولة الإشعارات أو
ضبط الخيار content_available على true لإرسال رسالة إلى جهاز
Apple، يتم إرسال الرسالة من خلال أسماء نقاط الوصول (APN)، وإلا يتم إرسالها من خلال
خدمة "المراسلة عبر السحابة الإلكترونية من Firebase".
|
إتاحة حمولة الإشعارات
تسرد الجداول التالية المفاتيح المحددة مسبقًا المتاحة لإنشاء رسائل إشعارات لأنظمة Apple وAndroid.
المَعلمة | الاستخدام | الوصف |
---|---|---|
title |
اختياري، سلسلة |
عنوان الإشعار. لا يظهر هذا الحقل على الهواتف والأجهزة اللوحية. |
body |
اختياري، سلسلة |
النص الأساسي للإشعار. |
sound |
اختياري، سلسلة |
الصوت الذي سيتم تشغيله عندما يتلقّى الجهاز الإشعار.
سلسلة تحدّد الملفات الصوتية في الحزمة الرئيسية للتطبيق العميل أو في
مجلد |
badge |
اختياري، سلسلة |
قيمة الشارة التي تظهر على رمز تطبيق الشاشة الرئيسية. وفي حال عدم تحديد هذه السمة، لن تتغيّر الشارة.
وإذا تم ضبط قيمة الشارة على |
click_action |
اختياري، سلسلة |
يشير ذلك المصطلح إلى الإجراء المرتبط بالمستخدم الذي ينقر على الإشعار.
يتطابق مع القيمة |
subtitle |
اختياري، سلسلة |
العنوان الفرعي للإشعار. |
body_loc_key |
اختياري، سلسلة |
تمثّل هذه السمة مفتاح السلسلة الأساسية في موارد سلسلة التطبيق لاستخدامها في أقلمة النص الأساسي بما يناسب الأقلمة الحالية للمستخدم.
يتطابق مع القيمة يمكنك الاطّلاع على مرجع مفتاح حمولة البيانات و ترجمة محتوى الإشعارات عن بُعد للحصول على مزيد من المعلومات. |
body_loc_args |
اختياري، مصفوفة JSON كسلسلة |
قيم سلسلة متغيرة لاستخدامها بدلاً من محددات التنسيق في
يتطابق مع القيمة يمكنك الاطّلاع على مرجع مفتاح حمولة البيانات و ترجمة محتوى الإشعارات عن بُعد للحصول على مزيد من المعلومات. |
title_loc_key |
اختياري، سلسلة |
تمثّل هذه السمة مفتاح سلسلة العنوان في موارد سلسلة التطبيق المطلوب استخدامها لترجمة نص العنوان حسب الترجمة الحالية للمستخدم.
يتطابق مع القيمة يمكنك الاطّلاع على مرجع مفتاح حمولة البيانات و ترجمة محتوى الإشعارات عن بُعد للحصول على مزيد من المعلومات. |
title_loc_args |
اختياري، مصفوفة JSON كسلسلة |
قيم سلسلة المتغيّرات التي سيتم استخدامها بدلاً من محدّدات التنسيقات في
يتطابق مع القيمة يمكنك الاطّلاع على مرجع مفتاح حمولة البيانات و ترجمة محتوى الإشعارات عن بُعد للحصول على مزيد من المعلومات. |
المَعلمة | الاستخدام | الوصف |
---|---|---|
title |
اختياري، سلسلة |
عنوان الإشعار. |
body |
اختياري، سلسلة |
النص الأساسي للإشعار. |
android_channel_id |
اختياري، سلسلة |
معرّف القناة للإشعار (جديد في Android O). يجب أن ينشئ التطبيق قناة باستخدام معرّف القناة هذا قبل أن نتلقّى أي إشعار يتضمّن معرّف القناة هذا. إذا لم ترسل معرّف القناة هذا في الطلب، أو إذا لم ينشئ التطبيق معرّف القناة الذي قدّمته بعد، ستستخدم خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" معرّف القناة المحدّد في بيان التطبيق. |
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 |
اختياري، سلسلة |
يشير ذلك المصطلح إلى الإجراء المرتبط بالمستخدم الذي ينقر على الإشعار. يجب استخدام HTTPS لجميع قيم عناوين URL. |
تفسير رد على رسالة XMPP قبل استلام الرسالة
يستعرض الجدول التالي الحقول التي تظهر في رد رسالة XMPP التي تظهر في مرحلة متأخرة من الوقت.
المَعلمة | الاستخدام | الوصف |
---|---|---|
from |
مطلوب، سلسلة | تحدد هذه المعلمة الجهة التي أرسلت هذه الاستجابة. القيمة هي الرمز المميّز لتسجيل تطبيق العميل. |
message_id |
مطلوب، سلسلة | تحدد هذه المعلمة رسالة بشكل فريد في اتصال XMPP. القيمة هي سلسلة تعرّف الرسالة المرتبطة بشكل فريد. |
message_type |
مطلوب، سلسلة | تحدّد هذه المعلمة الرسالة في حال ضبط القيمة على |
error |
اختياري، سلسلة | تحدّد هذه المعلمة خطأ متعلقًا برسالة استلام البريد. ويتم ضبطها عندما تكون قيمة
message_type هي nack . راجِع الجدول 4 للحصول على التفاصيل. |
error_description |
اختياري، سلسلة | تقدّم هذه المَعلمة معلومات وصفية عن الخطأ. ويتم ضبطها عندما تكون قيمة message_type هي nack . |
رموز الاستجابة للأخطاء التي تحدث في مرحلة متأخرة من الوقت
يسرد الجدول التالي رموز الاستجابة للأخطاء للرسائل التي تلي استلام البريد.
خطأ | رمز XMPP | الإجراء المقترَح |
---|---|---|
الرمز المميّز للتسجيل غير متوفّر | INVALID_JSON |
تأكَّد من أنّ الطلب يتضمّن رمزًا مميّزًا للتسجيل (في
registration_id في رسالة نصية عادية، أو في الحقل to
أو registration_ids بتنسيق JSON). |
تسجيل أسماء نقاط الوصول غير صالح | INVALID_JSON |
بالنسبة إلى عمليات التسجيل على أجهزة iOS، تأكَّد من أنّ طلب التسجيل المقدَّم من العميل يحتوي على معرّف تطبيق ورمز مميّزَين صالحَين لاسم نقطة الوصول (APN). |
الرمز المميّز للتسجيل غير صالح | BAD_REGISTRATION |
تحقَّق من تنسيق الرمز المميّز للتسجيل الذي تمرِّره إلى الخادم. يجب التأكّد من تطابق الرمز مع رمز التسجيل الذي يتلقّاه تطبيق العميل من التسجيل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". لا تقتطع أو تضيف أحرفًا إضافية. |
جهاز غير مسجَّل | DEVICE_UNREGISTERED |
قد يصبح الرمز المميّز الحالي للتسجيل غير صالح في عدد من السيناريوهات، بما في ذلك:
|
المُرسِل غير متطابق | SENDER_ID_MISMATCH |
ويرتبط الرمز المميّز للتسجيل بمجموعة معيّنة من المُرسِلين. عندما يسجِّل تطبيق عميل في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، يجب تحديد المرسِلين المسموح لهم بإرسال الرسائل. يجب استخدام أحد معرّفات المُرسِلين هذه عند إرسال الرسائل إلى تطبيق العميل. إذا بدّلت إلى مُرسِل مختلف، لن تعمل الرموز المميّزة الحالية للتسجيل. |
ملف JSON غير صالح | INVALID_JSON |
تحقَّق من أنّ رسالة JSON منسّقة بشكلٍ صحيح وتحتوي على حقول صالحة (على سبيل المثال، التأكّد من إدخال نوع البيانات الصحيح). |
الرسالة كبيرة جدًا. | INVALID_JSON |
تحقَّق من أن الحجم الإجمالي لبيانات الحمولة المضمّنة في الرسالة لا يتجاوز حدود "المراسلة عبر السحابة الإلكترونية من Firebase": 4096 بايت لمعظم الرسائل أو 2048 بايت في حالة الرسائل الموجَّهة إلى المواضيع. يتضمن ذلك كلاً من المفاتيح والقيم. |
مفتاح بيانات غير صالح | INVALID_JSON |
تأكَّد من أنّ بيانات الحمولة لا تحتوي على مفتاح (مثل from أو gcm أو أي قيمة يبدأها google ) تستخدمه خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" داخليًا. يُرجى العلم أنّ بعض الكلمات (مثل collapse_key )
تُستخدَم أيضًا من خلال خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، ولكن يُسمح باستخدامها في الحمولة، وفي هذه الحالة
يتم تجاهل قيمة الحمولة من خلال قيمة "المراسلة عبر السحابة الإلكترونية من Firebase". |
مدة البقاء غير صالحة | INVALID_JSON |
تأكَّد من أنّ القيمة المستخدَمة في time_to_live هي عدد صحيح يمثّل مدة بالثواني بين 0 و2419,200 (4 أسابيع). |
رسالة ACK غير صالحة | BAD_ACK |
يُرجى التأكّد من أنّ الرسالة ack منسّقة بشكل صحيح قبل إعادة المحاولة. راجِع الجدول 6 لمعرفة التفاصيل. |
وقت مستقطع | SERVICE_UNAVAILABLE |
لم يتمكّن الخادم من معالجة الطلب في الوقت المناسب. يُرجى إعادة محاولة الطلب نفسه، ولكن يجب:
ملاحظة: قد يُدرج المرسلون الذين يسببون مشاكل في قائمة سوداء. |
خطأ في الخادم الداخلي | INTERNAL_SERVER_
|
حدث خطأ في الخادم أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة تقديم الطلب نفسه باتّباع المتطلبات المذكورة في "المهلة" (راجِع الصف أعلاه). |
تم تجاوز معدّل الرسائل على الجهاز | DEVICE_MESSAGE_RATE |
معدّل الرسائل إلى جهاز معيّن مرتفع جدًا. قلِّل عدد الرسائل المُرسَلة إلى هذا الجهاز ولا تعيد محاولة الإرسال إليه على الفور. |
تم تجاوز معدل رسائل الموضوعات | TOPICS_MESSAGE_RATE |
معدل الرسائل الموجهة إلى المشتركين في موضوع معين مرتفع جدًا. قلّل عدد الرسائل المرسلة لهذا الموضوع، ولا تحاول الإرسال مجددًا على الفور. |
استنزاف الاتصال | CONNECTION_DRAINING |
تعذّرت معالجة الرسالة لأنّ الاتصال ينفد. يحدث ذلك لأنّه تحتاج خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" بشكل دوري إلى إغلاق الاتصال لتنفيذ موازنة التحميل. أعد محاولة إرسال الرسالة عبر اتصال XMPP آخر. |
بيانات اعتماد أسماء نقاط الوصول غير صالحة. | INVALID_APNS_CREDENTIAL |
تعذَّر إرسال رسالة موجَّهة إلى جهاز iOS بسبب عدم تحميل مفتاح المصادقة المطلوب لأسماء نقاط الوصول (APN) أو انتهت صلاحيته. تحقق من صحة بيانات اعتماد التطوير والإنتاج. |
تعذّرت المصادقة. | AUTHENTICATION_FAILED |
تعذّرت المصادقة باستخدام خدمات الدفع الخارجية. تأكَّد مما إذا كنت تستخدم شهادات Web Push الصحيحة. |
بنية الرسالة الرئيسية
الرسالة الأولية هي رسالة يرسلها تطبيق العميل إلى خادم التطبيق. لا تتوافق حاليًا سوى XMPP مع رسائل البث. راجِع مستندات النظام الأساسي للاطّلاع على مزيد من المعلومات حول إرسال الرسائل من تطبيقات العميل.
تفسير رسالة XMPP رئيسية
يوضِّح الجدول التالي الحقول في نسخة XMPP التي أنشأتها ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" استجابةً لطلبات الرسائل الأولية من تطبيقات العميل.
المَعلمة | الاستخدام | الوصف |
---|---|---|
from |
مطلوب، سلسلة | تحدد هذه المعلمة الشخص الذي أرسل الرسالة. القيمة هي الرمز المميّز لتسجيل تطبيق العميل. |
category |
مطلوب، سلسلة | تُحدِّد هذه المَعلمة اسم حزمة التطبيق الخاص بتطبيق العميل الذي أرسل الرسالة. |
message_id |
مطلوب، سلسلة | تحدّد هذه المعلمة المُعرّف الفريد للرسالة. |
data |
اختياري، سلسلة | تحدد هذه المعلمة أزواج المفتاح/القيمة لحمولة الرسالة. |
إرسال رسالة ACK
يوضّح الجدول التالي استجابة ACK التي من المتوقّع أن يرسلها خادم التطبيق إلى FCM ردًا على رسالة رئيسية تلقّاها خادم التطبيق.
المَعلمة | الاستخدام | الوصف |
---|---|---|
to |
مطلوب، سلسلة | تحدد هذه المعلمة مستلم رسالة الرد. يجب أن تكون القيمة رمزًا مميزًا لتسجيل تطبيق العميل الذي أرسل الرسالة الرئيسية. |
message_id |
مطلوب، سلسلة | تحدد هذه المعلمة الرسالة المخصصة للرد. يجب أن تكون القيمة هي message_id من الرسالة الرئيسية المقابلة. |
message_type |
مطلوب، سلسلة | تحدِّد هذه المَعلمة رسالة ack من خادم تطبيق إلى CCS.
بالنسبة إلى الرسائل الأولية، يجب ضبطها دائمًا على ack . |
رسائل خادم "المراسلة عبر السحابة الإلكترونية من Firebase" (XMPP)
هذه رسالة مُرسَلة من خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" إلى خادم تطبيق. في ما يلي الأنواع الأساسية للرسائل التي ترسلها خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" إلى خادم التطبيقات:
- التحكّم: تشير هذه الرسائل التي تم إنشاؤها من خلال CCS إلى أنّ خادم التطبيق مطلوب اتّخاذ إجراء.
يوضّح الجدول التالي الحقول المضمّنة في الرسائل التي ترسلها خدمة CCS إلى خادم التطبيق.
المَعلمة | الاستخدام | الوصف |
---|---|---|
حقل مشترك | ||
message_type |
مطلوب، سلسلة | تحدد هذه المعلمة نوع الرسالة: Control. وعند ضبطها على |
control_type |
اختياري، سلسلة | تحدد هذه المعلمة نوع رسالة التحكم المرسلة من "المراسلة عبر السحابة الإلكترونية من Firebase". في الوقت الحالي، يُسمح فقط باستخدام |