لمحة عن رسائل "المراسلة عبر السحابة الإلكترونية من Firebase"

توفّر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" مجموعة كبيرة من خيارات المراسلة والإمكانات. تهدف المعلومات الواردة في هذه الصفحة إلى مساعدتك على فهم الأنواع المختلفة من رسائل FCM وماذا يمكنك فعله بها.

أنواع الرسائل

باستخدام ميزة "المراسلة عبر السحابة الإلكترونية من Firebase"، يمكنك إرسال نوعين من الرسائل إلى العملاء:

• رسائل الإشعارات التي يُعتقَد أحيانًا على أنّها "رسائل معروضة" وتعالج حزمة تطوير البرامج لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" تلقائيًا هذه المشاكل.
• رسائل البيانات التي يعالجها تطبيق العميل

تحتوي رسائل الإشعارات على مجموعة محدّدة مسبقًا من المفاتيح المرئية للمستخدم. وعلى النقيض من ذلك، تحتوي رسائل البيانات فقط على أزواج المفتاح/القيمة المخصصة التي يحددها المستخدم. يمكن أن تحتوي رسائل الإشعارات على حمولة بيانات اختيارية. يبلغ الحدّ الأقصى لحمولة كلا نوعَي الرسائل 4096 بايت، باستثناء عند إرسال رسائل من "وحدة تحكُّم Firebase" التي تفرض حدًا أقصى يبلغ 1,000 حرف.

	استخدام السيناريو	كيفية الإرسال
رسالة إشعار	تعرِض حزمة تطوير البرامج (SDK) لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" الرسالة إلى أجهزة المستخدمين النهائيين بالنيابة عن تطبيق العميل عند تشغيله في الخلفية. أما إذا كان التطبيق يعمل في المقدّمة عند تلقّي الإشعار، فسيحدّد رمز التطبيق السلوك. تتضمن رسائل الإشعارات مجموعة محدَّدة مسبقًا من المفاتيح المرئية للمستخدم وحمولة بيانات اختيارية لأزواج المفتاح/القيمة المخصّصة.	في بيئة موثوق بها، مثل Cloud Functions أو خادم تطبيقك، استخدِم Admin SDK أو HTTP v1 API. اضبط المفتاح notification. قد تتوفّر حمولة بيانات اختيارية. قابلة للتصغير دائمًا يمكنك الاطّلاع على بعض الأمثلة على عرض الإشعارات وإرسال الحمولات الأساسية للطلبات. استخدِم مؤلف الإشعارات: أدخِل نص الرسالة وعنوانها وغير ذلك، ثم أرسِلها. أضِف حمولة بيانات اختيارية من خلال تقديم "بيانات مخصّصة".
رسالة البيانات	يكون تطبيق العميل مسؤولاً عن معالجة رسائل البيانات. تحتوي رسائل البيانات على أزواج مفاتيح/قيم مخصّصة فقط بدون أسماء مفاتيح محجوزة (انظر أدناه).	في بيئة موثوق بها، مثل Cloud Functions أو خادم تطبيقك، استخدِم Admin SDK أو بروتوكولات خادم FCM. في طلب الإرسال، اضبط المفتاح data.

يمكنك استخدام رسائل الإشعارات عندما تريد من حزمة تطوير البرامج (SDK) لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" معالجة عرض الإشعارات تلقائيًا عند تشغيل تطبيقك في الخلفية. يمكنك استخدام رسائل البيانات عندما تريد معالجة الرسائل باستخدام رمز تطبيق العميل الخاص بك.

يمكن لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" إرسال رسالة إشعار تتضمّن حمولة بيانات اختيارية. في هذه الحالات، تعالج خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" حمولة البيانات ويعالج تطبيق العميل حمولة البيانات.

رسائل الإشعارات

للاختبار أو لأغراض التسويق وإعادة جذب المستخدمين، يمكنك إرسال رسائل إشعارات باستخدام وحدة تحكُّم Firebase. توفّر وحدة تحكُّم Firebase اختبار A/B مستند إلى الإحصاءات لمساعدتك في تنقيح الرسائل التسويقية وتحسينها.

لإرسال رسائل الإشعارات آليًا باستخدام "SDK للمشرف" أو بروتوكولات "المراسلة عبر السحابة الإلكترونية من Firebase"، يجب ضبط مفتاح notification مع المجموعة المحدَّدة مسبقًا واللازمة من خيارات قيمة المفتاح للجزء المرئي للمستخدم من رسالة الإشعار. على سبيل المثال، إليك رسالة إشعار بتنسيق JSON في تطبيق رسائل فورية:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

يتم تسليم رسائل الإشعارات إلى قائمة الإشعارات عندما يكون التطبيق يعمل في الخلفية. بالنسبة إلى التطبيقات التي تعمل في المقدّمة، تتم معالجة الرسائل من خلال وظيفة معاودة الاتصال.

يمكنك الاطّلاع على كائن إشعار بروتوكول HTTP v1 للحصول على القائمة الكاملة للمفاتيح المحدَّدة مسبقًا المتاحة لإنشاء رسائل الإشعارات.

رسائل البيانات

اضبط المفتاح المناسب مع أزواج المفتاح/القيمة المخصّصة لإرسال حمولة بيانات إلى تطبيق العميل.

