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