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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

قدّمت واجهة برمجة التطبيقات 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 طلب في الثانية لكل مشروع.

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

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

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

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

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

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

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

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

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

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

تقييد خادم XMPP

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

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

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