تأكَّد من عدم استخدام أي كلمات محجوزة في أزواج المفتاح/القيمة المخصّصة. تتضمن الكلمات المحجوزة "من" أو "إشعار" أو "message_type" أو أي كلمة تبدأ بـ "google" أو "gcm".

على سبيل المثال، إليك رسالة بتنسيق JSON في تطبيق الرسائل الفورية نفسه الوارد أعلاه، حيث يتم تضمين المعلومات في مفتاح data الشائع، ومن المتوقّع أن يفسّر تطبيق العميل المحتوى:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

يوضّح المثال أعلاه استخدام حقل data ذي المستوى الأعلى أو المشترك، ويتم تفسير ذلك من خلال العملاء على جميع الأنظمة الأساسية التي تتلقّى الرسالة. على كل نظام أساسي، يتلقّى تطبيق العميل حمولة البيانات في دالة استدعاء.

تشفير رسائل البيانات

تستخدم طبقة النقل في Android (راجِع بنية "المراسلة عبر السحابة الإلكترونية من Firebase") التشفير من نقطة إلى نقطة. بناءً على احتياجاتك، يمكنك إضافة التشفير التام بين الأطراف إلى رسائل البيانات. لا توفّر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" حلاً شاملاً. مع ذلك، هناك حلول خارجية متاحة، مثل Capillary أو DTLS.

رسائل الإشعارات التي تتضمن حمولة بيانات اختيارية

ويمكنك، سواءً آليًا أو من خلال "وحدة تحكُّم Firebase" إرسال رسائل إشعارات تتضمّن حمولة اختيارية من أزواج المفتاح/القيمة المخصّصة. في منشئ الإشعارات، استخدِم حقول البيانات المخصّصة في الخيارات المتقدّمة.

يعتمد سلوك التطبيق عند تلقّي رسائل تتضمّن حمولات البيانات والإشعارات على ما إذا كان التطبيق يعمل في الخلفية أو في المقدّمة، بشكل أساسي، سواء كان نشطًا في وقت الاستلام أم لا.

• عندما تكون التطبيقات تعمل في الخلفية، تتلقّى حمولة الإشعارات في لوحة الإشعارات ولا تتعامل مع حمولة البيانات إلا عندما ينقر المستخدم على الإشعار.
• عند تشغيل التطبيق في المقدّمة، يتلقّى تطبيقك كائن رسالة مع توفّر كلتا حمولتَي البيانات.

في ما يلي رسالة بتنسيق JSON تحتوي على المفتاح notification والمفتاح data:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

تخصيص رسالة عبر الأنظمة الأساسية

إنّ "SDK للمشرف" في Firebase وبروتوكول FCM v1 HTTP يتيحان لطلبات الرسائل ضبط جميع الحقول المتاحة في العنصر message. يشمل هذا النوع من المحتوى ما يلي:

• مجموعة شائعة من الحقول ليتم تفسيرها بواسطة جميع مثيلات التطبيقات التي تتلقى الرسالة.
• مجموعات الحقول الخاصة بالنظام الأساسي، مثل AndroidConfig وWebpushConfig، لا يتم تفسيرها إلا من خلال مثيلات التطبيق التي تعمل على النظام الأساسي المحدد.

تمنحك عمليات الحظر الخاصة بالنظام الأساسي المرونة لتخصيص الرسائل للأنظمة الأساسية المختلفة لضمان التعامل معها بشكل صحيح عند استلامها. ستراعي خلفية "المراسلة عبر السحابة الإلكترونية من Firebase" جميع المعلمات المحدّدة وتخصِّص الرسالة لكل نظام أساسي.

متى تستخدم الحقول المشتركة

استخدِم الحقول الشائعة عند:

• استهداف مثيلات التطبيقات على جميع الأنظمة الأساسية: Apple وAndroid والويب
• إرسال رسائل إلى المواضيع

يمكن لجميع مثيلات التطبيقات، بغض النظر عن النظام الأساسي، تفسير الحقول الشائعة التالية:

• message.notification.title
• message.notification.body
• message.data

حالات استخدام الحقول الخاصة بالنظام الأساسي

استخدِم الحقول الخاصة بالنظام الأساسي عندما تريد:

• إرسال الحقول إلى أنظمة أساسية معيّنة فقط
• إرسال الحقول الخاصة بالنظام الأساسي بالإضافة إلى الحقول المشتركة

عندما تريد إرسال القيم إلى أنظمة أساسية معيّنة فقط، لا تستخدم الحقول الشائعة، بل استخدِم الحقول الخاصة بالنظام الأساسي. على سبيل المثال، لإرسال إشعار إلى أنظمة Apple الأساسية والويب فقط وليس إلى Android، يجب استخدام مجموعتَين منفصلتَين من الحقول، إحداهما لمنصة Apple والأخرى للويب.

عند إرسال الرسائل باستخدام خيارات تسليم محددة، استخدِم حقولاً خاصة بالنظام الأساسي لإعدادها. يمكنك تحديد قيم مختلفة لكل منصة إذا أردت. مع ذلك، حتى عندما تريد ضبط القيمة نفسها بشكل أساسي على مستوى الأنظمة الأساسية، يجب استخدام حقول خاصة بالأنظمة الأساسية. ويعود السبب في ذلك إلى أنّ كل نظام أساسي قد يفسّر القيمة بشكل مختلف قليلاً. على سبيل المثال، يتم تحديد مدة البقاء على Android كوقت انتهاء الصلاحية بالثواني، بينما يتم ضبط القيمة على تاريخ انتهاء الصلاحية على Apple.

