درباره پیام های FCM

Firebase Cloud Messaging ( FCM ) طیف گسترده ای از گزینه ها و قابلیت های پیام رسانی را ارائه می دهد. اطلاعات موجود در این صفحه به شما کمک می کند تا انواع مختلف پیام های FCM و کارهایی که می توانید با آنها انجام دهید را درک کنید.

پیام‌های اعلان با بار داده اختیاری

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

رفتار برنامه هنگام دریافت پیام‌هایی که شامل اعلان‌ها و بارهای داده می‌شوند به این بستگی دارد که آیا برنامه در پس‌زمینه یا پیش‌زمینه قرار دارد – اساساً فعال بودن یا نبودن آن در زمان دریافت.

• در پس‌زمینه ، برنامه‌ها بار اعلان را در سینی اعلان دریافت می‌کنند و تنها زمانی که کاربر روی اعلان ضربه می‌زند، محموله داده را مدیریت می‌کنند.
• زمانی که برنامه شما در پیش زمینه است ، یک شیء پیام با هر دو بار در دسترس دریافت می کند.

در اینجا یک پیام با فرمت JSON حاوی کلید notification و کلید data است:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }
}

گزینه های تحویل

FCM مجموعه خاصی از گزینه‌های تحویل را برای پیام‌های ارسال شده به دستگاه‌های Android فراهم می‌کند و امکان گزینه‌های مشابه را در پلتفرم‌های اپل و وب فراهم می‌کند. به عنوان مثال، رفتار پیام "تاشدنی" در Android از طریق collapse_key FCM ، در Apple از طریق apns-collapse-id و در JavaScript/Web از طریق Topic پشتیبانی می‌شود. برای جزئیات، به توضیحات در این بخش و مستندات مرجع مرتبط مراجعه کنید.

تعیین اولویت یک پیام

شما دو گزینه برای تخصیص اولویت تحویل به پیام های پایین دستی دارید: عادی و اولویت بالا. اگرچه این رفتار در پلتفرم‌ها کمی متفاوت است، اما تحویل پیام‌های عادی و با اولویت بالا به این صورت عمل می‌کند:

• اولویت عادی پیام های اولویت عادی بلافاصله زمانی که برنامه در پیش زمینه است، تحویل داده می شود. برای برنامه‌های پس‌زمینه، ممکن است تحویل به تأخیر بیفتد. برای پیام‌هایی که کمتر به زمان حساس هستند، مانند اعلان‌های ایمیل جدید، همگام‌سازی رابط کاربری خود، یا همگام‌سازی داده‌های برنامه در پس‌زمینه، اولویت تحویل عادی را انتخاب کنید.

• اولویت بالا FCM سعی می‌کند پیام‌های با اولویت بالا را فوراً ارسال کند، حتی اگر دستگاه در حالت Doze باشد. پیام های با اولویت بالا برای محتوای حساس به زمان و قابل مشاهده توسط کاربر هستند.

هنگام ارسال پیام های داده به دستگاه های اپل، اولویت باید روی 5 یا اولویت عادی تنظیم شود. پیام‌هایی که با اولویت بالا ارسال می‌شوند توسط بخش پشتیبان FCM با خطای INVALID_ARGUMENT رد می‌شوند.

در اینجا نمونه‌ای از یک پیام اولویت معمولی است که از طریق پروتکل FCM HTTP v1 ارسال می‌شود تا به مشترک مجله اطلاع دهد که محتوای جدید برای دانلود در دسترس است:

{
  "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"
      }
    }
  }
}

برای جزئیات بیشتر پلتفرم خاص در مورد تنظیم اولویت پیام:

• اسناد APN
• تنظیم و مدیریت اولویت پیام (اندروید)
• فوریت پیام فشار وب

موارد استفاده حیاتی زندگی

APIهای FCM برای هشدارهای اضطراری یا سایر فعالیت‌های پرخطر که در آن استفاده یا خرابی APIها می‌تواند منجر به مرگ، آسیب‌های شخصی یا آسیب‌های محیطی شود (مانند عملکرد تأسیسات هسته‌ای، کنترل ترافیک هوایی یا سیستم‌های پشتیبانی حیات) طراحی نشده‌اند. هر گونه استفاده از این قبیل صراحتاً طبق بخش 4 ممنوع است. 7 از شرایط خدمات. شما تنها مسئول مدیریت مطابقت برنامه خود با شرایط و هرگونه آسیب ناشی از عدم رعایت شما هستید. Google APIها را «همان‌طور که هست» ارائه می‌کند و این حق را برای خود محفوظ می‌دارد که به هر دلیل و در هر زمان، APIها یا هر بخش یا ویژگی یا دسترسی شما به آن‌ها را بدون مسئولیت یا تعهد دیگری در قبال شما یا کاربرانتان قطع کند.

تنظیم طول عمر یک پیام

FCM معمولاً پیام ها را بلافاصله پس از ارسال ارسال می کند. با این حال، این ممکن است همیشه امکان پذیر نباشد. به عنوان مثال، اگر پلتفرم اندروید باشد، دستگاه ممکن است خاموش، آفلاین یا غیرقابل دسترس باشد. یا FCM ممکن است عمداً پیام‌ها را به تأخیر بیندازد تا از مصرف بیش از حد منابع توسط برنامه و تأثیر منفی بر عمر باتری جلوگیری کند.

