يوفر هذا المستند مرجعًا لبناء جملة HTTP المستخدم لتمرير الرسائل من خادم التطبيق الخاص بك إلى تطبيقات العميل عبر Firebase Cloud Messaging.
عند استخدام بروتوكول HTTP القديم، يجب على خادم التطبيق الخاص بك توجيه جميع طلبات HTTP إلى نقطة النهاية هذه:
https://fcm.googleapis.com/fcm/send
تنقسم المعلمات والخيارات المتاحة إلى الفئات العامة التالية:
بناء جملة الرسالة المتلقين للمعلومات
يقدم هذا القسم بناء الجملة لإرسال الرسائل النهائية وتفسير استجابات HTTP من Firebase Cloud Messaging.
رسائل HTTP النهائية (JSON)
يسرد الجدول التالي الأهداف والخيارات والحمولة لرسائل HTTP JSON.
معامل | الاستخدام | وصف | |
---|---|---|---|
الأهداف | |||
to | اختياري، سلسلة | تحدد هذه المعلمة مستلم الرسالة. يمكن أن تكون القيمة عبارة عن رمز مميز لتسجيل الجهاز، أو مفتاح إعلام لمجموعة أجهزة، أو موضوع واحد (يسبقه | |
registration_ids | اختياري، مجموعة من السلاسل | تحدد هذه المعلمة مستلم رسالة البث المتعدد، وهي رسالة يتم إرسالها إلى أكثر من رمز مميز للتسجيل. يجب أن تكون القيمة عبارة عن مجموعة من رموز التسجيل التي سيتم إرسال رسالة البث المتعدد إليها. يجب أن يحتوي المصفوفة على رمز تسجيل واحد على الأقل وعلى 1000 رمز مميز على الأكثر. لإرسال رسالة إلى جهاز واحد، استخدم المعلمة يُسمح برسائل البث المتعدد فقط باستخدام تنسيق HTTP JSON. | |
condition | اختياري، سلسلة | تحدد هذه المعلمة تعبيرًا منطقيًا للشروط التي تحدد هدف الرسالة. الحالة المدعومة: الموضوع، بتنسيق "'yourTopic' في المواضيع". هذه القيمة غير حساسة لحالة الأحرف. عوامل التشغيل المدعومة: | |
notification_key إهمال | اختياري، سلسلة | تم إهمال هذه المعلمة. بدلاً من ذلك، استخدم | |
خيارات | |||
collapse_key | اختياري، سلسلة | تحدد هذه المعلمة مجموعة من الرسائل (على سبيل المثال، مع لاحظ أنه لا يوجد ضمان للترتيب الذي يتم به إرسال الرسائل. ملحوظة: يُسمح بحد أقصى 4 مفاتيح طي مختلفة في أي وقت. وهذا يعني أن FCM يمكنها تخزين 4 رسائل مختلفة لكل تطبيق عميل في وقت واحد. إذا تجاوزت هذا الرقم، فليس هناك ضمان بشأن المفاتيح الأربعة التي ستحتفظ بها FCM. | |
priority | اختياري، سلسلة | يحدد أولوية الرسالة. القيم الصالحة هي "عادية" و"عالية". على منصات Apple، تتوافق هذه مع أولويات APN 5 و10. افتراضيًا، يتم إرسال رسائل الإعلام بأولوية عالية، ويتم إرسال رسائل البيانات بأولوية عادية. تعمل الأولوية العادية على تحسين استهلاك بطارية تطبيق العميل ويجب استخدامها ما لم يكن التسليم الفوري مطلوبًا. بالنسبة للرسائل ذات الأولوية العادية، قد يتلقى التطبيق الرسالة بتأخير غير محدد. عندما يتم إرسال رسالة ذات أولوية عالية، يتم إرسالها على الفور، ويمكن للتطبيق عرض إشعار. | |
content_available | اختياري، منطقي | على أنظمة Apple الأساسية، استخدم هذا الحقل لتمثيل | |
mutable_content | اختياري، JSON منطقي | على أنظمة Apple الأساسية، استخدم هذا الحقل لتمثيل | |
time_to_live | اختياري، الرقم | تحدد هذه المعلمة المدة (بالثواني) التي يجب أن تبقى فيها الرسالة في وحدة تخزين FCM إذا كان الجهاز غير متصل بالإنترنت. الحد الأقصى لوقت البقاء مدعومًا هو 4 أسابيع، والقيمة الافتراضية هي 4 أسابيع. لمزيد من المعلومات، راجع تعيين مدة الرسالة . | |
restricted_package_ (Android فقط) | اختياري، سلسلة | تحدد هذه المعلمة اسم حزمة التطبيق حيث يجب أن تتطابق رموز التسجيل المميزة لتلقي الرسالة. | |
dry_run | اختياري، منطقي | تسمح هذه المعلمة، عند ضبطها على القيمة الافتراضية هي | |
الحمولة | |||
data | اختياري، كائن | تحدد هذه المعلمة أزواج قيمة المفتاح المخصصة لحمولة الرسالة. على سبيل المثال، مع على منصات Apple، إذا تم إرسال الرسالة عبر APNs، فإنها تمثل حقول البيانات المخصصة. إذا تم إرساله عبر FCM، فسيتم تمثيله كقاموس قيمة مفتاح في على Android، قد يؤدي هذا إلى يجب ألا يكون المفتاح كلمة محجوزة ("from"، أو "message_type"، أو أي كلمة تبدأ بـ "google" أو "gcm"). لا تستخدم أيًا من الكلمات المحددة في هذا الجدول (مثل يوصى باستخدام القيم في أنواع السلسلة. يجب عليك تحويل القيم الموجودة في الكائنات أو أنواع البيانات غير النصية الأخرى (على سبيل المثال، الأعداد الصحيحة أو القيم المنطقية) إلى سلسلة. | |
notification | اختياري، كائن | تحدد هذه المعلمة أزواج قيمة المفتاح المحددة مسبقًا والمرئية للمستخدم لحمولة الإشعارات. راجع دعم حمولة الإشعارات للحصول على التفاصيل. لمزيد من المعلومات حول خيارات رسائل الإعلام ورسائل البيانات، راجع أنواع الرسائل . إذا تم توفير حمولة إعلام، أو تم تعيين الخيار content_available على true لرسالة إلى جهاز Apple، فسيتم إرسال الرسالة عبر APNs ، وإلا فسيتم إرسالها عبر FCM. |
دعم حمولة الإخطار
تسرد الجداول التالية المفاتيح المحددة مسبقًا المتوفرة لإنشاء رسائل الإشعارات لنظامي التشغيل iOS و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. |
رسائل HTTP النهائية (نص عادي)
يسرد الجدول التالي بناء جملة الأهداف والخيارات والحمولة في رسائل HTTP ذات النص العادي.
معامل | الاستخدام | وصف |
---|---|---|
الأهداف | ||
registration_id | مطلوب، سلسلة | تحدد هذه المعلمة تطبيقات العميل (الرمز المميز للتسجيل) التي تتلقى الرسالة. يُسمح بمراسلة البث المتعدد (الإرسال إلى أكثر من رمز مميز للتسجيل) باستخدام تنسيق HTTP JSON فقط. |
خيارات | ||
collapse_key | اختياري، سلسلة | انظر الجدول 1 للحصول على التفاصيل. |
time_to_live | اختياري، الرقم | انظر الجدول 1 للحصول على التفاصيل. |
restricted_package_name | اختياري، سلسلة | انظر الجدول 1 للحصول على التفاصيل. |
dry_run | اختياري، منطقي | انظر الجدول 1 للحصول على التفاصيل. |
الحمولة | ||
data.<key> | اختياري، سلسلة | تحدد هذه المعلمة أزواج القيمة الرئيسية لحمولة الرسالة. لا يوجد حد لعدد معلمات قيمة المفتاح، ولكن يوجد حد إجمالي لحجم الرسالة يبلغ 4000 بايت. على سبيل المثال، في Android، قد يؤدي يجب ألا يكون المفتاح كلمة محجوزة ("from"، أو "message_type"، أو أي كلمة تبدأ بـ "google" أو "gcm"). لا تستخدم أيًا من الكلمات المحددة في هذا الجدول (مثل |
تفسير استجابة الرسالة المتلقين للمعلومات
يجب أن يقوم خادم التطبيق بتقييم كل من رأس استجابة الرسالة والنص الأساسي لتفسير استجابة الرسالة المرسلة من FCM. يصف الجدول التالي الاستجابات المحتملة.
إجابة | وصف |
---|---|
200 | تمت معالجة الرسالة بنجاح. سيحتوي نص الاستجابة على مزيد من التفاصيل حول حالة الرسالة، ولكن تنسيقها سيعتمد على ما إذا كان الطلب بتنسيق JSON أو نصًا عاديًا. انظر الجدول 5 لمزيد من التفاصيل. |
400 | ينطبق فقط على طلبات JSON. يشير إلى أنه لا يمكن تحليل الطلب كـ JSON، أو أنه يحتوي على حقول غير صالحة (على سبيل المثال، تمرير سلسلة حيث كان من المتوقع رقم). تم وصف سبب الفشل الدقيق في الرد ويجب معالجة المشكلة قبل إعادة محاولة الطلب. |
401 | حدث خطأ أثناء مصادقة حساب المرسل. |
5xx | تشير الأخطاء في النطاق 500-599 (مثل 500 أو 503) إلى وجود خطأ داخلي في الواجهة الخلفية لـ FCM أثناء محاولة معالجة الطلب، أو إلى أن الخادم غير متاح مؤقتًا (على سبيل المثال، بسبب انتهاء المهلات). يجب على المرسل إعادة المحاولة لاحقًا، مع مراعاة أي رأس Retry-After المضمن في الرد. يجب أن تقوم خوادم التطبيقات بتنفيذ التراجع الأسي. |
يسرد الجدول التالي الحقول الموجودة في نص استجابة الرسالة المتلقين للمعلومات (JSON).
معامل | الاستخدام | وصف |
---|---|---|
multicast_id | رقم مطلوب | معرف فريد (رقم) يحدد رسالة البث المتعدد. |
success | رقم مطلوب | عدد الرسائل التي تمت معالجتها بدون خطأ. |
failure | رقم مطلوب | عدد الرسائل التي لا يمكن معالجتها. |
results | مطلوب، مجموعة من الكائنات | صفيف من الكائنات التي تمثل حالة الرسائل التي تمت معالجتها. يتم إدراج الكائنات بنفس ترتيب الطلب (على سبيل المثال، لكل معرف تسجيل في الطلب، يتم إدراج نتيجته في نفس الفهرس في الاستجابة).
|
معامل | الاستخدام | وصف |
---|---|---|
message_id | اختياري، الرقم | معرف رسالة الموضوع عندما تتلقى FCM الطلب بنجاح وتحاول تسليمه إلى جميع الأجهزة المشتركة. |
error | اختياري، سلسلة | حدث خطأ أثناء معالجة الرسالة. ويمكن الاطلاع على القيم المحتملة في الجدول 9 . |
معامل | الاستخدام | وصف |
---|---|---|
id | مطلوب، سلسلة | تحدد هذه المعلمة معرف الرسالة الفريد الذي تمت معالجة FCM بنجاح. |
registration_id | اختياري، سلسلة | تحدد هذه المعلمة رمز التسجيل لتطبيق العميل الذي تمت معالجة الرسالة وإرسالها إليه. |
معامل | الاستخدام | وصف |
---|---|---|
Error | مطلوب، سلسلة | تحدد هذه المعلمة قيمة الخطأ أثناء معالجة الرسالة للمستلم. انظر الجدول 9 للحصول على التفاصيل. |
رموز الاستجابة لخطأ الرسالة المتلقين للمعلومات
يسرد الجدول التالي رموز استجابة الخطأ للرسائل المتلقية للمعلومات.
خطأ | رمز HTTP | الإجراء الموصى به |
---|---|---|
رمز التسجيل مفقود | 200 + خطأ: التسجيل مفقود | تأكد من أن الطلب يحتوي على رمز تسجيل مميز (في registration_id في رسالة نصية عادية، أو في الحقل to أو registration_ids في JSON). |
رمز التسجيل غير صالح | 200 + خطأ: التسجيل غير صالح | تحقق من تنسيق رمز التسجيل الذي تقوم بتمريره إلى الخادم. تأكد من أنه يطابق رمز التسجيل الذي يتلقاه تطبيق العميل من التسجيل في Firebase Notifications. لا تقم باقتطاع أو إضافة أحرف إضافية. |
جهاز غير مسجل | 200 + خطأ: غير مسجل | قد لا يعد رمز التسجيل الحالي صالحًا في عدد من السيناريوهات، بما في ذلك:
|
اسم الحزمة غير صالح | 200 + خطأ: اسم الحزمة غير صالح | تأكد من أن الرسالة موجهة إلى رمز التسجيل الذي يتطابق اسم الحزمة الخاص به مع القيمة التي تم تمريرها في الطلب. |
خطأ مصادقة | 401 | لا يمكن مصادقة حساب المرسل المستخدم لإرسال الرسالة. الأسباب المحتملة هي:
|
مرسل غير متطابق | 200 + خطأ: MismatchSenderId | يرتبط رمز التسجيل بمجموعة معينة من المرسلين. عندما يقوم تطبيق عميل بالتسجيل في FCM، يجب عليه تحديد المرسلين المسموح لهم بإرسال الرسائل. يجب عليك استخدام أحد معرفات المرسل عند إرسال الرسائل إلى تطبيق العميل. إذا قمت بالتبديل إلى مرسل مختلف، فلن تعمل رموز التسجيل الحالية. |
تنسيق JSON غير صالح | 400 | تأكد من أن رسالة JSON منسقة بشكل صحيح وتحتوي على حقول صالحة (على سبيل المثال، التأكد من تمرير نوع البيانات الصحيح). |
معلمات غير صالحة | 400 + خطأ: معلمات غير صالحة | تأكد من أن المعلمات المقدمة لها الاسم والنوع الصحيحين. |
الرسالة كبيرة جدًا | 200 + خطأ:MessageTooBig | تأكد من أن الحجم الإجمالي لبيانات الحمولة المضمنة في الرسالة لا يتجاوز حدود FCM: 4096 بايت لمعظم الرسائل، أو 2048 بايت في حالة الرسائل الموجهة إلى المواضيع. يتضمن ذلك المفاتيح والقيم. |
مفتاح البيانات غير صالح | 200 + خطأ: مفتاح البيانات غير صالح | تأكد من أن بيانات الحمولة لا تحتوي على مفتاح (مثل from أو gcm أو أي قيمة تسبقها google ) يتم استخدامه داخليًا بواسطة FCM. لاحظ أن بعض الكلمات (مثل collapse_key ) تُستخدم أيضًا بواسطة FCM ولكنها مسموح بها في الحمولة النافعة، وفي هذه الحالة سيتم تجاوز قيمة الحمولة النافعة بقيمة FCM. |
وقت غير صالح للعيش | 200 + خطأ: InvalidTtl | تأكد من أن القيمة المستخدمة في time_to_live هي عدد صحيح يمثل مدة بالثواني تتراوح بين 0 و2,419,200 (4 أسابيع). |
نفذ الوقت | خطأ 5xx أو 200 +: غير متاح | تعذر على الخادم معالجة الطلب في الوقت المناسب. أعد محاولة نفس الطلب، لكن يجب عليك:
المرسلون الذين يتسببون في حدوث مشكلات يتعرضون لخطر إدراجهم في القائمة السوداء. |
خطأ في الخادم الداخلي | 500 أو 200 + خطأ: خطأ داخلي في الخادم | واجه الخادم خطأ أثناء محاولة معالجة الطلب. يمكنك إعادة محاولة نفس الطلب باتباع المتطلبات المدرجة في "المهلة" (انظر الصف أعلاه). إذا استمر الخطأ، فيرجى الاتصال بدعم Firebase . |
تم تجاوز معدل رسالة الجهاز | 200 + خطأ: معدل رسالة الجهاز تجاوزت | معدل الرسائل إلى جهاز معين مرتفع جدًا. إذا أرسل أحد تطبيقات Apple رسائل بمعدل يتجاوز حدود APN، فقد يتلقى رسالة الخطأ هذه قم بتقليل عدد الرسائل المرسلة إلى هذا الجهاز واستخدم التراجع الأسي لإعادة محاولة الإرسال. |
تم تجاوز معدل رسائل المواضيع | 200 + خطأ: معدل الرسائل تجاوزت | معدل الرسائل للمشتركين في موضوع معين مرتفع جدًا. قم بتقليل عدد الرسائل المرسلة لهذا الموضوع واستخدم التراجع الأسي لإعادة محاولة الإرسال. |
بيانات اعتماد APNs غير صالحة | 200 + خطأ: بيانات اعتماد غير صالحة | تعذر إرسال رسالة موجهة إلى جهاز Apple لأنه لم يتم تحميل مفتاح مصادقة APN المطلوب أو انتهت صلاحيته. تحقق من صحة بيانات اعتماد التطوير والإنتاج الخاصة بك. |
إدارة مجموعة الأجهزة
يسرد الجدول التالي المفاتيح الخاصة بإنشاء مجموعات الأجهزة وإضافة الأعضاء وإزالتهم. لمزيد من المعلومات، راجع الدليل الخاص بنظامك الأساسي، iOS+ أو Android .
معامل | الاستخدام | وصف |
---|---|---|
operation | مطلوب، سلسلة | عملية التشغيل. القيم الصالحة هي create add remove . |
notification_key_name | مطلوب، سلسلة | الاسم المحدد من قبل المستخدم لمجموعة الأجهزة المراد إنشاؤها أو تعديلها. |
notification_key | مطلوب (باستثناء عملية create ، string | المعرف الفريد لمجموعة الأجهزة. يتم إرجاع هذه القيمة في الاستجابة لعملية create الناجحة، وهي مطلوبة لجميع العمليات اللاحقة على مجموعة الأجهزة. |
registration_ids | مطلوب، مجموعة من السلاسل | الرموز المميزة للجهاز لإضافة أو إزالة. إذا قمت بإزالة جميع رموز التسجيل الموجودة من مجموعة أجهزة، فستحذف FCM مجموعة الأجهزة. |