مثال: رسالة إشعار بخيارات التسليم الخاصة بالنظام الأساسي

يرسل طلب الإرسال التالي v1 عنوان إشعار ومحتوًى شائعَين إلى جميع المنصّات، ولكنّه يرسل أيضًا بعض عمليات الإلغاء الخاصة بالنظام الأساسي. على وجه التحديد، يجب أن يستوفي الطلب ما يلي:

• ضبط مدّة طويلة الأمد على أنظمة 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 v1 للحصول على التفاصيل الكاملة حول المفاتيح المتوفّرة في مجموعات خاصة بالنظام الأساسي في نص الرسالة. لمزيد من المعلومات حول إنشاء طلبات الإرسال التي تحتوي على نص الرسالة، راجِع إنشاء طلبات الإرسال.

خيارات التوصيل

توفّر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" مجموعة محدّدة من خيارات التسليم للرسائل المُرسَلة إلى أجهزة Android، وتتيح خيارات مماثلة على أنظمة Apple الأساسية وعلى الويب. على سبيل المثال، يتم دعم سلوك الرسالة "القابلة للتصغير" على Android من خلال collapse_key في ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" وعلى Apple عبر apns-collapse-id وعلى JavaScript/الويب من خلال Topic. للحصول على التفاصيل، راجِع الأوصاف في هذا القسم والمستندات المرجعية ذات الصلة.

الرسائل غير القابلة للتصغير والتصغير

تشير الرسالة غير القابلة للتصغير إلى أنّه تم تسليم كل رسالة فردية إلى الجهاز. تقدّم الرسالة غير القابلة للتصغير بعض المحتوى المفيد، على عكس الرسالة القابلة للتصغير، مثل إرسال "ping" خالٍ من المحتوى إلى التطبيق للأجهزة الجوّالة من أجل التواصل مع الخادم لجلب البيانات.

لا تضمن خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" طلب التسليم.

بعض حالات الاستخدام المعتادة للرسائل غير القابلة للتصغير هي رسائل المحادثة أو الرسائل المهمة. في تطبيق الرسائل الفورية مثلاً، قد ترغب في تسليم كل رسالة، لأن كل رسالة لها محتوى مختلف.

بالنسبة إلى نظام التشغيل Android، هناك حد أقصى يبلغ 100 رسالة يمكن تخزينها بدون تصغيرها. وفي حالة الوصول إلى الحد الأقصى، يتم تجاهل جميع الرسائل المخزنة. عند إعادة اتصال الجهاز بالإنترنت، يتلقى رسالة خاصة تشير إلى الوصول إلى الحد الأقصى. يمكن للتطبيق بعد ذلك التعامل مع الموقف بشكل صحيح، وعادةً ما يتم ذلك من خلال طلب مزامنة كاملة من خادم التطبيق.

الرسالة القابلة للتصغير هي رسالة قد يتم استبدالها برسالة جديدة في حال لم يتم تسليمها إلى الجهاز بعد.

من حالات الاستخدام الشائعة للرسائل القابلة للتصغير الرسائل التي يتم استخدامها لإخبار التطبيق المتوافق مع الأجهزة الجوّالة بمزامنة البيانات من الخادم. ومن الأمثلة على ذلك تطبيق الرياضة الذي يزوّد المستخدمين بأحدث النتائج. وتكون الرسالة الأحدث فقط هي ذات الصلة.

لوضع علامة "قابلة للتصغير" على رسالة على نظام التشغيل Android، عليك تضمين المَعلمة collapse_key في حمولة الرسالة. يكون المفتاح مصغَّرًا تلقائيًا هو اسم حزمة التطبيق المسجَّل في وحدة تحكُّم Firebase. يمكن لخادم "المراسلة عبر السحابة الإلكترونية من Firebase" أن يخزِّن في الوقت نفسه أربع رسائل مختلفة قابلة للتصغير على كل جهاز، ولكل منها مفتاح تصغير مختلف. وفي حال تجاوز هذا الرقم، تحتفظ خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" بأربعة مفاتيح تصغير فقط بدون أي ضمانات بشأن المفاتيح التي يتم الاحتفاظ بها.

تكون رسائل المواضيع التي لا تتضمّن حمولة قابلة للتصغير تلقائيًا. تكون رسائل الإشعارات قابلة للتصغير دائمًا، وستتجاهل المَعلمة collapse_key.

أيّها يجب أن أستخدم؟

تُعدّ الرسائل القابلة للتصغير الخيار الأفضل من منظور الأداء، بشرط ألا يحتاج تطبيقك إلى استخدام رسائل غير قابلة للتصغير. مع ذلك، إذا كنت تستخدم الرسائل القابلة للتصغير، تذكّر أنّ خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" تسمح فقط باستخدام أربعة مفاتيح تصغير مختلفة كحد أقصى من خلال خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" لكل رمز مميَّز للتسجيل في أي وقت. يجب عدم تجاوز هذا الرقم، وإلا قد يؤدي ذلك إلى عواقب غير متوقّعة.

	استخدام السيناريو	كيفية الإرسال
