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 ارائه شده توسط گوگل.
  • سرور برنامه خود و یا دیگر محیط سرور مورد اعتماد که در آن سرور اجرا می شود منطق خود را، مانند توابع Cloud برای فایربیس یا دیگر محیط های ابر مدیریت شده توسط Google.

سرور برنامه یا محیط سرور مورد اعتماد شما درخواست های پیام را به پشتیبان FCM ارسال می کند ، و سپس پیامها را به برنامه های سرویس گیرنده اجرا شده در دستگاه کاربران هدایت می کند.

شرایط مورد نیاز برای محیط سرور مورد اعتماد

محیط سرور برنامه شما باید دارای معیارهای زیر باشد:

  • قادر به ارسال درخواست پیام با فرمت مناسب به باطن FCM.
  • قادر به رسیدگی به درخواست و ارسال مجدد آنها با استفاده از نمایی پشت خاموش.
  • قادر به ذخیره ایمن اعتبار سرور و نشانه های ثبت نام مشتری است.
  • برای پروتکل XMPP (در صورت استفاده) ، سرور باید قادر به تولید شناسه پیام باشد تا هر پیامی را که ارسال می کند به طور منحصر به فرد شناسایی کند (باطن FCM HTTP شناسه های پیام را تولید می کند و آنها را در پاسخ باز می گرداند). شناسه های پیام XMPP باید به ازای هر شناسه فرستنده منحصر به فرد باشد.

انتخاب گزینه سرور

شما نیاز به تصمیم گیری در یک راه برای تعامل با سرور FCM: یا با استفاده از فایربیس محیط مدیریت SDK و یا پروتکل های خام. SDK سرپرست Firebase به دلیل پشتیبانی از آن در زبانهای برنامه نویسی محبوب و روشهای مناسب برای مدیریت احراز هویت و مجوز ، روش توصیه شده است.

گزینه های تعامل با سرورهای FCM شامل موارد زیر است:
  • فایربیس محیط مدیریت SDK، که دارای پشتیبانی از گره ، جاوا ، پایتون ، C # ، و برو .
  • FCM HTTP V1 API است که اکثر تا تاریخ از گزینه های پروتکل، با مجوز امن تر و قابل انعطاف قابلیت های پیام رسانی کراس پلت فرم است (فایربیس محیط مدیریت SDK در این پروتکل بر اساس و فراهم می کند تمام مزایای ذاتی آن).
  • میراث HTTP پروتکل.
  • XMPP پروتکل سرور. توجه داشته باشید که اگر می خواهید از پیام های بالادستی برنامه های مشتری خود استفاده کنید ، باید از XMPP استفاده کنید.

SDK سرپرست Firebase برای FCM

API Admin FCM احراز هویت را با پس زمینه مدیریت می کند و ارسال پیام و مدیریت اشتراک موضوعات را تسهیل می کند. با استفاده از SDK مدیریت Firebase ، می توانید:

  • ارسال پیام به دستگاه های جداگانه
  • پیام ها را به موضوعات ارسال کنید و گزاره های شرط را که با یک یا چند موضوع مطابقت دارد ارسال کنید.
  • مشترک شدن و لغو اشتراک دستگاه ها در و از موضوعات
  • بارهای پیام متناسب با سیستم عامل های مختلف ایجاد کنید

SDK Admin Node.js روش هایی برای ارسال پیام به گروه های دستگاه ارائه می دهد.

برای تنظیم فایربیس محیط مدیریت SDK، و اضافه کردن فایربیس محیط مدیریت SDK به سرور خود را . اگر شما در حال حاضر یک پروژه فایربیس، با شروع اضافه کردن SDK . سپس، یک بار فایربیس محیط مدیریت SDK نصب شده است، شما می توانید منطق نوشتن شروع به درخواست ساخت ارسال .

پروتکل های سرور FCM

در حال حاضر FCM این پروتکل های سرور خام را ارائه می دهد:

سرور برنامه شما می تواند از این پروتکل ها به صورت جداگانه یا همزمان استفاده کند. از آنجا که برای ارسال پیام به چندین سیستم عامل به روزترین و انعطاف پذیرترین است ، FCM HTTP v1 API تا جایی که امکان پذیر است توصیه می شود. اگر نیازهای شما شامل پیام رسانی بالادست از دستگاه ها به سرور است ، باید پروتکل XMPP را پیاده سازی کنید.

