Firebase Cloud Messaging چیست و برای چه کاری ساخته شده است؟

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

بروزرسانی: زمان مطالعه حدود ۱۱ دقیقه نوشته‌ی تیم فنی فینگت

Firebase Cloud Messaging چیست؟ تعریف ساده

Firebase Cloud Messaging چیست؟ ساده‌ترین جواب این است: یک پستچی مرکزی. اپ شما و سرور شما هر دو با یک سرویس واسط حرف می‌زنند و آن سرویس مسیریابی را انجام می‌دهد. سرور فقط می‌گوید «این پیام را به آن دستگاه برسان» و FCM تصمیم می‌گیرد از کدام راه و کی برساند. همین واسطه است که باعث می‌شود اپ برای گرفتن اعلان مجبور نباشد دائم بیدار باشد.

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

FCM خودش «پنل ارسال اعلان به مشتری» نیست؛ ابزار فنی رساندن پیام است. کدی که اپ را به آن وصل می‌کند و منطق «چه کسی چه پیامی بگیرد» را باید خودتان یا یک سرویس دیگر پیاده کند.

معماری FCM؛ پیام از سرور شما تا گوشی چه مسیری می‌رود؟

پنج مرحله‌ی زیر چارچوب کار هر پروژه‌ای است که از FCM استفاده می‌کند.

  1. ۱

    ثبت پروژه

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

  2. ۲

    گرفتن توکن FCM

    اپ هنگام اجرا از کتابخانه‌ی FCM یک توکن ثبت‌نام می‌گیرد؛ شناسه‌ای که یک نصب مشخص از اپ را روی یک دستگاه مشخص نشان می‌دهد.

  3. ۳

    ذخیره‌ی توکن روی سرور

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

  4. ۴

    ارسال پیام

    سرور با اعتبارنامه‌ی حساب سرویس، درخواستی به API فایربیس می‌دهد که حاوی توکن، عنوان و متن یا داده‌ی دلخواه است.

  5. ۵

    تحویل و نمایش

    FCM پیام را به دستگاه می‌رساند؛ سیستم‌عامل یا کد اپ آن را نشان می‌دهد یا پردازش می‌کند.

در کل این مسیر، سرور شما هرگز مستقیم به گوشی وصل نمی‌شود. اگر شبکه‌ی کاربر دسترسی به سرویس‌های گوگل نداشته باشد، حتی بی‌نقص‌ترین سرور هم پیام را نمی‌رساند.

دو نوع پیام در FCM؛ پیام اعلان و پیام داده

ویژگیپیام اعلان (notification)پیام داده (data)
چه کسی نمایش می‌دهدسیستم‌عامل، وقتی اپ در پس‌زمینه استکد اپ شما
کنترل روی ظاهرکم؛ عنوان، متن، آیکونکامل؛ هر کاری که کد بتواند
اجرای کد اپفقط وقتی اپ در پیش‌زمینه استاپ برای پردازش بیدار می‌شود، با محدودیت‌های اندروید
کاربرد معمولاعلان‌های ساده‌ی خبری و تبلیغاتیهمگام‌سازی، چت، اعلان سفارشی با دکمه
خطر رایجنبود کنترل روی ظاهر و رفتاررسیدن ناقص اگر سازنده‌ی گوشی اپ را در پس‌زمینه ببندد
حجم مجازحدود چهار کیلوبایتحدود چهار کیلوبایت

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

پیام موضوعی و گروه دستگاه

علاوه بر ارسال به یک توکن، FCM امکان «موضوع» (topic) دارد: دستگاه‌ها مشترک یک موضوع می‌شوند و یک بار ارسال برای همه‌ی مشترکان می‌رود. برای اعلان‌هایی مثل «خبرهای ورزشی» مناسب است، اما برای پیام شخصی (مثل «سفارش شما ارسال شد») باید به توکن یا شناسه‌ی همان کاربر بفرستید.

کد نمونه‌ی ارسال پیام با FCM

