يوفر هذا المستند مرجعًا لبناء جملة XMPP المستخدم لتمرير الرسائل بين خادم التطبيق وتطبيقات العميل وFirebase Cloud Messaging (FCM). يجب أن يتصل خادم التطبيق الخاص بك بنقاط النهاية هذه:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
تقع المعلمات والخيارات المتاحة ضمن هذه الفئات:
- بناء جملة الرسالة المتلقين للمعلومات
- رموز الاستجابة لخطأ الرسالة المتلقين للمعلومات
- بناء جملة الرسالة المنبع
- رسائل التحكم FCM
بناء جملة الرسالة المتلقين للمعلومات
يقدم هذا القسم بناء الجملة لإرسال الرسائل النهائية.
رسائل XMPP المتلقية للمعلومات (JSON)
يسرد الجدول التالي الأهداف والخيارات والحمولة لرسائل XMPP JSON.
معامل | الاستخدام | وصف | |
---|---|---|---|
هدف | |||
to | اختياري، سلسلة | تحدد هذه المعلمة مستلم الرسالة. يمكن أن تكون القيمة عبارة عن رمز مميز لتسجيل الجهاز، أو مفتاح إعلام لمجموعة أجهزة، أو موضوع واحد (يسبقه | |
condition | اختياري، سلسلة | تحدد هذه المعلمة تعبيرًا منطقيًا للشروط التي تحدد هدف الرسالة. الحالة المدعومة: الموضوع، بتنسيق "'yourTopic' في المواضيع". هذه القيمة غير حساسة لحالة الأحرف. عوامل التشغيل المدعومة: | |
خيارات | |||
message_id | مطلوب، سلسلة | تحدد هذه المعلمة الرسالة بشكل فريد في اتصال XMPP. | |
collapse_key | اختياري، سلسلة | تحدد هذه المعلمة مجموعة من الرسائل (على سبيل المثال، مع ليس هناك ضمان للترتيب الذي يتم به إرسال الرسائل. ملحوظة: يُسمح بحد أقصى 4 مفاتيح طي مختلفة في أي وقت. وهذا يعني أن FCM يمكنها تخزين 4 رسائل مختلفة في وقت واحد لكل تطبيق عميل. إذا تجاوزت هذا الرقم، فليس هناك ضمان بشأن المفاتيح الأربعة التي ستحتفظ بها FCM. | |
priority | اختياري، سلسلة | يحدد أولوية الرسالة. القيم الصالحة هي "عادية" و"عالية". على منصات Apple، تتوافق هذه مع أولويات APN 5 و10. افتراضيًا، يتم إرسال رسائل الإعلام بأولوية عالية، ويتم إرسال رسائل البيانات بأولوية عادية. تعمل الأولوية العادية على تحسين استهلاك بطارية تطبيق العميل ويجب استخدامها ما لم يكن التسليم الفوري مطلوبًا. بالنسبة للرسائل ذات الأولوية العادية، قد يتلقى التطبيق الرسالة بتأخير غير محدد. عندما يتم إرسال رسالة ذات أولوية عالية، يتم إرسالها على الفور، ويمكن للتطبيق عرض إشعار. | |
content_available | اختياري، منطقي | على أنظمة Apple الأساسية، استخدم هذا الحقل لتمثيل | |
mutable_content | اختياري، JSON منطقي | على أنظمة Apple الأساسية، استخدم هذا الحقل لتمثيل | |
time_to_live | اختياري، الرقم | تحدد هذه المعلمة المدة (بالثواني) التي يجب أن تبقى فيها الرسالة في وحدة تخزين FCM إذا كان الجهاز غير متصل بالإنترنت. الحد الأقصى لوقت البقاء مدعومًا هو 4 أسابيع، والقيمة الافتراضية هي 4 أسابيع. لمزيد من المعلومات، راجع تعيين مدة الرسالة . | |
dry_run | اختياري، منطقي | تسمح هذه المعلمة، عند ضبطها على القيمة الافتراضية هي | |
الحمولة | |||
data | اختياري، كائن | تحدد هذه المعلمة أزواج القيمة الرئيسية لحمولة الرسالة. على سبيل المثال، مع على منصات Apple، إذا تم تسليم الرسالة بواسطة APNs، فإنها تمثل حقول البيانات المخصصة. إذا تم تسليمه بواسطة FCM، فسيتم تمثيله كقاموس قيمة رئيسي في على Android، يؤدي هذا إلى يجب ألا يكون المفتاح كلمة محجوزة ("from"، أو "message_type"، أو أي كلمة تبدأ بـ "google" أو "gcm"). لا تستخدم أيًا من الكلمات المحددة في هذا الجدول (مثل يوصى باستخدام القيم في أنواع السلسلة. يجب عليك تحويل القيم الموجودة في الكائنات أو أنواع البيانات غير النصية الأخرى (على سبيل المثال، الأعداد الصحيحة أو القيم المنطقية) إلى سلسلة. | |
notification | اختياري، كائن | تحدد هذه المعلمة أزواج قيمة المفتاح المحددة مسبقًا والمرئية للمستخدم لحمولة الإشعارات. راجع دعم حمولة الإشعارات للحصول على التفاصيل. لمزيد من المعلومات حول خيارات رسائل الإعلام ورسائل البيانات، راجع أنواع الرسائل . إذا تم توفير حمولة إعلام، أو تم تعيين الخيار content_available على true لرسالة إلى جهاز Apple، فسيتم إرسال الرسالة عبر APNs ، وإلا فسيتم إرسالها عبر 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 | اختياري، سلسلة | الإجراء المرتبط بنقر المستخدم على الإشعار. بالنسبة لجميع قيم URL، يلزم استخدام HTTPS. |
تفسير استجابة رسالة 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). |
تسجيل APNs غير صالح | 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 و2,419,200 (4 أسابيع). |
رسالة ACK سيئة | BAD_ACK | تأكد من تنسيق رسالة ack بشكل صحيح قبل إعادة المحاولة. انظر الجدول 6 للحصول على التفاصيل. |
نفذ الوقت | SERVICE_UNAVAILABLE | تعذر على الخادم معالجة الطلب في الوقت المناسب. أعد محاولة نفس الطلب، لكن يجب عليك:
ملاحظة: المرسلون الذين يتسببون في حدوث مشكلات يتعرضون لخطر إدراجهم في القائمة السوداء. |
خطأ في الخادم الداخلي | INTERNAL_SERVER_ | واجه الخادم خطأ أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة نفس الطلب باتباع المتطلبات المذكورة في "المهلة" (انظر الصف أعلاه). |
تم تجاوز معدل رسالة الجهاز | DEVICE_MESSAGE_RATE | معدل الرسائل إلى جهاز معين مرتفع جدًا. قم بتقليل عدد الرسائل المرسلة إلى هذا الجهاز، ولا تحاول إرسالها مرة أخرى على الفور إلى هذا الجهاز. |
تم تجاوز معدل رسائل المواضيع | TOPICS_MESSAGE_RATE | معدل الرسائل للمشتركين في موضوع معين مرتفع جدًا. قم بتقليل عدد الرسائل المرسلة لهذا الموضوع، ولا تحاول إرسالها مرة أخرى على الفور. |
استنزاف الاتصال | CONNECTION_DRAINING | تعذرت معالجة الرسالة لأن الاتصال يستنزف. يحدث هذا لأن FCM تحتاج بشكل دوري إلى إغلاق الاتصال لإجراء موازنة التحميل. أعد محاولة إرسال الرسالة عبر اتصال XMPP آخر. |
بيانات اعتماد APNs غير صالحة | INVALID_APNS_CREDENTIAL | تعذر إرسال رسالة موجهة إلى جهاز iOS لأنه لم يتم تحميل مفتاح مصادقة APN المطلوب أو انتهت صلاحيته. تحقق من صحة بيانات اعتماد التطوير والإنتاج الخاصة بك. |
المصادقة فشلت | AUTHENTICATION_FAILED | فشلت المصادقة مع خدمات الدفع الخارجية. تحقق مما إذا كنت تستخدم شهادات دفع الويب الصحيحة. |
بناء جملة الرسالة المنبع
الرسالة الأولية هي رسالة يرسلها تطبيق العميل إلى خادم التطبيق. حاليًا، يدعم 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_type | اختياري، سلسلة | تحدد هذه المعلمة نوع رسالة التحكم المرسلة من FCM. حاليًا، يتم دعم |