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

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

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

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

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

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

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

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

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

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

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

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

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

• أولوية عالية: تحاول خدمة 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 والويب/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.

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

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

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