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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

تأكَّد من عدم استخدام أي كلمات محجوزة في أزواج المفتاح/القيمة المخصّصة. تشمل الكلمات المحجوزة "from" أو "notification" أو "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. في أداة إنشاء الإشعارات، استخدِم حقول البيانات المخصّصة في الخيارات المتقدّمة.

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

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

في ما يلي رسالة بتنسيق 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 من FCM لطلبات الرسائل ضبط جميع الحقول المتاحة في عنصر message. ويشمل ذلك ما يلي:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• تضبط مدة بقاء طويلة لمنصتَي Android والويب، مع ضبط أولوية رسالة APNs (منصات 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 من خلال FCMcollapse_key، وعلى 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 في البروتوكولات القديمة (جميع الأنظمة الأساسية)

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

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

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

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

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

في ما يلي مثال على رسالة ذات أولوية عادية تم إرسالها عبر بروتوكول HTTP الإصدار 1 ‏(FCM) لإعلام أحد المشتركين في مجلة بأنّه يتوفّر محتوى جديد للتنزيل:

{
  "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)
• مدى إلحاح الإشعارات الفورية على الويب

حالات الاستخدام الحرجة

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

ضبط مدة بقاء الرسالة

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

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

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

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

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

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

في ما يلي مثال على طلب يتضمّن قيمة TTL:

{
  "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: إذا كانت هناك رسالة مخزّنة ومُنتظِرة للتسليم تتضمّن مفتاح دمج (ورمز تسجيل) مطابقًا، يتم تجاهل الرسالة القديمة واستبدالها بالرسالة الجديدة (أي يتم دمج الرسالة القديمة مع الرسالة الجديدة). ومع ذلك، إذا لم يتم ضبط مفتاح الدمج، سيتم تخزين الرسالتين الجديدة والقديمة لتسليمهما في المستقبل.

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

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

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

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

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

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

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

ملاحظة: إنّ الحدود الموضّحة في هذا القسم قابلة للتغيير.

الحدّ من عدد الرسائل الواردة

قدّمت واجهة برمجة التطبيقات 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 طلب في الثانية لمشروع فردي، ولكن هذا الرقم ليس مضمونًا وهو نتيجة إجمالي الحمل على النظام. يُرجى العِلم أنّ سعة النشر المتاحة يتم تقسيمها بين المشاريع وليس بين طلبات النشر. لذا، إذا كان مشروعك يتضمّن عمليتَي توسيع نطاق قيد التقدّم، لن ترى كل عملية سوى نصف معدّل توسيع النطاق المتاح. الطريقة المقترَحة لتحقيق أقصى سرعة في عملية التوزيع هي أن يكون لديك عملية توزيع نشطة واحدة فقط قيد التقدّم في كل مرة.

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

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

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

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

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

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

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

بالنسبة إلى iOS، نعرض رسالة خطأ عندما يتجاوز المعدّل حدود APNs.

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

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

ملاحظة: إذا كنت تتلقّى إشعارات عبر APNs، تأكَّد من أنّك فتحت أيضًا المنافذ التي حدّدتها Apple.

التفاعلات مع شبكات VPN وإمكانية تجاوزها

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

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

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

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

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

استنادًا إلى ميزات FCM التي تستخدمها، قد تحتاج إلى بيانات الاعتماد التالية من مشروعك على Firebase:

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