پیام های XMPP با پیام های HTTP در موارد زیر متفاوت است:

  • پیام های بالادست/پایین دست
    • HTTP: فقط پایین دست ، ابری به دستگاه.
    • XMPP: بالادست و پایین دست (دستگاه به ابر ، ابر به دستگاه).
  • پیام رسانی (همزمان یا ناهمزمان)
    • HTTP: همزمان. سرورهای برنامه پیامها را به عنوان درخواست HTTP POST ارسال می کنند و منتظر پاسخ می مانند. این مکانیزم همزمان است و فرستنده را از ارسال پیام دیگری تا دریافت پاسخ منع می کند.
    • XMPP: ناهمزمان. سرورهای برنامه با سرعت کامل خطوط را از طریق اتصالات ثابت XMPP به/از همه دستگاه های خود ارسال و دریافت می کنند. سرور اتصال XMPP اعلان های تأیید یا خرابی (در قالب پیام های ویژه XMPP با کد ACK و NACK JSON) را به صورت ناهمزمان ارسال می کند.
  • JSON
    • HTTP: پیام های JSON به عنوان HTTP POST ارسال می شوند.
    • XMPP: پیام های JSON که در پیام های XMPP محصور شده اند.
  • متن ساده
    • HTTP: پیام های متنی ساده به عنوان HTTP POST ارسال می شوند.
    • XMPP: پشتیبانی نمی شود.
  • Multicast پایین دست ارسال به چندین رمز ثبت.
    • HTTP: در قالب پیام JSON پشتیبانی می شود.
    • XMPP: پشتیبانی نمی شود.

پیاده سازی پروتکل سرور HTTP

برای ارسال پیام ، سرور برنامه یک درخواست POST با هدر HTTP و بدنه HTTP متشکل از جفت های مقدار JSON صادر می کند. برای جزئیات در مورد هدر و بدن گزینه های، و ساخت برنامه سرور ارسال درخواست

پیاده سازی پروتکل سرور XMPP

بار JSON برای پیام های FCM مشابه پروتکل HTTP است ، با این استثنا:

  • از چندین گیرنده پشتیبانی نمی شود.
  • FCM اضافه می کند زمینه message_id ، که مورد نیاز است. این شناسه پیام را در یک اتصال XMPP به طور منحصر به فرد مشخص می کند. تصدیق یا NACK از FCM با استفاده از message_id به شناسایی یک پیام از سرورهای برنامه به FCM ارسال می شود. بنابراین، این مهم است که این message_id نه تنها منحصر به فرد (در هر شود فرستنده 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" است. اما وقتی پاسخ حاوی خطا باشد ، 2 شکل مختلف وجود دارد که پیام می تواند در زیر توضیح داده شود.

پیام 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 .

خطای استانزا

همچنین در موارد خاص می توانید خطای بند را دریافت کنید. خطای بند شامل موارد زیر است:

  • کد خطای Stanza
  • شرح خطای Stanza (متن رایگان).

مثلا:

<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 دیگر، باز کردن یک اتصال جدید در صورت لزوم. با این حال ، شما باید اتصال اصلی را باز نگه دارید و به دریافت پیامهایی که ممکن است از طریق اتصال (و ACKing آنها) دریافت شوند ، ادامه دهید - 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. پیام / ACK جریان است.

برعکس ، برای جلوگیری از بارگذاری بیش از حد سرور برنامه ، در صورت وجود پیام های ناشناخته زیاد ، FCM ارسال را متوقف می کند. بنابراین ، سرور برنامه باید پیامهای بالادستی را که از برنامه مشتری از طریق FCM دریافت می کنند ، در اسرع وقت "ACK" کند تا جریان ثابت پیامهای دریافتی را حفظ کند. محدودیت پیامی که در بالا ذکر شد برای این ACK ها اعمال نمی شود. حتی اگر تعداد پیام های معلق به 100 برسد ، سرور برنامه باید به ارسال ACK برای پیام های دریافتی از FCM ادامه دهد تا از تحویل پیام های بالادستی جدید جلوگیری شود.

ACK ها فقط در زمینه یک اتصال معتبر هستند. اگر اتصال قبل از پیغام ACKed بسته شده باشد ، سرور برنامه باید منتظر بماند تا FCM پیام پیشین را دوباره ارسال کند تا دوباره آن را ACK کند. به طور مشابه ، همه پیامهای معلق که ACK/NACK برای آنها قبل از بسته شدن اتصال از FCM دریافت نشده است ، باید دوباره ارسال شوند.