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

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

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

باستخدام FCM، يمكنك إرسال نوعَين من الرسائل إلى العملاء:

• رسائل الإشعارات، التي يُشار إليها أحيانًا باسم "الرسائل المعروضة" تعالج حزمة تطوير البرامج (SDK) FCM هذه الطلبات تلقائيًا.
• رسائل البيانات التي يعالجها تطبيق العميل

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

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

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

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

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

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

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

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

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

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

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

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

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

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

في ما يلي رسالة بتنسيق 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، لا تفسّرها سوى نُسخ التطبيق التي تعمل على المنصة المحدّدة.

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

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

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

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

يمكن لجميع نُسخ التطبيق، بغض النظر عن المنصة، تفسير الحقلَين التاليَين المشترَكين:

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

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

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

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

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

خيارات التسليم

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

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

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

لا تضمن FCM ترتيب التسليم.

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

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

الرسالة القابلة للطي هي رسالة قد يتم استبدالها برسالة جديدة إذا لم يتم تسليمها إلى الجهاز بعد.

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

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

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

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

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

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

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

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

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

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

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

في ما يلي مثال على رسالة ذات أولوية عادية تم إرسالها عبر بروتوكول 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"
      }
    }
  }
}

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

• مستندات نقاط الوصول (APN)
• ضبط أولوية الرسائل وإدارتها (Android)
• أهمية رسالة Web Push

حالات الاستخدام المُهمّة للحياة

إنّ واجهات FCM API غير مصمَّمة لتنبيهات الطوارئ أو غيرها من الأنشطة الخطيرة التي قد يؤدي استخدامها أو الإخفاق في استخدامها إلى الوفاة أو التعرُّض لإصابة شخصية أو إلحاق الضرر بالبيئة (مثل تشغيل المنشآت النووية أو مراقبة حركة المرور الجوي أو أنظمة المحافظة على الحياة). ويُحظر صراحةً مثل هذا الاستخدام بموجب الفقرة 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:

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

ملاحظة: لا تتمّ مواءمة هذه الرسوم البيانية بالوقت بدقة مع دقائق الحصة، ما يعني أنّه قد يتم عرض أخطاء 429 عندما تكون عدد الزيارات أقل من الحصة.

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

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

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

إذا كنت تستوفي هذه المعايير، يمكنك إرسال طلب زيادة الحصة بنسبة تصل إلى ‎25%، وستبذل FCM كل الجهود العملية لتلبية الطلب (لا يمكن ضمان أي زيادة).

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

اطّلِع أيضًا على الأسئلة الشائعة حول قيود FCM.

الحد الأقصى المسموح به لرسائل المواضيع

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

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

تقييد توزيع البيانات

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

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

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

الحد من عدد الرسائل القابلة للتصغير

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

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

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

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

الحدّ الأقصى المسموح به لعرض نطاق خادم XMPP

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

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

منافذ 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 Cloud Messaging خطوات مختلفة لضمان أنّ اتصال رسائل الدفع من الهاتف إلى الخادم موثوق به ومتاح قدر الإمكان. ويؤدي استخدام شبكة VPN إلى تعقيد هذا الجهد.

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

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

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

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

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

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