لمحة عن رسائل "المراسلة عبر السحابة الإلكترونية من 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 اختبار أ/ب المستنِد إلى الإحصاءات لمساعدتك في تحسين الرسائل التسويقية و تعديلها.

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

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

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

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

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

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

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

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

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

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

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

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

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

يوفّر 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‏ 1 لإعلام أحد المشتركين في مجلة بأنّه يتوفّر محتوى جديد للتنزيل:

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

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

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

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

التفاعلات مع شبكة 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 ومفاتيح المتصفّح.