دو بخش لازم است: سرور که پیام را می‌فرستد و اپ که توکن را می‌گیرد و پیام را دریافت می‌کند. نمونه‌ی سرور با Node.js و بسته‌ی رسمی firebase-admin نوشته شده است. API قدیمی «کلید سرور» توسط گوگل بسته شده و روش فعلی بر پایه‌ی HTTP v1 و حساب سرویس است؛ بسته‌ی admin همین را برای شما انجام می‌دهد.

فایل JSON حساب سرویس را از کنسول فایربیس بگیرید و مسیرش را در متغیر محیطی GOOGLE_APPLICATION_CREDENTIALS بگذارید. این فایل یک راز است و نباید در مخزن کد یا داخل اپ قرار بگیرد.

send.mjs؛ ارسال به یک توکن با Node.js
// npm install firebase-admin
import { initializeApp, applicationDefault } from 'firebase-admin/app'
import { getMessaging } from 'firebase-admin/messaging'

initializeApp({ credential: applicationDefault() })

export async function notifyOrder(token, orderId) {
  try {
    return await getMessaging().send({
      token,
      notification: { title: 'سفارش شما ارسال شد', body: 'سفارش ' + orderId + ' به پست تحویل شد.' },
      data: { screen: 'order', orderId: String(orderId) }, // مقدارهای data همیشه رشته‌اند
      android: { priority: 'high', ttl: 60 * 60 * 1000 }, // اگر یک ساعت نرسید، منقضی شود
    })
  } catch (err) {
    // توکن باطل‌شده را از پایگاه‌داده پاک کنید تا بارها به آن پیام داده نشود
    if (err.code === 'messaging/registration-token-not-registered') {
      return 'invalid-token'
    }
    throw err
  }
}
AppMessagingService.kt؛ گرفتن توکن و پیام در اپ اندروید
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage

class AppMessagingService : FirebaseMessagingService() {

    // توکن اولین بار یا هر وقت عوض شود صدا زده می‌شود
    override fun onNewToken(token: String) {
        uploadTokenToServer(token) // پیاده‌سازی با شماست: ارسال به API خودتان
    }

    override fun onMessageReceived(message: RemoteMessage) {
        val screen = message.data["screen"]
        val orderId = message.data["orderId"]
        // یا اعلان خودتان را بسازید یا داده را برای صفحه‌ی مقصد نگه دارید
    }
}

سرویس بالا باید در فایل مانیفست با intent-filter مربوط به MESSAGING_EVENT ثبت شود. در اندروید ۱۳ و بالاتر، نمایش هر اعلانی نیازمند مجوز POST_NOTIFICATIONS است که اپ باید در زمان مناسب از کاربر بگیرد.

توکن FCM؛ کوچک‌ترین جزء و بیشترین دردسر

توکن FCM یک شناسه‌ی ثابت و همیشگی نیست. بیشتر «چرا اعلان نرسید؟» های واقعی به همین نکته برمی‌گردد.

توکن عوض می‌شود

پاک و نصب دوباره‌ی اپ، پاک شدن داده‌ی اپ یا بازگردانی گوشی توکن جدیدی می‌سازد. باید onNewToken را جدی بگیرید و توکن را فوری به سرور بفرستید.

توکن قدیمی روی سرور می‌ماند

اگر پاسخ خطای «توکن ثبت‌نشده» را نادیده بگیرید، فهرستتان پر از توکن مرده می‌شود و آمار ارسال بی‌معنی.

یک کاربر، چند دستگاه

کاربری که گوشی و تبلت دارد دو توکن دارد. توکن را به دستگاه وصل کنید نه فقط به کاربر.

توکن همان شناسه‌ی کاربر نیست

هویت کاربر را با شناسه‌ی خودتان مدیریت کنید و توکن را فقط آدرس تحویل بدانید.

توکن را فاش نکنید

توکن به‌تنهایی برای فرستادن پیام کافی نیست، اما در دست دیگران برای جاسوسی یا رفتار مزاحم به کار می‌آید. در لاگ‌ها ماسکش کنید.

FCM رایگان است، اما «رایگان» یعنی چه؟

