بيئة الخادم و FCM

يتكون جانب الخادم من Firebase Cloud Messaging من مكونين:

• الواجهة الخلفية FCM المقدمة من Google.
• خادم التطبيق الخاص بك أو بيئة خادم موثوقة أخرى حيث يتم تشغيل منطق الخادم الخاص بك ، مثل Cloud Functions for Firebase أو البيئات السحابية الأخرى التي تديرها Google.

يرسل خادم التطبيق أو بيئة الخادم الموثوقة طلبات الرسائل إلى الواجهة الخلفية لـ FCM ، والتي تقوم بعد ذلك بتوجيه الرسائل إلى تطبيقات العميل التي تعمل على أجهزة المستخدمين.

متطلبات بيئة الخادم الموثوق بها

يجب أن تستوفي بيئة خادم التطبيق المعايير التالية:

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

اختيار خيار الخادم

ستحتاج إلى تحديد طريقة للتفاعل مع خوادم FCM: إما باستخدام Firebase Admin SDK أو البروتوكولات الأولية. نظرًا لدعمها عبر لغات البرمجة الشائعة وأساليبها الملائمة للتعامل مع المصادقة والتفويض ، فإن Firebase Admin SDK هي الطريقة الموصى بها.

تتضمن خيارات التفاعل مع خوادم FCM ما يلي:

• حزمة Firebase Admin SDK ، والتي تدعم Node و Java و Python و C # و Go .
• واجهة برمجة تطبيقات FCM HTTP v1 ، وهي أحدث خيارات البروتوكول ، مع مصادقة أكثر أمانًا وقدرات مرنة للمراسلة عبر الأنظمة الأساسية (تستند Firebase Admin SDK على هذا البروتوكول وتوفر جميع مزاياها المتأصلة). نظرًا لأنه يتم عادةً إضافة ميزات جديدة إلى واجهة برمجة تطبيقات HTTP v1 فقط ، فإننا نوصي باستخدام واجهة برمجة التطبيقات هذه لمعظم حالات الاستخدام.
• بروتوكول HTTP القديم . يوصى بشدة بالمشاريع الجديدة لاعتماد FCM v1 HTTP API بدلاً من البروتوكول القديم.
• بروتوكول خادم XMPP القديم . يوصى بشدة بالمشاريع الجديدة لاعتماد FCM v1 HTTP API بدلاً من البروتوكول القديم.

Firebase Admin SDK for FCM

تتولى Admin FCM API المصادقة مع الواجهة الخلفية وتسهل إرسال الرسائل وإدارة اشتراكات الموضوعات. باستخدام Firebase Admin SDK ، يمكنك:

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

يوفر Admin Node.js SDK طرقًا لإرسال الرسائل إلى مجموعات الأجهزة.

لإعداد Firebase Admin SDK ، راجع إضافة Firebase Admin SDK إلى خادمك . إذا كان لديك بالفعل مشروع Firebase ، فابدأ بإضافة SDK . تأكد أيضًا من تمكين Cloud Messagin API في صفحة إعدادات Cloud Messaging لمشروعك. بعد ذلك ، بمجرد تثبيت Firebase Admin SDK ، يمكنك البدء في كتابة المنطق لإنشاء طلبات الإرسال .

بروتوكولات خادم FCM

توفر FCM حاليًا بروتوكولات الخادم الأولية هذه:

• واجهة برمجة تطبيقات FCM HTTP v1
• بروتوكول HTTP القديم
• بروتوكول XMPP القديم

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

تختلف رسائل XMPP عن رسائل HTTP بالطرق التالية:

• رسائل المنبع / المصب
  • HTTP: للتنزيل فقط ، من سحابة إلى جهاز.
  • XMPP: المنبع والمصب (من جهاز إلى سحابة ، ومن سحابة إلى جهاز).
• المراسلة (متزامن أو غير متزامن)
  • HTTP: متزامن. ترسل خوادم التطبيقات الرسائل كطلبات HTTP POST وتنتظر الرد. هذه الآلية متزامنة وتمنع المرسل من إرسال رسالة أخرى حتى تلقي الرد.
  • XMPP: غير متزامن. ترسل خوادم التطبيقات / تستقبل الرسائل من / إلى جميع أجهزتها بسرعة كاملة عبر اتصالات XMPP المستمرة. يرسل خادم اتصال XMPP إعلامات إقرار أو فشل (في شكل رسائل ACK خاصة ورسائل XMPP NACK JSON المشفرة) بشكل غير متزامن.
• جسون
  • HTTP: تم إرسال رسائل JSON على أنها HTTP POST.
  • XMPP: رسائل JSON مغلفة في رسائل XMPP.
• نص عادي
  • HTTP: تم إرسال رسائل نصية عادية على أنها HTTP POST.
  • XMPP: غير مدعوم.
• الإرسال المتعدد المتلقين للمعلومات يرسل إلى رموز تسجيل متعددة.
  • HTTP: مدعوم بتنسيق رسالة JSON.
  • XMPP: غير مدعوم.

تنفيذ بروتوكول خادم HTTP

لإرسال رسالة ، يصدر خادم التطبيق طلب POST برأس HTTP وجسم HTTP يتكون من أزواج قيمة مفتاح JSON. للحصول على تفاصيل حول خيارات الرأس والجسم ، راجع إنشاء طلبات إرسال خادم التطبيق

