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

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

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

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

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

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

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

  1. في بيئة موثوق بها، مثل Cloud Functions أو خادم تطبيقك، استخدِم Admin SDK أو HTTP v1 API. اضبط مفتاح notification. قد يتضمّن حمولة بيانات اختيارية. يمكن تصغيرها دائمًا.

    يمكنك الاطّلاع على بعض أمثلة على إشعارات العرض وإرسال حمولات الطلبات.

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

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

يعود إليك تحديد طريقة استخدام حمولة FCM data لتنفيذ نظام التشفير الذي تختاره. تأكَّد من عدم استخدام أي كلمات محجوزة في أزواج المفتاح/القيمة المخصّصة. تشمل الكلمات المحجوزة "from" أو "notification" أو "message_type" أو أي كلمة تبدأ بـ "google" أو "gcm".

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

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

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

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

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

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

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

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

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

عندما تريد إرسال القيم إلى منصات معيّنة فقط، لا تستخدِم الحقول الشائعة، بل استخدِم الحقول الخاصة بالمنصة. على سبيل المثال، لإرسال إشعار إلى منصات 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 من خلال FCM collapse_key، وعلى أجهزة Apple من خلال apns-collapse-id، وعلى JavaScript/الويب من خلال Topic. للاطّلاع على التفاصيل، يُرجى الرجوع إلى الأوصاف الواردة في هذا القسم والمستندات المرجعية ذات الصلة.

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

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

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

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

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

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

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

إنّ واجهات برمجة التطبيقات 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. لإنشاء رموز دخول وتغييرها بشكل دوري، اتّبِع الخطوات الموضّحة في تفويض طلبات الإرسال.