هنگامی که این اتفاق می افتد، FCM پیام را ذخیره می کند و به محض اینکه امکان پذیر باشد، آن را تحویل می دهد. در حالی که این در اکثر موارد خوب است، برخی از برنامه‌ها هستند که ممکن است هرگز پیام دیرهنگام برای آنها ارسال نشود. به عنوان مثال، اگر پیام یک تماس ورودی یا اعلان چت تصویری باشد، فقط برای مدت کوتاهی قبل از پایان تماس معنادار است. یا اگر پیام دعوت به یک رویداد باشد، اگر بعد از پایان رویداد دریافت شود، بی فایده است.

در اندروید و وب/جاوا اسکریپت، می توانید حداکثر طول عمر یک پیام را مشخص کنید. مدت زمان باید از 0 تا 2419200 ثانیه (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 متصل باشد، صفحه نمایش روشن باشد و هیچ محدودیتی برای کاهش فشار وجود نداشته باشد، پیام فوراً ارسال می‌شود.

اگر دستگاه متصل باشد اما در Doze باشد، یک پیام با اولویت پایین توسط FCM ذخیره می شود تا زمانی که دستگاه از Doze خارج شود. و اینجاست که پرچم collapse_key نقش بازی می‌کند: اگر قبلاً پیامی با همان کلید کوچک کردن (و رمز ثبت نام) ذخیره شده باشد و منتظر تحویل باشد، پیام قدیمی کنار گذاشته می‌شود و پیام جدید جای آن را می‌گیرد (یعنی پیام قدیمی توسط پیام جدید جمع می‌شود). با این حال، اگر کلید کوچک کردن تنظیم نشده باشد، هر دو پیام جدید و قدیمی برای تحویل آینده ذخیره می شوند.

اگر دستگاه به FCM متصل نباشد، پیام تا زمانی که اتصال برقرار شود ذخیره می‌شود (دوباره با رعایت قوانین کلید کوچک کردن). هنگامی که یک اتصال برقرار می شود، FCM همه پیام های معلق را به دستگاه تحویل می دهد. اگر دستگاه هرگز دوباره وصل نشود (مثلاً اگر بازنشانی به تنظیمات کارخانه انجام شده باشد)، پیام در نهایت تمام می شود و از حافظه FCM حذف می شود. مهلت زمانی پیش‌فرض چهار هفته است، مگر اینکه پرچم time_to_live تنظیم شده باشد.

برای دریافت بینش بیشتر در مورد تحویل یک پیام:

برای دریافت اطلاعات بیشتر در مورد تحویل پیام ها در سیستم عامل های Android یا Apple، به داشبورد گزارش FCM مراجعه کنید، که تعداد پیام های ارسال شده و باز شده در دستگاه های Apple و Android را به همراه داده های "impressions" (اعلان های مشاهده شده توسط کاربران) برای برنامه های Android ثبت می کند.

برای دستگاه‌های Android با پیام‌رسانی مستقیم کانال فعال، اگر دستگاه بیش از یک ماه به FCM وصل نشده باشد، FCM همچنان پیام را می‌پذیرد اما فوراً آن را نادیده می‌گیرد. اگر دستگاه در عرض چهار هفته از آخرین پیام داده ای که به آن ارسال کرده اید متصل شود، کلاینت شما پاسخ تماس ()onDeletedMessages را دریافت می کند. سپس برنامه می‌تواند وضعیت را به درستی مدیریت کند، معمولاً با درخواست همگام‌سازی کامل از سرور برنامه.

در نهایت، زمانی که FCM تلاش می‌کند پیامی را به دستگاه ارسال کند و برنامه حذف شد، FCM فوراً آن پیام را کنار گذاشته و رمز ثبت نام را باطل می‌کند. تلاش‌های بعدی برای ارسال پیام به آن دستگاه منجر به خطای NotRegistered می‌شود.

اعتبارنامه

بسته به ویژگی‌های FCM که پیاده‌سازی می‌کنید، ممکن است به اعتبارنامه‌های زیر از پروژه Firebase خود نیاز داشته باشید:

شناسه پروژه	یک شناسه منحصر به فرد برای پروژه Firebase شما، که در درخواست ها به نقطه پایانی FCM v1 HTTP استفاده می شود. این مقدار در قسمت تنظیمات کنسول Firebase موجود است.
رمز ثبت نام	یک رشته رمز منحصر به فرد که هر نمونه برنامه مشتری را شناسایی می کند. رمز ثبت نام برای پیام‌رسانی یک دستگاه و گروه دستگاه لازم است. توجه داشته باشید که نشانه های ثبت نام باید مخفی نگه داشته شوند.
شناسه فرستنده	یک مقدار عددی منحصربه‌فرد که هنگام ایجاد پروژه Firebase خود ایجاد می‌شود و در برگه Cloud Messaging در صفحه تنظیمات کنسول Firebase موجود است. شناسه فرستنده برای شناسایی هر فرستنده ای که می تواند به برنامه مشتری پیام ارسال کند، استفاده می شود.
نشانه دسترسی	یک توکن کوتاه مدت OAuth 2.0 که درخواست ها را به API HTTP v1 مجاز می کند. این نشانه با یک حساب خدماتی مرتبط است که به پروژه Firebase شما تعلق دارد. برای ایجاد و چرخاندن نشانه‌های دسترسی، مراحل توضیح داده شده در مجوز ارسال درخواست‌ها را دنبال کنید.