تنفيذ بروتوكول خادم XMPP

حمولة JSON لرسائل FCM مشابهة لبروتوكول HTTP ، مع هذه الاستثناءات:

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

بالإضافة إلى رسائل FCM العادية ، يتم إرسال رسائل التحكم ، ويشار إليها بالحقل message_type في كائن JSON. يمكن أن تكون القيمة إما "ack" أو "nack" أو "control" (انظر التنسيقات أدناه). يمكن أن يتجاهل الخادم الخاص بك أي رسالة FCM بها message_type غير معروف.

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

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

راجع مرجع البروتوكول للحصول على قائمة بجميع معلمات الرسالة.

تنسيق الطلب

رسالة مع الحمولة - رسالة إعلام

هنا مقطع XMPP لرسالة إعلام:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
     "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
     "notification": {
        "title": "Portugal vs. Denmark”,
        "body”: "5 to 1”
      },
      "time_to_live":"600"
  }
  </gcm>
</message>

رسالة مع الحمولة - رسالة بيانات

إليك مقطع XMPP يحتوي على رسالة JSON من خادم التطبيق إلى FCM:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
      "message_id":"m-1366082849205" // new required field
      "data":
      {
          "hello":"world",
      }
      "time_to_live":"600",
  }
  </gcm>
</message>

تنسيق الاستجابة

يمكن أن يكون لاستجابة FCM ثلاثة أشكال ممكنة. الأول هو رسالة "ack" العادية. ولكن عندما تحتوي الاستجابة على خطأ ، فهناك شكلين مختلفين يمكن أن تتخذهما الرسالة ، كما هو موضح أدناه.

رسالة ACK

إليك مقطع XMPP يحتوي على رسالة ACK / NACK من FCM إلى خادم التطبيق:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

رسالة NACK

خطأ NACK هو رسالة XMPP عادية تكون فيها رسالة حالة message_type "nack". تحتوي رسالة NACK على:

• رمز خطأ NACK.
• وصف خطأ NACK.

فيما يلي بعض الأمثلة.

تسجيل سيء:

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationToken",
    "error":"BAD_REGISTRATION",
    "error_description":"Invalid token on 'to' field: SomeInvalidRegistrationId"
  }
  </gcm>
</message>

JSON غير صالح:

<message>
 <gcm xmlns="google:mobile:data">
 {
   "message_type":"nack",
   "message_id":"msgId1",
   "from":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
   "error":"INVALID_JSON",
   "error_description":"InvalidJson: JSON_TYPE_ERROR : Field \"time_to_live\" must be a JSON java.lang.Number: abc"
 }
 </gcm>
</message>

تم تجاوز معدل رسائل الجهاز:

<message id="...">
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"REGID",
    "error":"DEVICE_MESSAGE_RATE_EXCEEDED",
    "error_description":"Downstream message rate exceeded for this registration id"
  }
  </gcm>
</message>

راجع مرجع الخادم للحصول على قائمة كاملة برموز خطأ NACK. ما لم تتم الإشارة إلى خلاف ذلك ، لا ينبغي إعادة محاولة الرسالة NACKed. يجب التعامل مع رموز خطأ NACK غير المتوقعة مثل INTERNAL_SERVER_ERROR .

خطأ مقطع

يمكنك أيضًا الحصول على خطأ مقطع مقطع في بعض الحالات. يحتوي خطأ مقطع مقطع على:

• كود خطأ مقطع.
• وصف خطأ المقطع (نص مجاني).

على سبيل المثال:

<message id="3" type="error" to="123456789@fcm.googleapis.com/ABC">
  <gcm xmlns="google:mobile:data">
     {"random": "text"}
  </gcm>
  <error code="400" type="modify">
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
      InvalidJson: JSON_PARSING_ERROR : Missing Required Field: message_id\n
    </text>
  </error>
</message>

رسائل التحكم

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

تبدو رسالة CONNECTION_DRAINING كما يلي:

<message>
  <data:gcm xmlns:data="google:mobile:data">
  {
    "message_type":"control"
    "control_type":"CONNECTION_DRAINING"
  }
  </data:gcm>
</message>

CONNECTION_DRAINING هو control_type الوحيد المدعوم حاليًا.

التحكم في التدفق

تتلقى كل رسالة يتم إرسالها إلى FCM إما ACK أو استجابة NACK. الرسائل التي لم تتلق أحد هذه الردود تعتبر معلقة. إذا وصل عدد الرسائل المعلقة إلى 100 ، يجب أن يتوقف خادم التطبيق عن إرسال رسائل جديدة وينتظر FCM للإقرار ببعض الرسائل المعلقة الحالية كما هو موضح في الشكل 1:

الشكل 1. رسالة / تدفق ack.

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

ACKs صالحة فقط في سياق اتصال واحد. إذا تم إغلاق الاتصال قبل أن يتم قبول رسالة ، يجب على خادم التطبيق انتظار FCM لإعادة إرسال الرسالة الأولية قبل ACKing مرة أخرى. وبالمثل ، يجب إرسال جميع الرسائل المعلقة التي لم يتم استلام ACK / NACK لها من FCM قبل إغلاق الاتصال مرة أخرى.