غير قابلة للتصغير	تكون كل رسالة مهمة لتطبيق العميل ويجب تسليمها.	باستثناء رسائل الإشعارات، تكون جميع الرسائل غير قابلة للتصغير بشكل تلقائي.
قابلة للطيّ	عند وجود رسالة أحدث تعرض رسالة قديمة ذات صلة لا صلة لها بتطبيق العميل، تستبدل خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" الرسالة القديمة. على سبيل المثال: الرسائل المستخدمة لبدء مزامنة البيانات من الخادم أو رسائل الإشعارات القديمة.	اضبط المَعلمة المناسبة في طلب الرسالة: "collapseKey" على نظام التشغيل Android "apns-collapse-id" على Apple "Topic" على الويب collapse_key في البروتوكولات القديمة (جميع الأنظمة الأساسية)

تحديد أولوية رسالة

لديك خياران لتعيين أولوية التسليم للرسائل التي تلي استلام الرسالة: أولوية عادية وعالية. وعلى الرغم من اختلاف السلوك قليلاً باختلاف المنصات، يتم تسليم الرسائل ذات الأولوية العادية وتلك ذات الأولوية العالية على النحو التالي:

• أولوية عادية: يتم تسليم الرسائل ذات الأولوية العادية على الفور عندما يكون التطبيق في المقدّمة. وبالنسبة إلى التطبيقات التي تعمل في الخلفية، قد يتأخر التسليم. يمكنك اختيار أولوية التسليم العادية بشأن الرسائل الأقل أهمية من حيث الوقت، مثل إشعارات البريد الإلكتروني الجديد أو مزامنة واجهة المستخدم أو مزامنة بيانات التطبيق في الخلفية.

• أولوية عالية: تحاول خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" تسليم الرسائل ذات الأولوية العالية فورًا حتى إذا كان الجهاز في وضع "القيلولة". الرسائل ذات الأولوية العالية هي للمحتوى المرئي الحسّاس من حيث الوقت.

عند إرسال رسائل بيانات إلى أجهزة Apple، يجب ضبط الأولوية على 5، أو الأولوية العادية. ترفض الواجهة الخلفية للمراسلة عبر السحابة الإلكترونية من Firebase الرسائل المُرسَلة ذات الأولوية العالية مع ظهور الخطأ INVALID_ARGUMENT.

في ما يلي مثال لرسالة ذات أولوية عادية يتم إرسالها عبر بروتوكول HTTP v1 في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" لإبلاغ مشترك في إحدى المجلات بأنّ المحتوى الجديد متوفّر للتنزيل:

{
  "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"
      }
    }
  }
}

لمزيد من التفاصيل الخاصة بالنظام الأساسي حول ضبط أولوية الرسالة:

• مستندات أسماء نقاط الوصول (APN)
• ضبط أولوية الرسائل وإدارتها (Android)
• الحاجة المُلحّة لإرسال رسائل فورية على الويب

تحديد عمر الرسالة

عادةً ما تسلِّم ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" الرسائل فور إرسالها. ومع ذلك، قد لا يكون ذلك ممكنًا في جميع الأحيان. على سبيل المثال، إذا كان النظام الأساسي هو Android، قد يكون الجهاز متوقّفًا أو غير متصل بالإنترنت أو غير متاح بأي شكل آخر. وقد تعمل ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" على تأخير الرسائل عمدًا لمنع التطبيق من استهلاك موارد زائدة والتأثير سلبيًا في عمر البطارية.

وعند حدوث ذلك، تخزِّن خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" الرسالة وتسلمها في أقرب وقت ممكن. ولا بأس في ذلك في معظم الحالات، إلا أنّ هناك بعض التطبيقات التي قد لا يتم تسليم رسالة متأخرة أبدًا. على سبيل المثال، إذا كانت الرسالة عبارة عن مكالمة واردة أو إشعار محادثة فيديو، لا يمكن الاستفادة منها إلا لفترة زمنية قصيرة قبل إنهاء المكالمة. أما إذا كانت الرسالة عبارة عن دعوة إلى حدث، فلن تكون عديمة الفائدة إذا تم استلامها بعد انتهاء الحدث.

على نظامَي التشغيل Android والويب/JavaScript، يمكنك تحديد الحدّ الأقصى لعمر الرسالة. يجب أن تتراوح القيمة بين 0 و2,419,200 ثانية (28 يومًا)، وتتوافق مع الحد الأقصى للفترة الزمنية التي تخزّن خلالها خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" الرسالة وتحاول تسليمها. أما الطلبات التي لا تتضمّن هذا الحقل، فتتم تلقائيًا ضبط المدة على أربعة أسابيع كحد أقصى.

فيما يلي بعض الاستخدامات الممكنة لهذه الميزة:

• المكالمات الواردة عبر محادثة الفيديو
• أحداث الدعوات التي ستنتهي صلاحيتها قريبًا
• أحداث التقويم

