Join us for Firebase Summit on November 10, 2021. Tune in to learn how Firebase can help you accelerate app development, release with confidence, and scale with ease. Register

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

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

  • الخلفية FCM التي تقدمها جوجل.
  • الخادم التطبيق الخاص بك أو غيرها من بيئة الخوادم الموثوق بها حيث الخاص بك يعمل منطق الخادم، مثل وظائف السحب لFirebase أو غيرها من البيئات السحابية تدار من قبل جوجل.

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

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

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

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

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

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

تتضمن خيارات التفاعل مع خوادم FCM ما يلي:
  • وFirebase مشرف SDK، والذي يحظى بدعم ل عقدة ، جافا ، بيثون ، C # ، و العودة .
  • و FCM HTTP V1 API ، والذي هو الأكثر حتى الآن من الخيارات البروتوكول، مع تفويض أكثر أمنا ومرونة قدرات التراسل عبر منصة (ويستند المسؤول SDK Firebase على هذا البروتوكول ويوفر كافة مزايا المتأصلة فيها).
  • إرث HTTP بروتوكول.
  • و XMPP بروتوكول الخادم. لاحظ أنه إذا كنت تريد استخدام الرسائل الأولية من تطبيقات العميل ، فيجب عليك استخدام XMPP.

Firebase Admin SDK for FCM

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

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

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

لإعداد Firebase مشرف SDK، انظر إضافة Firebase الادارية SDK إلى الملقم . إذا كان لديك بالفعل مشروع Firebase، وتبدأ مع إضافة SDK . ثم، مرة واحدة يتم تثبيت الادارية SDK Firebase، يمكنك البدء في الكتابة المنطق ل طلبات بناء الإرسال .

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

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

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

خطأ A NACK هو رسالة XMPP العادية فيها message_type رسالة الحالة هي "صغيرة تافهة". تحتوي رسالة 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:

رسم تخطيطي مفصل لتدفق التحكم بين FCM وخادم التطبيق

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

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

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