Google is committed to advancing racial equity for Black communities. See how.
ترجمت واجهة Cloud Translation API‏ هذه الصفحة.
Switch to English

بيئة الخادم و 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 for FCM

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

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

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

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

بروتوكولات خادم 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

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

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

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

تسجيل سيء:

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationId",
    "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 الاتصال وسيتم إغلاقه قريبًا. يشير "التصريف" إلى إيقاف تدفق الرسائل الواردة إلى اتصال ، ولكن مع السماح باستمرار كل ما هو موجود بالفعل في خط الأنابيب. عندما تتلقى رسالة 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 الوحيد control_type حاليًا.

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

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

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

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

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