من الميزات الأخرى لتحديد مدة ظهور الرسالة أنّ خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" لا تطبِّق تقييد الرسائل القابلة للتصغير على الرسائل التي لها قيمة مدة البقاء 0 ثانية. توفّر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" أفضل جهد لمعالجة الرسائل التي يجب تسليمها "الآن أو أبدًا". تجدر الإشارة إلى أنّ قيمة 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"
      }
    }
  }
}

فترة بقاء الرسالة

عندما ينشر خادم تطبيق رسالة إلى "المراسلة عبر السحابة الإلكترونية من Firebase" ويتلقّى معرّف الرسالة، لا يعني ذلك أنّه تم تسليم الرسالة إلى الجهاز. بل يعني أنه تم قبوله للتسليم. يعتمد ما يحدث للرسالة بعد قبولها على عدة عوامل.

في أفضل الحالات، إذا كان الجهاز متصلاً بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، سيتم تشغيل الشاشة وليست هناك أي قيود مفروضة على أي قيود، سيتم تسليم الرسالة فورًا.

إذا كان الجهاز متصلاً وكان في وضع "القيلولة"، تخزّن خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" رسالة ذات أولوية منخفضة إلى أن يتم إيقاف ميزة "القيلولة" في الجهاز. وهنا تؤدي العلامة collapse_key دورًا: إذا كان هناك رسالة مخزَّنة حاليًا بمفتاح التصغير (والرمز المميّز للتسجيل) نفسه وتنتظر التسليم، يتم تجاهل الرسالة القديمة وتحلّ الرسالة الجديدة مكانها (أي أنّه يتم تصغير الرسالة القديمة بواسطة الرسالة الجديدة). ومع ذلك، إذا لم يتم تعيين مفتاح التصغير، فسيتم تخزين الرسائل الجديدة والقديمة للتسليم في المستقبل.

إذا لم يكن الجهاز متصلاً بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"، سيتم تخزين الرسالة إلى أن يتم إنشاء اتصال (مرة أخرى مع مراعاة القواعد الرئيسية للتصغير). عند إنشاء اتصال، تُسلِّم ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" جميع الرسائل المعلّقة إلى الجهاز. إذا لم يتصل الجهاز مرة أخرى (على سبيل المثال، إذا تمت إعادة ضبطه على الإعدادات الأصلية)، تنتهي مهلة الرسالة في النهاية ويتم تجاهلها من مساحة تخزين FCM. وتكون المهلة التلقائية أربعة أسابيع، ما لم يتم ضبط علامة time_to_live.

للحصول على مزيد من الإحصاءات حول تسليم رسالة:

للحصول على مزيد من الإحصاءات حول تسليم الرسائل على أنظمة Android أو Apple الأساسية، راجِع لوحة بيانات إعداد التقارير في خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" التي تسجِّل عدد الرسائل المرسَلة والمفتوحة على أجهزة Apple وAndroid، بالإضافة إلى بيانات "مرات الظهور" (الإشعارات التي يراها المستخدمون) لتطبيقات Android.

بالنسبة إلى أجهزة Android التي تم فيها تفعيل ميزة المراسلة المباشرة من القناة، إذا لم يتصل الجهاز بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" لأكثر من شهر واحد، ستظل خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" تقبل الرسالة ولكنها ستتجاهلها على الفور. إذا كان الجهاز يتصل خلال أربعة أسابيع من آخر رسالة بيانات أرسلتها إليه، سيتلقّى عميلك معاودة الاتصال onDeletedMessages(). يمكن للتطبيق بعد ذلك التعامل مع الموقف بشكل صحيح، وعادةً ما يتم ذلك من خلال طلب مزامنة كاملة من خادم التطبيق.

أخيرًا، عندما تحاول خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" تسليم رسالة إلى الجهاز وتم إلغاء تثبيت التطبيق، تتجاهل هذه الرسالة على الفور وتلغي الرمز المميّز للتسجيل. تؤدي المحاولات المستقبلية لإرسال رسالة إلى ذلك الجهاز إلى ظهور خطأ NotRegistered.

تقييد البيانات والحصص

هدفنا هو تسليم كل رسالة يتم إرسالها عبر ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" بشكل دائم. ومع ذلك، يؤدي عرض كل رسالة في بعض الأحيان إلى تجربة مستخدم سيئة بشكل عام. وفي حالات أخرى، نحتاج إلى وضع حدود لضمان توفير خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" لجميع المُرسِلين بخدمة قابلة للتطور. تساعدنا أنواع الحدود والحصص الموضحة في هذا القسم في تحقيق التوازن بين هذه العوامل المهمة.

ملاحظة: تخضع الحدود القصوى التي تمت مناقشتها في هذا القسم للتغيير.

تقييد الرسائل بعد استلامها

قدّمت واجهة برمجة التطبيقات HTTP v1 حصصًا لكل مشروع في الدقيقة لتبادل الرسائل أثناء مرحلة التنفيذ. وتغطي الحصة التلقائية، التي تبلغ 600 ألف رسالة في الدقيقة، أكثر من% 99 من مطوّري خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" مع حماية استقرار النظام والحدّ من تأثير المشاريع المتطورة.