گوگل خود FCM را بدون هزینه‌ی هر پیام عرضه می‌کند. این به معنی صفر هزینه برای پروژه‌ی شما نیست: سرور، نگهداری توکن‌ها، منطق ارسال، آمار و پشتیبانی همه با خودتان است. اگر از ابزار «ارسال اعلان» کنسول فایربیس استفاده کنید، برای کارهای ساده مناسب است، اما سناریوهای شخصی‌شده مثل «وضعیت سفارش ۴۵۲ تغییر کرد» به کدنویسی سمت سرور نیاز دارند.

هزینه‌ی دیگری هم هست که کمتر دیده می‌شود: ریسک وابستگی. FCM به سرویس‌های گوگل روی دستگاه (Google Play Services) تکیه دارد و پروژه‌ای که فقط از آن استفاده کند، به ثبات آن سرویس و شبکه‌ی بین گوشی و گوگل وابسته می‌ماند.

محدودیت‌های فنی که باید بدانید

  • حجم هر پیام حدود چهار کیلوبایت است؛ پس اعلان جای فرستادن متن طولانی نیست.
  • پیام‌هایی که دستگاه آفلاین نگرفته، بسته به مقدار ttl فقط مدتی در صف می‌مانند و بعد حذف می‌شوند.
  • سقف تعداد پیام در ثانیه و سهمیه‌های ارسال دارد و مقدارش در مستندات گوگل به‌روز می‌شود؛ اعداد را از همان‌جا بخوانید.
  • اولویت بالا را فقط برای پیام‌های واقعاً فوری بگذارید؛ سوءاستفاده از آن باعث کم‌اعتبار شدن اپ در نظر اندروید می‌شود.

FCM در ایران؛ نکته‌هایی که پیش از انتخاب باید بسنجید

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

جاهایی که FCM مناسب‌تر است

  • اپی که کاربرانش زیاد خارج از ایران‌اند یا روی گوشی‌هایی با سرویس‌های گوگل کار می‌کند.
  • پروژه‌ای که یک بخش از اعلان‌هایش اگر دیر رسید، اتفاق بدی نمی‌افتد.
  • تیمی که می‌خواهد با کمترین کار، پیام را روی اندروید، آیفون و وب با یک API بفرستد.

جاهایی که باید راه پشتیبان داشت

  • پیام‌هایی که نرسیدنشان خسارت دارد، مثل کد ورود یا هشدار پرداخت.
  • کاربرانی که گوشی بدون سرویس‌های گوگل دارند.
  • سناریویی که دسترسی شبکه‌ی کاربر به سرویس‌های گوگل را نمی‌توانید مطمئن باشید و باید خودتان نسخه‌ی دوم مسیر ارسال بسازید.

برای مقایسه‌ی همین مسیر با فرستادن پیامک، پیامک یا پوش نوتیفیکیشن را ببینید؛ و برای دیدن این‌که چرا گاهی پوش نمی‌رسد، مشکل ارسال پوش نوتیفیکیشن را بخوانید.

Firebase Cloud Messaging چیست در مقایسه با گزینه‌های دیگر؟

وقتی می‌پرسند Firebase Cloud Messaging چیست و چرا همه از آن حرف می‌زنند، دلیلش بیشتر عمومیت آن است: مستندات فراوان، کتابخانه‌ی آماده برای اندروید و وب و رایگان بودن ارسال. اما بقیه‌ی راه‌ها هم وجود دارند و هر کدام جای خودشان را دارند.

  • سرویس پوش اپل (APNs): تنها مسیر رسمی برای آیفون؛ FCM هم روی آیفون در واقع پیام را از همین مسیر می‌رساند.
  • وب پوش با کلیدهای VAPID: استاندارد مرورگرها که بدون پروژه‌ی فایربیس هم کار می‌کند و در صفحه‌ی وب پوش توضیح داده شده است.
  • سرویس‌های ایرانی پوش یا سرویس‌های خارجی دیگر که لایه‌ای روی همین سرویس‌ها می‌گذارند و مدیریت مخاطب و پنل می‌دهند؛ مقایسه‌شان در بهترین سرویس پوش نوتیفیکیشن آمده است.
  • اتصال دائمی خود اپ به سرور شما، مثل وب‌سوکت یا MQTT؛ برای اپ‌هایی که پیام‌شان باید لحظه‌ای برسد و دسترسی به گوگل را نمی‌خواهند، ولی هزینه‌ی باتری و پیچیدگی نگهداری دارد.

