يوفّر Firebase Cloud Messaging (FCM) مجموعة كبيرة من خيارات المراسلة والإمكانات. تهدف المعلومات الواردة في هذه الصفحة إلى مساعدتك في فهم الأنواع المختلفة من رسائل FCM والإجراءات التي يمكنك اتّخاذها بشأنها.
أنواع الرسائل
باستخدام FCM، يمكنك إرسال نوعَين من الرسائل إلى العملاء:
- رسائل الإشعارات، التي يُشار إليها أحيانًا باسم "رسائل العرض" تعالج حزمة تطوير البرامج (SDK) لنظام التشغيل FCM هذه العمليات تلقائيًا.
- رسائل البيانات التي يعالجها تطبيق العميل
تحتوي رسائل الإشعارات على مجموعة محدّدة مسبقًا من المفاتيح المرئية للمستخدم. في المقابل، لا تحتوي رسائل البيانات إلا على أزواج مفتاح/قيمة مخصّصة يحدّدها المستخدم. يمكن أن تحتوي رسائل الإشعارات على حمولة بيانات اختيارية. الحد الأقصى لحمولة كلا نوعَي الرسائل هو 4096 بايت، باستثناء حالة إرسال الرسائل من وحدة تحكّم Firebase التي تفرض حدودًا تبلغ 1,000 حرف.
سيناريو الاستخدام | كيفية الإرسال | |
---|---|---|
رسالة الإشعار | FCM تعرِض حزمة تطوير البرامج (SDK) الرسالة على أجهزة المستخدمين النهائيين بالنيابة عن تطبيق العميل عندما يكون قيد التشغيل في الخلفية. بخلاف ذلك، إذا كان التطبيق قيد التشغيل في المقدّمة عند تلقّي الإشعار، سيحدِّد رمز التطبيق السلوك. تحتوي رسائل الإشعارات على مجموعة محدّدة مسبقًا من المفاتيح المرئية للمستخدم وحمل بيانات اختيارية تتضمن أزواج مفاتيح/قيم مخصّصة. |
|
رسالة البيانات | يتحمّل تطبيق العميل مسؤولية معالجة رسائل البيانات. رسائل البيانات تحتوي فقط على أزواج مفتاح/قيمة مخصّصة بدون أسماء مفاتيح محجوزة (راجِع المعلومات أدناه). | في بيئة موثوق بها، مثل
Cloud Functions
أو خادم تطبيقك، استخدِم
Admin SDK أو
بروتوكولات خادم "خدمة إرسال الرسائل إلى الأجهزة الجوّالة من Google". في طلب الإرسال، اضبط المفتاح data .
|
استخدِم رسائل الإشعارات عندما تريد أن تتعامل حزمة SDK لنظام التشغيل FCM مع عرض إشعار تلقائيًا عندما يكون تطبيقك قيد التشغيل في الخلفية. استخدِم رسائل البيانات عندما تريد معالجة الرسائل باستخدام رمز تطبيق العميل الخاص بك.
يمكن أن يرسل FCM رسالة إشعار تتضمّن بيانات اختيارية في الحمولة الأساسية. في هذه الحالات، يعالج FCM عرض الحمولة للإشعار، ويعالج تطبيق العميل الحمولة للبيانات.
رسائل الإشعارات
لأغراض الاختبار أو التسويق وإعادة جذب المستخدمين، يمكنك إرسال رسائل إشعارات باستخدام وحدة تحكّم Firebase. توفّر وحدة تحكّم Firebase اختبار أ/ب المستنِد إلى الإحصاءات لمساعدتك في تحسين الرسائل التسويقية و تعديلها.
لإرسال رسائل الإشعارات آليًا باستخدام حزمة Admin SDK أو بروتوكولات
FCM، اضبط مفتاح notification
باستخدام
مجموعة الخيارات المحدّدة مسبقًا اللازمة لمفتاح القيمة للجزء
المرئي للمستخدم من رسالة الإشعار. على سبيل المثال، في ما يلي رسالة إشعار بتنسيق JSON
في تطبيق مراسلة فورية. يمكن أن يتوقع المستخدم ظهور
رسالة بعنوان "البرتغال ضد الدنمارك" والنص
"مباراة رائعة" على الجهاز:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "notification":{ "title":"Portugal vs. Denmark", "body":"great match!" } } }
يتم تسليم رسائل الإشعارات إلى علبة الإشعارات عندما يكون التطبيق في الخلفية. بالنسبة إلى التطبيقات التي تعمل في المقدّمة، تتم معالجة الرسائل من خلال دالة ردّ اتصال.
اطّلِع على مستندات مرجعية لكائن إشعار بروتوكول HTTP v1 للحصول على القائمة الكاملة للمفاتيح المحدّدة مسبقًا المتاحة لإنشاء رسائل إعلام.
رسائل البيانات
اضبط المفتاح المناسب باستخدام أزواج المفتاح/القيمة المخصّصة ل إرسال حمولة بيانات إلى تطبيق العميل.
على سبيل المثال، في ما يلي
رسالة بتنسيق JSON في تطبيق المراسلة الفورية نفسه أعلاه،
حيث يتم تضمين المعلومات في مفتاح data
الشائع
ومن المتوقّع أن يفسّر تطبيق العميل المحتوى:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "data":{ "Nick" : "Mario", "body" : "great match!", "Room" : "PortugalVSDenmark" } } }
يوضّح المثال أعلاه استخدام حقل المستوى الأعلى أو الحقل المشترك data
،
والذي يفسّره العملاء على جميع المنصّات التي تتلقّى الرسالة.
على كل نظام أساسي، يتلقّى تطبيق العميل الحمولة البرمجية للبيانات
في دالة ردّ اتصال.
تشفير رسائل البيانات
تستخدم طبقة النقل في Android (راجِع بنية FCM) التشفير من نقطة إلى نقطة. استنادًا إلى احتياجاتك، يمكنك إضافة التشفير من جهة إلى أخرى إلى رسائل البيانات. لا يوفّر FCM حلًا شاملاً. ومع ذلك، تتوفّر حلول خارجية، مثل Capillary أو DTLS.
رسائل الإشعارات التي تحتوي على حمولة بيانات اختيارية
يمكنك إرسال رسائل إعلام برمجيًا أو من خلال وحدة تحكّم Firebase تحتوي على حمولة اختيارية من أزواج مفتاح/قيمة مخصّصة. في أداة إنشاء الإشعارات، استخدِم حقول البيانات المخصّصة في الخيارات المتقدّمة.
يعتمد سلوك التطبيق عند تلقّي الرسائل التي تتضمّن حمولتَي الإشعارات والبيانات على ما إذا كان التطبيق يعمل في المقدّمة أو الخلفية، أي ما إذا كان نشطًا في وقت الاستلام أم لا.
- عندما تكون التطبيقات في الخلفية، تتلقّى التطبيقات الحمولة البرمجية للإشعار في علبة الإشعارات، ولا تعالج الحمولة البرمجية للبيانات إلا عندما يصنّد المستخدم على الإشعار.
- عندما يكون التطبيق في المقدّمة، يتلقّى عنصر رسالة يتوفّر فيه كلا الحمّلَين.
في ما يلي رسالة بتنسيق JSON تحتوي على كل من مفتاح
notification
ومفتاح data
:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "notification":{ "title":"Portugal vs. Denmark", "body":"great match!" }, "data" : { "Nick" : "Mario", "Room" : "PortugalVSDenmark" } } }
تخصيص رسالة على جميع المنصات
يسمح كل من Firebase Admin SDK وبروتوكول HTTP في الإصدار 1 من إطار عمل إدارة إشعارات Google (FCM) لطلبات الرسائل
بضبط جميع الحقول المتاحة في كائن
message
. ويشمل ذلك ما يلي:
- مجموعة شائعة من الحقول التي ستفسّرها جميع نُسخ التطبيق التيتلقّى الرسالة
- مجموعات الحقول الخاصة بالمنصة، مثل
AndroidConfig
وWebpushConfig
، التي لا تفسّرها سوى نُسخ التطبيق التي تعمل على المنصة المحدّدة
تمنحك الكتل الخاصة بالنظام الأساسي مرونة في تخصيص الرسائل لمختلف المنصات لضمان معالجتها بشكل صحيح عند تلقّيها. ستأخذ المعالجة الخلفية لـ FCM جميع المَعلمات المحدّدة في الاعتبار وستخصّص الرسالة لكل منصة.
حالات استخدام الحقول الشائعة
استخدِم الحقول الشائعة في الحالات التالية:
- استهداف نُسخ التطبيق على جميع الأنظمة الأساسية، مثل Apple وAndroid والويب
- إرسال الرسائل إلى المواضيع
يمكن لجميع نُسخ التطبيق، بغض النظر عن المنصة، تفسير الحقلَين التاليَين المشترَكين:
حالات استخدام الحقول الخاصة بالمنصة
استخدِم الحقول الخاصة بالمنصة عندما تريد:
- إرسال الحقول إلى منصات معيّنة فقط
- إرسال الحقول الخاصة بالمنصة بالإضافة إلى الحقول الشائعة
عندما تريد إرسال القيم إلى منصات معيّنة فقط، لا تستخدِم الحقول الشائعة، بل استخدِم الحقول الخاصة بالمنصة. على سبيل المثال، لإرسال إشعار إلى منصات Apple والويب فقط وليس إلى Android، يجب استخدام مجموعتَين منفصلتَين من الحقول، واحدة لأجهزة Apple وأخرى للويب.
عند إرسال رسائل تتضمّن خيارات تسليم معيّنة، استخدِم الحقول الخاصة بالمنصة لضبطها. يمكنك تحديد قيم مختلفة لكل منصة إذا أردت ذلك. ومع ذلك، حتى إذا أردت ضبط القيمة نفسها بشكل أساسي على مستوى المنصّات، يجب استخدام الحقول الخاصة بالمنصّة. ويعود السبب في ذلك إلى أنّ كل نظام أساسي قد يفسّر القيمة بشكلٍ مختلف قليلاً. على سبيل المثال، يتم ضبط وقت الصلاحية على Android كوقت انتهاء صلاحية بالثواني، في حين يتم ضبطه على Apple كتاريخ انتهاء صلاحية.
مثال: رسالة إشعار تتضمّن خيارات تسليم خاصة بالنظام الأساسي
يُرسِل طلب الإرسال بالإصدار 1 التالي عنوان إشعار ومقتَله موحّدَين إلى جميع المنصّات، ولكنه يُرسِل أيضًا بعض عمليات الاستبدال الخاصة بالمنصّة. على وجه التحديد، يجب أن يستوفي الطلب الشروط التالية:
- ضبط وقت انتهاء صلاحية طويل لنظامَي Android والويب، مع ضبط أولوية رسالة APN (منصات Apple) على مستوى منخفض
- تُستخدَم هذه السمة لضبط المفاتيح المناسبة لتحديد نتيجة نقرة المستخدم على الإشعار على Android وApple، وهي
click_action
وcategory
على التوالي.
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "notification":{ "title":"Match update", "body":"Arsenal goal in added time, score is now 3-0" }, "android":{ "ttl":"86400s", "notification"{ "click_action":"OPEN_ACTIVITY_1" } }, "apns": { "headers": { "apns-priority": "5", }, "payload": { "aps": { "category": "NEW_MESSAGE_CATEGORY" } } }, "webpush":{ "headers":{ "TTL":"86400" } } } }
اطّلِع على مستندات مرجعية لإصدار HTTP 1 للحصول على تفاصيل كاملة عن المفاتيح المتاحة في الكتل الخاصة بالنظام الأساسي في نص الرسالة. لمزيد من المعلومات حول إنشاء طلبات الإرسال التي تحتوي على نص الرسالة، راجِع مقالة إنشاء طلبات الإرسال.
خيارات التسليم
يوفّر FCM مجموعة محدّدة من خيارات التسليم للرسائل المُرسَلة إلى
أجهزة Android، ويسمح بخيارات مماثلة على
أنظمة التشغيل Apple والويب. على سبيل المثال، يتوفّر سلوك الرسائل "القابلة للطي" على
Android من خلال collapse_key
في FCM، وعلى Apple من خلال
apns-collapse-id
، وعلى JavaScript/الويب من خلال Topic
. للاطّلاع على التفاصيل، يُرجى الاطّلاع على الوصف في هذا القسم والمستندات المرجعية ذات الصلة.
الرسائل غير القابلة للتصغير والرسائل القابلة للتصغير
تشير الرسالة غير القابلة للطي إلى أنّه تم تسليم كل رسالة فردية إلى الجهاز. تُرسِل الرسالة غير القابلة للطي بعضًا من المحتوى العميل ، على عكس الرسالة القابلة للطي، مثل رسالة "إرسال طلب فحص" بدون محتوى إلى التطبيق المتوافق مع الأجهزة الجوّالة للتواصل مع الخادم من أجل جلب البيانات.
تشمل بعض حالات الاستخدام الشائعة للرسائل غير القابلة للطي رسائل المحادثة أو الرسائل المهمة. على سبيل المثال، في تطبيق المراسلة الفورية، ستحتاج إلى تسليم كل رسالة لأنّه تحتوي كل رسالة على محتوى مختلف.
بالنسبة إلى أجهزة Android، يمكن تخزين 100 رسالة كحد أقصى بدون تصغيرها. في حال بلوغ الحدّ الأقصى، يتم تجاهل جميع الرسائل المخزّنة. عندما يعود الجهاز مجددًا إلى الاتصال بالإنترنت، يتلقّى رسالة خاصة تشير إلى بلوغ الحد الأقصى. يمكن للتطبيق بعد ذلك التعامل مع الموقف بشكل صحيح، عادةً من خلال طلب ملف شخصي كامل مزامنة من خادم التطبيق.
الرسالة القابلة للطي هي رسالة قد يتم استبدالها برسالة جديدة إذا لم يتم تسليمها إلى الجهاز بعد.
من حالات الاستخدام الشائعة للرسائل القابلة للطي هي الرسائل المستخدَمة لإخبار تطبيق متوافق مع الأجهزة الجوّالة بمزامنة البيانات من الخادم. على سبيل المثال، تطبيق رياضي يُطلع المستخدمين على أحدث النتائج. تكون أحدث رسالة فقط ذات صلة.
لوضع علامة على رسالة على أنّها قابلة للطي على Android، أدرِج المَعلمة
collapse_key
في
الحمولة البرمجية للرسالة. يكون مفتاح التصغير تلقائيًا هو اسم حزمة التطبيق
المسجّل في وحدة تحكّم Firebase. يمكن لخادم FCM
تخزين أربع رسائل مختلفة قابلة للطي في الوقت نفسه لكل
جهاز، ولكل رسالة مفتاح مختلف للطي. وفي حال تجاوزت هذا العدد،
يحتفظ FCM فقط بأحد
أربعة مفاتيح تصغير، بدون ضمانات بشأن المفاتيح التي يتم الاحتفاظ بها.
تكون رسائل المواضيع التي لا تحتوي على حمولة قابلة للطي تلقائيًا. إنّ رسائل الإشعارات
قابلة للطي دائمًا وستتجاهل المَعلمة collapse_key
.
أيّ منهما يجب استخدامه؟
إنّ الرسائل القابلة للطي هي خيار أفضل من وجهة نظر الأداء، شرط ألا يحتاج تطبيقك إلى استخدام رسائل غير قابلة للطي. ومع ذلك، في حال استخدام رسائل قابلة للطي، تذكَّر أنّه لا يسمح FCM باستخدام أكثر من أربعة مفاتيح مختلفة للطي في المرة الواحدة من قِبل FCM لكل رمز تسجيل في أي وقت. يجب عدم تجاوز هذا العدد، وإلا قد يؤدي ذلك إلى عواقب غير متوقّعة.
سيناريو الاستخدام | كيفية الإرسال | |
---|---|---|
لا يمكن تصغيرها | كل رسالة مهمة لتطبيق العميل ويجب إرسالها. | باستثناء رسائل الإشعارات، لا يمكن تصغير جميع الرسائل بشكلٍتلقائي. |
قابل للطي | عندما تكون هناك رسالة أحدث تجعل رسالة قديمة ذات صلة غير ذات صلة بتطبيق العميل، تحلّ FCM محل الرسالة القديمة. على سبيل المثال: الرسائل المستخدَمة لبدء مزامنة البيانات من الخادم، أو رسائل الإشعارات القديمة | اضبط المَعلمة المناسبة في طلب الرسالة:
|
ضبط أولوية رسالة
لديك خياران لتحديد أولوية التسليم للرسائل الواردة: الأولوية العادية والعالية. على الرغم من أنّ السلوك يختلف قليلاً على مختلف المنصات، فإنّ إرسال الرسائل العادية والرسائل ذات الأولوية العالية يعمل على النحو التالي:
أولوية عادية: يتم تسليم الرسائل ذات الأولوية العادية فورًا عندما يكون التطبيق في المقدّمة. بالنسبة إلى التطبيقات التي تعمل في الخلفية، قد يتأخّر التسليم. بالنسبة إلى الرسائل الأقل حساسية للوقت، مثل إشعارات الرسائل الإلكترونية الجديدة أو مزامنة واجهة المستخدم أو مزامنة بيانات التطبيق في الخلفية، اختَر الأولوية العادية للتسليم.
أولوية عالية: تحاول ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" إرسال الرسائل المُهمّة على الفور حتى إذا كان الجهاز في وضع "الاستراحة الذكية". الرسائل ذات الأولوية العالية مخصّصة للمحتوى الذي يظهر للمستخدمين ويكون متاحًا لفترة محدودة.
في ما يلي مثال على رسالة عادية ذات أولوية تم إرسالها عبر بروتوكول FCM HTTP v1 لإعلام أحد المشتركين في مجلة بأنّه يتوفّر محتوى جديد للتنزيل:
{ "message":{ "topic":"subscriber-updates", "notification":{ "body" : "This week's edition is now available.", "title" : "NewsMagazine.com", }, "data" : { "volume" : "3.21.15", "contents" : "http://www.news-magazine.com/world-week/21659772" }, "android":{ "priority":"normal" }, "apns":{ "headers":{ "apns-priority":"5" } }, "webpush": { "headers": { "Urgency": "high" } } } }
لمزيد من التفاصيل حول تحديد أولوية الرسائل الخاصة بالمنصة:
حالات الاستخدام المُهمّة للحياة
لم يتم تصميم واجهات برمجة التطبيقات FCM لإرسال تنبيهات الطوارئ أو الأنشطة الأخرى العالية الخطورة التي قد يؤدي استخدام واجهات برمجة التطبيقات أو عدم استخدامها إلى الوفاة أو التعرض لإصابة شخصية أو إلحاق الضرر بالبيئة (مثل تشغيل المنشآت النووية أو مراقبة حركة المرور الجوي أو أنظمة المساعدة على الإبقاء على حياة الأفراد). ويُحظر أي استخدام من هذا القبيل صراحةً بموجب الفقرة 4(أ). 7 من بنود الخدمة. أنت وحدك المسؤول عن إدارة امتثال تطبيقك للأحكام، وأي أضرار ناتجة عن عدم امتثالك لها. توفّر Google واجهات برمجة التطبيقات "كما هي"، وتحتفظ بالحق في إيقاف واجهات برمجة التطبيقات أو أي جزء منها أو أي ميزة أو إمكانية وصولك إليها، لأي سبب و في أي وقت، بدون مسؤولية أو التزام آخر تجاهك أو تجاه المستخدمين.
ضبط مدة بقاء الرسالة
يُسلّم FCM الرسائل عادةً بعد إرسالها مباشرةً. ومع ذلك، قد لا يكون هذا ممكنًا في بعض الحالات. على سبيل المثال، إذا كانت المنصة Android، قد يكون الجهاز مطفأً أو غير متصل بالإنترنت أو غير متاح لأي سبب آخر. وقد يؤخّر FCM الرسائل عمدًا لمنع أحد التطبيقات من استهلاك موارد مفرطة مما يؤدي بدوره إلى أثر سلبي على عمر البطارية.
وفي هذه الحالة، يخزِّن FCM الرسالة ويسلّمها في أقرب وقت ممكن. على الرغم من أنّ هذا أمر جيد في معظم الحالات، إلا أنّ هناك بعض التطبيقات التي قد لا يتم تسليم رسائلها المتأخرة أبدًا. على سبيل المثال، إذا كانت الرسالة عبارة عن مكالمة واردة أو إشعار بمحادثة فيديو، لن يكون لها معنى إلا لفترة قصيرة قبل إنهاء المكالمة. أو إذا كانت الرسالة دعوة لحضور حدث، لن يكون لها أي فائدة إذا تم استلامها بعد انتهاء الحدث.
على Android والويب/JavaScript، يمكنك تحديد الحد الأقصى لمدة بقاء الرسالة. يجب أن تكون القيمة مدة تتراوح بين 0 و2,419,200 ثانية (28 يومًا)، وتتوافق مع الحد الأقصى لمدة الوقت التي يخزّن فيها FCM الرسالة ويحاول تسليمها. يتم ضبط الطلبات التي لا تحتوي على حقل هذا تلقائيًا على الحد الأقصى لمدة أربعة أسابيع.
في ما يلي بعض الاستخدامات المحتملة لهذه الميزة:
- المكالمات الواردة عبر محادثة الفيديو
- أحداث الدعوات التي تنتهي صلاحيتها
- أحداث التقويم
من المزايا الأخرى لتحديد مدة صلاحية الرسالة أنّه
لا تفرض FCM تقييدًا على عدد الرسائل القابلة للطي للرسائل التي تبلغ قيمة
وقت بقائها 0 ثانية.
تبذل FCM قصارى جهدها في معالجة الرسائل التي يجب
تسليمها "الآن أو أبدًا". تجدر الإشارة إلى أنّ قيمة
time_to_live
التي تبلغ
0 تعني تجاهل الرسائل التي لا يمكن تسليمها على الفور. ومع ذلك،
يقدّم ذلك أفضل وقت استجابة
لإرسال رسائل الإشعارات، لأنّه لا يتم تخزين هذه الرسائل مطلقًا.
في ما يلي مثال على طلب يتضمّن وقت الاستبدال المؤقت:
{ "message":{ "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...", "data":{ "Nick" : "Mario", "body" : "great match!", "Room" : "PortugalVSDenmark" }, "apns":{ "headers":{ "apns-expiration":"1604750400" } }, "android":{ "ttl":"4500s" }, "webpush":{ "headers":{ "TTL":"4500" } } } }
مدة صلاحية الرسالة
عندما ينشر خادم التطبيق رسالة إلى FCM ويتلقّى رقم تعريف الرسالة، لا يعني ذلك أنّه سبق أن تم تسليم الرسالة إلى الجهاز. بل يعني ذلك أنّه تم قبوله للتسليم. يعتمد ما يحدث للرسالة بعد قبولها على عدة عوامل.
في أفضل الحالات، إذا كان الجهاز متصلاً بـ FCM، وكانت الشاشة مفعّلة ولم تكن هناك قيود على الحدّ الأقصى للسرعة، يتم تسليم الرسالة على الفور.
إذا كان الجهاز متصلاً ولكن في وضع "الاستراحة الذكية"، يتم تخزين رسالة ذات أولوية منخفضة
بواسطة FCM إلى أن يخرج الجهاز من وضع "الاستراحة الذكية". و
هنا يأتي دور العلامة collapse_key
: إذا كانت هناك
رسالة تتضمّن مفتاح التصغير (ومرموز التسجيل) نفسه محفوظة
وتنتظر
التسليم، يتم تجاهل الرسالة القديمة وتحلّ الرسالة الجديدة محلّها
(أي أنّ الرسالة القديمة يتم تصغيرها بواسطة الرسالة الجديدة). ومع ذلك، في حال عدم ضبط مفتاح collapse
، يتم تخزين كلّ من الرسائل الجديدة والقديمة لإرسالها في المستقبل.
إذا لم يكن الجهاز متصلاً بـ FCM، يتم تخزين الرسالة إلى أن يتم
إنشاء اتصال (مع مراعاة قواعد مفتاح التصغير مرة أخرى). عند بدء اتصال، يرسل FCM جميع الرسائل في انتظار المراجعة إلى
الجهاز. إذا لم يتم ربط الجهاز مرة أخرى
(على سبيل المثال، إذا تمت إعادة ضبطه على الإعدادات الأصلية)، ستنتهي مهلة الرسالة في النهاية
وسيتم تجاهلها من مساحة تخزين FCM. المهلة التلقائية هي أربعة أسابيع،
ما لم يتم ضبط العلامة time_to_live
.
للحصول على مزيد من الإحصاءات حول تسليم رسالة، اتّبِع الخطوات التالية:
للحصول على مزيد من الإحصاءات عن إرسال الرسائل على منصات Android أو Apple، يمكنك الاطّلاع على لوحة بيانات إعداد التقارير في FCM التي تسجِّل عدد الرسائل المُرسَلة والمُفتحة على أجهزة Apple وAndroid، بالإضافة إلى بيانات "مرّات الظهور" (الإشعارات التي يراها المستخدمون) لتطبيقات Android.
بالنسبة إلى أجهزة Android التي تم تفعيل ميزة المراسلة المباشرة مع القناة عليها، إذا لم يتم ربط الجهاز بتطبيق FCM لأكثر من شهر، سيظل تطبيق FCM يقبل الرسالة ولكنّه يتخلّص منها على الفور. إذا ربط العميل الجهاز خلال أربعة أسابيع من آخر رسالة بيانات أرسلتها إليه، سيتلقّى العميل طلب الاستدعاء onDeletedMessages(). يمكن للتطبيق بعد ذلك التعامل مع الموقف بشكل صحيح، عادةً من خلال طلب ملف شخصي كامل مزامنة من خادم التطبيق.
أخيرًا، عندما يحاول FCM إرسال رسالة إلى الجهاز
وتم إلغاء تثبيت التطبيق، يتخلّص FCM من هذه الرسالة على الفور ويبطل
رمز التسجيل. ستؤدي محاولات إرسال رسالة إلى ذلك
الجهاز في المستقبل إلى ظهور خطأ NotRegistered
.
التقييد والحصص
هدفنا هو تسليم كل رسالة يتم إرسالها عبر ميزة "المراسلة من خلال السحابة الإلكترونية من Firebase". ومع ذلك، يؤدي إرسال كل رسالة أحيانًا إلى تقديم تجربة سيئة للمستخدم بشكل عام. وفي الحالات الأخرى، نحتاج إلى توفير حدود لضمان أن يوفّر نظام "إرسال الرسائل إلى تطبيقات Android" خدمة قابلة للتطوير لجميع المُرسِلين. تساعدنا أنواع الحدود والحصص الموضّحة في هذا القسم في موازنة هذه العوامل المهمة.
الحدّ الأقصى المسموح به لعرض نطاق الرسائل الواردة
قدّمت واجهة برمجة التطبيقات HTTP v1 حصصًا لكل مشروع وكل دقيقة لرسائل البث المباشر. تغطّي الحصة التلقائية التي تبلغ 600 ألف رسالة في الدقيقة أكثر من% 99 من FCM المطوّرين مع الحفاظ على استقرار النظام وتقليل تأثير المشاريع التي تُرسِل عددًا كبيرًا من الرسائل في وقت قصير.
أنماط حركة المرور المفاجئة يمكن أن تؤدي إلى ظهور أخطاء تجاوز الحصة. في حال تجاوز الحدّ الأقصى للعدد المسموح به، يعرض النظام رمز حالة HTTP 429 (QUOTA_EXCEEDED) إلى أن تتم إعادة ملء الحدّ الأقصى المسموح به في الدقيقة التالية. قد يتم أيضًا عرض الردود 429 في حالات ازدحام الشبكة، لذا ننصحك بشدة بمعالجة الردود 429 وفقًا لالاقتراحات المنشورة.
يُرجى العلم بما يلي:
- تقيس الحصة للتحميل الرسائل، وليس الطلبات.
- يتم احتساب أخطاء العميل (رموز حالة HTTP من 400 إلى 499) (باستثناء أخطاء 429).
- يتم احتساب الحصص بالدقائق، ولكن لا يتم ضبط هذه الدقائق وفقًا للساعة.
حصة المراقبة
يمكنك الاطّلاع على الحصة والاستخدام والأخطاء في Google Cloud Console:
- الانتقال إلى وحدة تحكّم Google Cloud
- اختَر واجهات برمجة التطبيقات والخدمات.
- من قائمة الجدول، اختَر Firebase Cloud Messaging API.
- اختَر الحصة والقيود المفروضة على النظام.
ملاحظة: لا تتمّ مواءمة هذه الرسوم البيانية مع الدقائق المحدّدة في الحصة الزمنية بدقة، ما يعني أنّه قد يتم عرض رسائل الخطأ 429 عندما تكون عدد الزيارات أقل من الحصة.
طلب زيادة الحصة
قبل طلب زيادة الحصة، تأكَّد مما يلي:
- إذا كان معدّل استخدامك يتجاوز بانتظام% 80 من الحصة لمدة 5 دقائق متتالية على الأقل في اليوم
- نسبة أخطاء العميل أقل من% 5، خاصةً خلال ذروة عدد الزيارات
- الالتزام بأفضل الممارسات لإرسال الرسائل على نطاق واسع
إذا كنت تستوفي هذه المعايير، يمكنك إرسال طلب زيادة الحصة بنسبة تصل إلى 25%، وستبذل FCM كل الجهود العملية لتلبية الطلب (لا يمكن ضمان أي زيادة).
إذا كنت بحاجة إلى المزيد من الحصة المخصّصة للرسائل الواردة بسبب إطلاق وشيك أو حدث مؤقت، اطلب حصتك قبل 15 يومًا على الأقل للسماح بوقت كافٍ لمعالجة الطلب. بالنسبة إلى الطلبات الكبيرة (>18 مليون رسالة في الدقيقة)، يجب إرسال إشعار قبل 30 يومًا على الأقل. لا تزال عمليات الإطلاق وطلبات الأحداث الخاصة تخضع لنسبة أخطاء العميل ومتطلبات أفضل الممارسات.
اطّلِع أيضًا على الأسئلة الشائعة حول قيود FCM.
الحد الأقصى المسموح به لرسائل المواضيع
لا يتجاوز معدّل إضافة/إزالة الاشتراكات في المواضيع 3,000 طلب في الثانية لكل مشروع.
لمعرفة معدّلات إرسال الرسائل، يُرجى الاطّلاع على تقييد معدل توسيع نطاق البث.
تقييد توزيع البيانات
توسيع نطاق وصول الرسائل هي عملية إرسال رسالة إلى أجهزة متعددة، مثل عند استهداف المواضيع والمجموعات، أو عند استخدام أداة إنشاء الإشعارات لاستهداف شرائح الجمهور أو شرائح المستخدمين.
لا يكون توسيع نطاق الرسائل فوريًا، لذا قد يكون لديك أحيانًا عدة عمليات توسيع نطاق جارية بشكل متزامن. نحصر عدد عمليات توسيع نطاق الرسائل المتزامنة لكل مشروع بـ 1,000 عملية. بعد ذلك، قد نرفض طلبات توسيع نطاق البث إضافية أو نؤجل توسيع نطاق البث للطلبات إلى أن تكتمل بعض عمليات توسيع نطاق البث الجارية.
يتأثّر معدّل التوسيع الفعلي الذي يمكن تحقيقه بعدد المشاريع التي تطلب عمليات التوسيع في الوقت نفسه. إنّ معدّل التوسّع الذي يبلغ 10,000 طلب في الثانية لمشروع individual ليس من غير المألوف، ولكنّ هذا العدد ليس ضمانًا وهو نتيجة إجمالي الحمل على النظام. تجدر الإشارة إلى أنّه يتم تقسيم سعة العرض المتوفرة على المشاريع وليس على طلبات العرض. وبالتالي، إذا كان مشروعك يتضمّن قسمَين فرعيَّين قيد التنفيذ، سيتلقّى كل قسم فرعي نصف معدّل التقسيم المتاح فقط. إنّ الطريقة المُقترَحة لزيادة سرعة التوسّع إلى أقصى حدّ هي عدم إجراء أكثر من عملية توسّع نشطة واحدة في المرة الواحدة.
الحد من عدد الرسائل القابلة للتصغير
كما هو موضّح أعلاه، الرسائل القابلة للطي هي إشعارات خالية من المحتوى ومصمّمة للطي فوق بعضها. في حال تكرار المطوِّر للرسالة نفسها في التطبيق بشكلٍ متكرّر جدًا، نؤخّر الرسائل (نخفّض سرعتها) لتقليل تأثيرها على بطارية المستخدم.
على سبيل المثال، إذا أرسلت أعدادًا كبيرة من طلبات مزامنة الرسائل الإلكترونية الجديدة إلى جهاز واحد، قد نؤخّر طلب مزامنة الرسائل الإلكترونية التالي بضع دقائق حتى تتمكّن الأجهزة من المزامنة بمعدّل متوسط أقل. ويتم إجراء هذا التقييد بشكل صارم بهدف الحد من تأثير البطارية على المستخدم.
إذا كانت حالة الاستخدام تتطلّب أنماط إرسال متكرّرة بمعدل عالٍ، قد تكون الرسائل غير القابلة للطي هي الخيار المناسب. بالنسبة إلى هذه الرسائل، احرص على تضمين المحتوى في هذه الرسائل لتقليل استهلاك البطارية.
نحن نقتصر على عرض 20 رسالة قابلة للطي لكل تطبيق على كل جهاز، مع إضافة رسالة واحدة كل 3 دقائق.
الحدّ الأقصى المسموح به لعرض نطاق خادم XMPP
نحدّ من معدّل الاتصال بخوادم XMPP في "خدمة المراسلة عبر السحابة الإلكترونية من Firebase" إلى 400 اتصال في الدقيقة لكل مشروع. من المفترض ألا يتسبب ذلك في حدوث مشكلة في تسليم الرسائل، ولكن من المهم ضمان ثبات النظام. لكل مشروع، تسمح ميزة "المراسلة عبر السحابة الإلكترونية من Firebase (FCM)" بإجراء 2500 عملية اتصال بشكل متزامن.
بالنسبة إلى المراسلة من الأعلى إلى الأسفل باستخدام XMPP، تحدّ خدمة المراسلة عبر السحابة الإلكترونية من Google من الرسائل من الأعلى إلى الأسفل التي تبلغ 1,500,000 رسالة في الدقيقة لكل مشروع لتجنُّب زيادة عدد الطلبات على الخوادم المقصودة من الأعلى إلى الأسفل.
نحدّ من عدد الرسائل المرسَلة من كل جهاز إلى 1,000 رسالة في الدقيقة للحماية من تضاؤل طاقة البطارية بسبب الأداء السيئ للتطبيقات.
الحد الأقصى لعدد الرسائل المرسَلة إلى جهاز واحد
بالنسبة إلى أجهزة Android، يمكنك إرسال ما يصل إلى 240 رسالة في الدقيقة و5,000 رسالة في الساعة إلى جهاز واحد. يهدف هذا الحدّ الأقصى العالي إلى السماح بزيادة مفاجئة في عدد الزيارات على المدى القصير، مثلما يحدث عندما يتفاعل المستخدمون بسرعة عبر المحادثة. يمنع هذا الحد الأخطاء في منطق الإرسال من استنزاف البطارية على الجهاز بدون قصد.
بالنسبة إلى أجهزة iOS، نعرض رسالة خطأ عندما يتجاوز معدّل الرسائل الحدود المسموح بها في APN.
منافذ FCM وجدار الحماية
إذا كانت مؤسستك تستخدم جدار حماية لتقييد حركة البيانات من وإلى الإنترنت، عليك ضبطه للسماح للأجهزة الجوّالة بالاتصال بـ FCM لكي تتلقّى الأجهزة على شبكتك الرسائل. يستخدم FCM عادةً المنفذ 5228، ولكنه يستخدم أحيانًا المنفذَين 443 و5229 و 5230.
بالنسبة إلى الأجهزة التي تتصل بشبكتك، لا يوفّر FCMعناوين IP محدّدة لأنّ نطاق IP الخاص بنا يتغيّر بشكل متكرّر وقد تصبح قواعد جدار الحماية قديمة، ما يؤثر في تجربة المستخدمين. من الأفضل إضافة المنافذ 5228 إلى 5230 و443 إلى القائمة المسموح بها بدون أي قيود على عناوين IP. ومع ذلك، إذا كان عليك فرض قيود على عناوين IP، يجب إضافة جميع عناوين IP المدرَجة في goog.json إلى القائمة المسموح بها. يتم تعديل هذه القائمة الكبيرة بانتظام، وننصحك بتعديل القواعد بشكل شهري. غالبًا ما تكون المشاكل الناتجة عن قيود جدار الحماية على عناوين IP متقطعة ويصعب تشخيصها.
نقدّم مجموعة من أسماء النطاقات التي يمكن إدراجها في القائمة المسموح بها بدلاً من عناوين IP. ويمكنك الاطّلاع على أسماء المضيفين هذه أدناه. إذا بدأنا باستخدام عناوين Hostname إضافية، سنعدّل القائمة هنا. قد يكون استخدام أسماء النطاقات في قاعدة جدار الحماية صالحًا أو غير صالح في جهاز جدار الحماية.
منافذ TCP المطلوب فتحها:
- 5228
- 5229
- 5230
- 443
أسماء المضيفين المطلوب فتحها:
- mtalk.google.com
- mtalk4.google.com
- mtalk-staging.google.com
- mtalk-dev.google.com
- alt1-mtalk.google.com
- alt2-mtalk.google.com
- alt3-mtalk.google.com
- alt4-mtalk.google.com
- alt5-mtalk.google.com
- alt6-mtalk.google.com
- alt7-mtalk.google.com
- alt8-mtalk.google.com
- android.apis.google.com
- device-provisioning.googleapis.com
- firebaseinstallations.googleapis.com
جدران حماية ترجمة عناوين الشبكة و/أو فحص الحِزم بالاستناد إلى الحالة:
إذا كانت شبكتك تستخدم ترجمة عنوان الشبكة (NAT) أو فحص الحِزم بالاستناد إلى الحالة (SPI)، يجب ضبط مهلة تبلغ 30 دقيقة أو أكثر لعمليات الاتصال عبر المنافذ 5228 و5230. يتيح لنا ذلك توفير اتصالٍ موثوق به مع تقليل استهلاك البطارية في الأجهزة الجوّالة للمستخدمين.
التفاعلات مع شبكة VPN وإمكانية تجاوزها
تتّخذ Firebase Cloud Messaging خطوات مختلفة لضمان أنّ اتصال رسائل الدفع من الهاتف إلى الخادم موثوق به ومتاح قدر الإمكان. ويؤدي استخدام شبكة VPN إلى تعقيد هذا الجهد.
تحجب شبكات VPN المعلومات الأساسية التي يحتاج إليها FCM لضبط الاتصال من أجل زيادة الموثوقية وعمر البطارية إلى أقصى حد. في بعض الحالات، تؤدي الشبكات الافتراضية الخاصة إلى قطع الاتصالات التي تستمر لفترة طويلة، ما يؤدي إلى تجربة سيئة للمستخدمين بسبب عدم تلقّي الرسائل أو تأخّرها أو بسبب استهلاك البطارية بشكل كبير. عندما تكون شبكة VPN مُعدّة للسماح لنا بإجراء ذلك، نتجاوز شبكة VPN باستخدام اتصال مشفَّر (عبر الشبكة الأساسية Wi-Fi أو LTE) لضمان تجربة موثوقة وموفّرة للبطارية. إنّ استخدام FCM لشبكات VPN التي يمكن اختراقها خاص بقناة الإشعارات الفورية في FCM. أما حركة بيانات FCM الأخرى، مثل حركة بيانات التسجيل، فتستخدم شبكة VPN إذا كانت نشطة. عندما يتجاوز FCM الاتصال شبكة VPN، يفقد مزايا إضافية قد تقدّمها شبكة VPN، مثل إخفاء عنوان IP.
ستتوفّر طرق مختلفة في الشبكات الافتراضية الخاصة للتحكّم في إمكانية تجاوزها. للحصول على التعليمات، يُرجى الرجوع إلى مستندات شبكة VPN المحدّدة.
إذا لم يتم ضبط شبكة VPN لتكون قابلة للتجاوز، سيستخدم Firebase Cloud Messaging شبكة VPN للاتصال بالخادم. قد يؤدي ذلك إلى تأخُّر وصول الرسائل وقد يؤدي إلى زيادة استهلاك البطارية لأنّ تطبيق Cloud Messaging يعمل على الحفاظ على الاتصال عبر شبكة VPN.
بيانات الاعتماد
استنادًا إلى ميزات FCM التي تنفّذها، قد تحتاج إلى بيانات الاعتماد التالية من مشروعك على Firebase:
رقم تعريف المشروع | معرّف فريد لمشروعك على Firebase، يُستخدَم في الطلبات المرسَلة إلى نقطة نهاية HTTP في FCM الإصدار 1. تتوفّر هذه القيمة في لوحة الإعدادات في وحدة تحكّم Firebase. |
الرمز المميّز للتسجيل | سلسلة رمز مميّز تُحدِّد كل مثيل من تطبيقات العميل يجب توفُّر الرمز المميّز للتسجيل للرسائل المرسَلة من جهاز واحد أو من مجموعة أجهزة. يُرجى العلم أنّه يجب الحفاظ على سرية الرموز المميّزة للتسجيل. |
معرّف المُرسِل | قيمة رقمية فريدة تم إنشاؤها عند إنشاء مشروعك على Firebase، وهي متوفّرة في علامة التبويب Cloud Messaging ضمن لوحة الإعدادات Firebase. يتم استخدام معرّف المُرسِل لتحديد كل مُرسِل يمكنه إرسال الرسائل إلى تطبيق العميل. |
رمز الدخول | رمز مميز قصير الأمد لبروتوكول OAuth 2.0 يمنح الإذن بطلبات HTTP v1 API. يرتبط هذا الرمز المميّز بحساب خدمة ينتمي إلى مشروعك على Firebase. لإنشاء رموز وصول وتغييرها، اتّبِع الخطوات الموضّحة في مقالة تفويض طلبات الإرسال. |
مفتاح الخادم (للبروتوكولات القديمة **المتوقفة نهائيًا**) | مفتاح خادم يمنح خادم تطبيقك إذنًا بالوصول إلى خدمات Google، بما في ذلك إرسال الرسائل عبر بروتوكولات Firebase Cloud Messaging القديمة التي تم إيقافها نهائيًا ملاحظة مهمة: لا تُدرِج مفتاح الخادم في أي مكان في رمز العميل. تأكَّد أيضًا من استخدام مفاتيح الخادم فقط لتفويض خادم تطبيقك. ترفض FCM مفاتيح نظام التشغيل Android ونظام التشغيل Apple ومفاتيح المتصفّح. |