يمكن أن تؤدي أنماط حركة المرور المرتفعة إلى أخطاء تجاوز الحصة. في سيناريو تجاوز الحصة المحدّدة، يعرض النظام رمز حالة HTTP 429 (QUOTA_EXCEEDED) حتى تتم إعادة تعبئة الحصة في الدقيقة التالية. قد يتم أيضًا عرض 429 ردًا في حالات التحميل الزائد، لذا ننصحك بشدة بالتعامل مع نماذج 429 وفقًا للاقتراحات المنشورة.

تجدر الإشارة إلى ما يلي:

• تقيس حصة عملية استلام الرسائل الإلكترونية الرسائل، وليس الطلبات.
• ويتم احتساب أخطاء العميل (رمز حالة HTTP 400-499) (باستثناء 429).
• تكون الحصص في الدقيقة، ولكن لا تتم محاذاة هذه الدقائق مع الساعة.

حصة المراقبة

يمكنك الاطّلاع على الحصة والاستخدام والأخطاء على Google Cloud Console:

1. انتقِل إلى وحدة تحكُّم Google Cloud
2. اختَر واجهات برمجة التطبيقات والخدمات.
3. من قائمة الجدول، اختَر Firebase Cloud Messaging API.
4. اختَر حدود الحصة والنظام.

ملاحظة: لا تتوافق هذه الرسوم البيانية بدقة مع دقائق الحصة، مما يعني أنه قد يتم عرض 429s عندما يبدو أن عدد الزيارات أقل من الحصة.

طلب زيادة في الحصة

قبل طلب زيادة الحصة، تأكَّد مما يلي:

• يزيد استخدامك عادةً عن حصة تبلغ ≥ 80% لمدة 5 دقائق متتالية على الأقل في اليوم.
• لديك أقل من 5% من نسبة أخطاء العميل، خاصةً أثناء ذروة حركة الزيارات.
• تلتزم بأفضل الممارسات لإرسال الرسائل على نطاق واسع.

في حال استيفاء هذه المعايير، يمكنك إرسال طلب لزيادة الحصة بنسبة تصل إلى +25% وستبذل خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" قصارى جهدها لتلبية الطلب (لا يمكن ضمان حدوث زيادة).

إذا كنت بحاجة إلى المزيد من حصة الرسائل التي تظهر عند استلام الرسالة بسبب وشيكة الإطلاق أو حدث مؤقت، اطلب حصتك قبل 15 يومًا على الأقل لتوفير الوقت الكافي لمعالجة الطلب. للطلبات الكبيرة (أكثر من 18 مليون رسالة في الدقيقة)، يلزم إرسال إشعار قبل 30 يومًا على الأقل. لا تزال عمليات الإطلاق وطلبات الأحداث الخاصة خاضعة لنسبة الخطأ لدى العميل ومتطلبات أفضل الممارسات.

يمكنك أيضًا الاطّلاع على الأسئلة الشائعة حول حصص "المراسلة عبر السحابة الإلكترونية من Firebase".

الحد الأقصى للرسائل المرتبطة بالموضوع

إنّ معدّل إضافة أو إزالة الاشتراك في الموضوع يقتصر على 3,000 طلب في الثانية لكل مشروع.

للتعرُّف على معدلات إرسال الرسائل، يُرجى الاطّلاع على تقييد المعجبين.

تقييد تدفق البيانات

توزيع الرسائل هو عملية إرسال رسالة إلى أجهزة متعددة، مثلاً عند استهداف مواضيع ومجموعات أو عند استخدام أداة إنشاء الإشعارات لاستهداف شرائح جمهور أو شرائح مستخدمين.

لا يتم توزيع الرسائل بشكل فوري، ومن ثم يكون لديك أحيانًا عدة معجبين في الوقت نفسه. نحن نحدّ من عدد المعجبين المتزامنين في الرسائل لكل مشروع إلى 1,000. بعد ذلك، قد نرفض طلبات الموزَّع الإضافية أو نؤجل عملية توزيع هذه الطلبات حتى تكتمل بعض عمليات التوزيع الجارية.

يتأثر معدل التوزيع الفعلي القابل للتحقيق بعدد المشروعات التي تطلب توزيعات واسعة في نفس الوقت. ويُعتبر معدل التوزيع الموزَّع 10000 طلب في الثانية لمشروع فردي أمرًا غير شائع، إلا أن هذا الرقم لا يُعد ضمانًا لأنه ناتج عن الحِمل الإجمالي على النظام. من المهم ملاحظة أن سعة التوزيع المتاحة مقسمة بين المشروعات وليس عبر طلبات التوزيع. لذلك، إذا كان مشروعك يحتوي على عمليتي توزيع قيد التقدم، فلن يرى كل توزيع سوى نصف معدل التوزيع المتاح. الطريقة الموصى بها لزيادة سرعة المعجبين هي أن يكون لديك فقط توزيع نشط واحد قيد التقدم في كل مرة.

تقييد الرسائل القابلة للتصغير

كما هو موضح أعلاه، الرسائل القابلة للتصغير هي إشعارات خالية من المحتوى مصممة للتصغير فوق بعضها البعض. وفي حال تكرار إرسالك الرسالة نفسها إلى أحد التطبيقات بشكل متكرر جدًا، نؤخّر (تقييد) الرسائل لتقليل تأثير ذلك على بطارية المستخدم.