انتخاب درست از پرسش «کاربران من چه گوشی‌ای دارند و پیام‌ها چقدر حیاتی‌اند؟» شروع می‌شود، نه از محبوبیت یک ابزار. پیام تبلیغاتی ساده را می‌شود با FCM فرستاد و گاهی نرسیدنش را تحمل کرد؛ برای کد ورود اما بهتر است راه‌هایی مثل جایگزین پیامک ورود را هم در نظر بگیرید.

یک نکته‌ی تکمیلی برای کسی که تازه آغاز کرده: پیش از نوشتن هر کدی، یک پیام آزمایشی از کنسول فایربیس به گوشی خودتان بفرستید. اگر آن پیام رسید، مسیر پیکربندی اپ درست است و هر مشکل بعدی احتمالاً در کد سرور یا توکن‌هاست؛ اگر نرسید، اول شبکه، سرویس‌های گوگل و تنظیمات باتری گوشی را بررسی کنید.

آیا برای اعلان به کاربران سایت خودم باید حتماً سراغ FCM بروم؟

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

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

چک‌لیست راه‌اندازی FCM در یک پروژه

پیش از انتشار، این موارد را برای هر پروژه‌ی دارای FCM مرور کنید:

  • پروژه و اپ ثبت شده‌اند شناسه‌ی بسته‌ی اپ دقیقاً با چیزی که در کنسول وارد کرده‌اید یکی است.
  • توکن به سرور می‌رسد هم بار اول و هم هر بار که onNewToken صدا زده می‌شود.
  • توکن‌های مرده پاک می‌شوند پاسخ خطای توکن نامعتبر یک رویداد عادی است، نه استثنا.
  • مجوز اعلان در اندروید ۱۳ گرفته می‌شود در لحظه‌ی مناسب و با توضیح، نه همان ثانیه‌ی اول اجرا.
  • کلید حساب سرویس فقط روی سرور است در اپ و مخزن عمومی نیست.
  • پیام‌های حساس روی صفحه‌ی قفل نمایش داده نمی‌شوند متن اعلان را بدون اطلاعات محرمانه بنویسید.
  • آزمون روی چند گوشی دست‌کم یک گوشی با محدودیت باتری شدید سازنده را هم امتحان کنید.

پرسش‌های متداول درباره Firebase Cloud Messaging چیست

Firebase Cloud Messaging چیست و فرقش با پوش نوتیفیکیشن چیست؟

پوش نوتیفیکیشن مفهوم کلی «رساندن پیام از سرور به دستگاه» است و FCM یکی از سرویس‌های ساخت آن، متعلق به گوگل. نمونه‌ی دیگر سرویس پوش اپل برای آیفون است.

FCM رایگان است؟

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

برای استفاده از FCM حتماً باید اپ اندروید داشته باشم؟

نه. FCM برای وب و آیفون هم کار می‌کند، اما در همه‌ی حالت‌ها به کدی روی سمت کاربر، یعنی اپ یا سرویس ورکر مرورگر، نیاز دارید.

چرا پیام FCM به بعضی گوشی‌ها نمی‌رسد؟

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

فرق پیام داده و پیام اعلان در FCM چیست؟

پیام اعلان را سیستم‌عامل با ظاهر ثابت نشان می‌دهد؛ پیام داده را کد اپ شما دریافت می‌کند و هر طور بخواهید پردازش می‌کند. بیشتر اپ‌ها هر دو را در یک پیام می‌فرستند.

برای فروشگاه ووکامرسی بدون اپ چه راهی دارم؟

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