على سبيل المثال، إذا أرسلت أعدادًا كبيرة من طلبات مزامنة البريد الإلكتروني الجديدة إلى جهاز واحد، قد نؤخر طلب مزامنة البريد الإلكتروني التالي لبضع دقائق حتى يمكن مزامنة الجهاز بمعدّل أقل. ويتم إجراء هذا التقييد بشكل صارم للحد من تأثير البطارية الذي يواجهه المستخدم.

إذا كانت حالة الاستخدام تتطلب أنماط إرسال متسلسلة عالية، قد تكون الرسائل غير القابلة للتصغير الخيار الصحيح. بالنسبة لمثل هذه الرسائل، تأكد من تضمين المحتوى في هذه الرسائل لتقليل تكلفة البطارية.

نحدّ من الرسائل القابلة للتصغير إلى سلسلة من 20 رسالة لكل تطبيق على كل جهاز، مع إعادة تعبئة رسالة واحدة كل 3 دقائق.

تقييد خادم XMPP

تنبيه: تم إيقاف ميزة إرسال الرسائل (بما في ذلك الرسائل الرئيسية) من خلال FCM وواجهات برمجة تطبيقات HTTP القديمة لـ FCM في 20 حزيران (يونيو) 2023 وستتم إزالتها في حزيران (يونيو) 2024. إذا كنت تستخدم واجهات برمجة التطبيقات القديمة لإرسال "المراسلة عبر السحابة الإلكترونية من Firebase"، ننصحك بشدة بنقل البيانات إلى واجهة برمجة التطبيقات HTTP v1 أو استخدام SDK للمشرف لإنشاء طلبات الإرسال.

نحدّ من معدّل الاتصال بخوادم FCM XMPP إلى 400 اتصال في الدقيقة لكل مشروع. ولا ينبغي أن يمثل ذلك مشكلة في تسليم الرسائل، إنما المهم هو ضمان استقرار النظام. تتيح خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" 2,500 اتصال بالتوازي لكل مشروع

بالنسبة إلى المراسلات الأولية باستخدام XMPP، تفرض خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" حدودًا على الرسائل الأولية بقيمة 1,500,000 لكل دقيقة لكل مشروع لتجنُّب التحميل الزائد لخوادم الوجهة الرئيسية.

نحدّ من وصول الرسائل المرسَلة إلى كل جهاز بمعدّل 1,000 في الدقيقة للحماية من استنزاف البطارية بسبب الأداء السيئ للتطبيق.

الحد الأقصى لمعدل الرسائل إلى جهاز واحد

بالنسبة إلى Android، يمكنك إرسال ما يصل إلى 240 رسالة في الدقيقة و5,000 رسالة في الساعة إلى جهاز واحد. يهدف هذا الحدّ المرتفع إلى السماح بالزيارات على المدى القصير، على سبيل المثال، عندما يتفاعل المستخدمون بسرعة عبر الدردشة. يمنع هذا الحد الأخطاء في إرسال منطقي من استنزاف البطارية على الجهاز دون قصد.

في أجهزة iOS، سنعرض رسالة خطأ عندما يتجاوز المعدّل حدود أسماء نقاط الوصول (APN).

تنبيه: لا ترسِل الرسائل بشكل روتيني بالقرب من هذا الحد الأقصى لمعدّل الإرسال. قد يؤدي ذلك إلى إهدار موارد المستخدمين النهائيين، وقد يتم تصنيف تطبيقك على أنّه مسيء.

منافذ FCM وجدار الحماية

وإذا كانت مؤسستك تمتلك جدار حماية لتقييد عدد الزيارات من الإنترنت أو منه، يجب إعداده للسماح للأجهزة الجوّالة بالاتصال بخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" حتى تتلقّى الأجهزة على شبكتك الرسائل. تستخدم خدمة FCM عادةً المنفذ 5228، لكنها تستخدم أحيانًا 443 و5229 و5230.

بالنسبة إلى الأجهزة التي تتصل بشبكتك، لا توفّر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" عناوين IP محدّدة لأنّ نطاق عناوين IP يتغيّر بشكل متكرر جدًا وقد تصبح قواعد جدار الحماية قديمة، ما يؤثّر في تجربة المستخدمين. من الناحية المثالية، يمكنك استخدام المنافذ 5228-5230 و443 في القائمة المسموح بها بدون قيود على عناوين IP. ومع ذلك، إذا كان لا بد من حظر عنوان IP، يجب إضافة جميع عناوين IP المدرجة في goog.json إلى القائمة المسموح بها. يتم تحديث هذه القائمة الكبيرة بانتظام، ويُوصى بتحديث القواعد الخاصة بك شهريًا. غالبًا ما تكون المشاكل الناتجة عن قيود عناوين IP لجدار الحماية متقطعة ويصعب تشخيصها.

نحن نقدم مجموعة من أسماء النطاقات التي يمكن إدراجها في القائمة المسموح بها بدلاً من عناوين IP. في ما يلي أسماء المضيفين هذه. إذا بدأنا في استخدام أسماء مضيفين إضافية، فسنقوم بتحديث القائمة هنا. قد يكون استخدام أسماء النطاقات لقاعدة جدار الحماية أو لا يعمل في جهاز جدار الحماية.

منافذ 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. وسيسمح لنا ذلك بتوفير اتصال موثوق به مع تقليل استهلاك البطارية للأجهزة الجوّالة الخاصة بالمستخدمين.

ملاحظة: إذا كنت تتلقّى إشعارات عبر أسماء نقاط الوصول (APN)، تأكَّد أيضًا من فتح المنافذ التي تحدّدها Apple.

تفاعلات شبكة VPN وتجاوزها

تتخذ خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" خطوات مختلفة لضمان موثوقية اتصال الرسائل الفورية من الهاتف إلى الخادم وتوفُّره بقدر الإمكان. يؤدي استخدام شبكة VPN إلى تعقيد هذه الجهود.

تحجب الشبكات الافتراضية الخاصة المعلومات الأساسية التي تحتاجها خدمة FCM لضبط اتصالها لزيادة الموثوقية وعمر البطارية إلى أقصى حد. في بعض الحالات، تنقطع الشبكات الافتراضية الخاصة الاتصالات طويلة الأمد بشكل نشط مما يؤدي إلى تجربة سيئة للمستخدم بسبب فوات الرسائل أو تأخرها أو ارتفاع تكلفة البطارية. عندما يتم ضبط شبكة VPN للسماح لنا بذلك، نتجاوز الشبكة الافتراضية الخاصة باستخدام اتصال مشفّر (عبر شبكة Wi-Fi أو LTE الأساسية) لضمان توفير تجربة موثوقة ومألوفة للبطارية. يرتبط استخدام خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" للشبكات الافتراضية الخاصة القابلة للتجاوز بقناة الإشعارات الفورية التي توفّرها خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". وتستخدم حركة بيانات "المراسلة عبر السحابة الإلكترونية من Firebase" الأخرى، مثل زيارات التسجيل، الشبكة الافتراضية الخاصة إذا كانت نشطة. عندما يتجاوز اتصال "المراسلة عبر السحابة الإلكترونية من Firebase" شبكة VPN، ستفقد مزايا إضافية قد توفّرها الشبكة الافتراضية الخاصة، مثل إخفاء عناوين IP.

سيكون للشبكات الافتراضية الخاصة (VPN) طرق مختلفة للتحكم في ما إذا كان يمكن تجاوزها أم لا. للحصول على تعليمات، يمكنك الاطّلاع على وثائق الشبكة الافتراضية الخاصة.

إذا لم يتم ضبط شبكة VPN بحيث يمكن تجاوزها، سيستخدم "المراسلة عبر السحابة الإلكترونية من Firebase" الشبكة الافتراضية الخاصة للاتصال بالخادم. وقد يؤدي ذلك إلى فترات زمنية تتأخر فيها الرسائل وقد يؤدي إلى زيادة استهلاك البطارية مع الحفاظ على الاتصال عبر شبكة VPN.

بيانات الاعتماد

بناءً على ميزات "المراسلة عبر السحابة الإلكترونية من Firebase" التي تنفّذها، قد تحتاج إلى الحصول على بيانات الاعتماد التالية من مشروع Firebase:

رقم تعريف المشروع	معرّف فريد لمشروعك على Firebase، ويُستخدم في الطلبات المُرسَلة إلى نقطة نهاية HTTP للإصدار 1 من خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". تتوفر هذه القيمة في لوحة الإعدادات في "وحدة تحكُّم Firebase".
الرمز المميّز للتسجيل	سلسلة رمز مميّز فريدة تحدِّد كل مثيل لتطبيق عميل يجب أن يتوفّر الرمز المميّز للتسجيل للمراسلة الجماعية على جهاز واحد وجهاز واحد. يُرجى العِلم أنّه يجب الحفاظ على سرية الرموز المميّزة للتسجيل.
معرّف المرسِل	قيمة رقمية فريدة يتم إنشاؤها عند إنشاء مشروعك على Firebase، وتتوفّر في علامة التبويب المراسلة عبر السحابة الإلكترونية في لوحة الإعدادات في وحدة تحكُّم Firebase. يُستخدم معرّف المُرسِل لتحديد كل مُرسِل يمكنه إرسال رسائل إلى تطبيق العميل.
رمز الدخول	يشير هذا المصطلح إلى رمز مميّز قصير الأجل من OAuth 2.0 يسمح بالطلبات المرسَلة إلى HTTP v1. هذا الرمز المميّز مرتبط بحساب خدمة ينتمي إلى مشروعك على Firebase. لإنشاء رموز الدخول وتدويرها، اتّبِع الخطوات الموضّحة في الموافقة على طلبات الإرسال.
مفتاح الخادم (للبروتوكولات القديمة **متوقّفة نهائيًا**)	مفتاح خادم يفوّض خادم تطبيقك بالوصول إلى خدمات Google، بما في ذلك إرسال الرسائل عبر البروتوكولات القديمة للمراسلة عبر السحابة الإلكترونية من Firebase. ملاحظة مهمة: لا تضمِّن مفتاح الخادم في أي مكان في رمز العميل. تأكَّد أيضًا من استخدام مفاتيح الخادم فقط لمصادقة خادم التطبيقات. رفضت ميزة "المراسلة عبر السحابة الإلكترونية من Firebase" مفاتيح Android ونظام Apple الأساسي والمتصفّح.