این راهنمای سریع نحوه راه‌اندازی Firebase Cloud Messaging را در برنامه‌های موبایل و کلاینت وب شما شرح می‌دهد تا بتوانید پیام‌ها را به طور قابل اعتمادی ارسال کنید. برای محیط‌های سرور، به بخش Your server environment and FCM مراجعه کنید.

یک برنامه کلاینت Firebase Cloud Messaging روی Flutter راه‌اندازی کنید

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

آی‌او‌اس+

روش سوویزلینگ

برای استفاده از افزونه FCM Flutter در دستگاه‌های اپل، به method swizzling نیاز است. بدون آن، ویژگی‌های کلیدی Firebase مانند مدیریت توکن‌های FCM به درستی کار نخواهند کرد.

اندروید

سرویس‌های گوگل پلی

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

برنامه‌هایی که به SDK سرویس‌های Play متکی هستند، باید همیشه قبل از دسترسی به ویژگی‌های سرویس‌های Google Play، دستگاه را از نظر سازگاری با APK سرویس‌های Google Play بررسی کنند. توصیه می‌شود این کار را در دو مکان انجام دهید: در متد onCreate() در فعالیت اصلی و در متد onResume() آن. بررسی onCreate() اطمینان حاصل می‌کند که برنامه بدون بررسی موفقیت‌آمیز قابل استفاده نیست. بررسی onResume() اطمینان حاصل می‌کند که اگر کاربر از طریق روش‌های دیگری، مانند دکمه برگشت، به برنامه در حال اجرا بازگردد، بررسی همچنان انجام می‌شود.

اگر دستگاه نسخه سازگار با سرویس‌های گوگل پلی را نداشته باشد، برنامه شما می‌تواند تابع GoogleApiAvailability.makeGooglePlayServicesAvailable() را فراخوانی کند تا به کاربران اجازه دهد سرویس‌های گوگل پلی را از فروشگاه پلی دانلود کنند.

وب

پیکربندی اعتبارنامه‌های وب با FCM

رابط وب FCM از اعتبارنامه‌های وب به نام کلیدهای Voluntary Application Server Identification یا "VAPID" برای تأیید ارسال درخواست‌ها به سرویس‌های پشتیبانی‌شده‌ی ارسال اعلان‌های وب استفاده می‌کند. برای عضویت در برنامه‌ی خود برای ارسال اعلان‌ها، باید یک جفت کلید را با پروژه‌ی Firebase خود مرتبط کنید. می‌توانید یک جفت کلید جدید ایجاد کنید یا جفت کلید موجود خود را از طریق کنسول Firebase وارد کنید.

افزونه FCM را نصب کنید

1. اگر قبلاً افزونه‌های Firebase را برای Flutter نصب و راه‌اندازی نکرده‌اید، این کار را انجام دهید.

2. از ریشه پروژه Flutter خود، دستور زیر را برای نصب افزونه اجرا کنید:

   flutter pub add firebase_messaging
   

3. پس از اتمام، برنامه Flutter خود را بازسازی کنید:

   flutter run
   

دسترسی به توکن ثبت نام

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

// You may set the permission requests to "provisional" which allows the user to choose what type
// of notifications they would like to receive once the user receives a notification.
final notificationSettings = await FirebaseMessaging.instance.requestPermission(provisional: true);

// For apple platforms, make sure the APNS token is available before making any FCM plugin API calls
final apnsToken = await FirebaseMessaging.instance.getAPNSToken();
if (apnsToken != null) {
 // APNS token is available, make FCM plugin API requests...
}

در پلتفرم‌های وب، کلید عمومی VAPID خود را به getToken() ارسال کنید:

final fcmToken = await FirebaseMessaging.instance.getToken(vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu");

برای اینکه هر زمان توکن به‌روزرسانی شد، مطلع شوید، در استریم onTokenRefresh مشترک شوید:

FirebaseMessaging.instance.onTokenRefresh
    .listen((fcmToken) {
      // TODO: If necessary send token to application server.

      // Note: This callback is fired at each app startup and whenever a new
      // token is generated.
    })
    .onError((err) {
      // Error getting token.
    });

جلوگیری از مقداردهی اولیه خودکار

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

آی‌او‌اس

در iOS، یک مقدار فراداده به Info.plist خود اضافه کنید:

FirebaseMessagingAutoInitEnabled = NO

اندروید

در اندروید، با اضافه کردن این مقادیر فراداده به AndroidManifest.xml ، جمع‌آوری Analytics و مقداردهی اولیه خودکار FCM را غیرفعال کنید (باید هر دو را غیرفعال کنید):

<meta-data
    android:name="firebase_messaging_auto_init_enabled"
    android:value="false" />
<meta-data
    android:name="firebase_analytics_collection_enabled"
    android:value="false" />

فعال کردن مجدد شروع خودکار FCM در زمان اجرا

برای فعال کردن auto-init برای یک نمونه خاص از برنامه، setAutoInitEnabled() را فراخوانی کنید:

await FirebaseMessaging.instance.setAutoInitEnabled(true);

این مقدار پس از تنظیم، در طول راه‌اندازی مجدد برنامه حفظ می‌شود.

ارسال پیام اطلاع رسانی آزمایشی

1. برنامه را روی دستگاه هدف نصب و اجرا کنید. در دستگاه‌های اپل، باید درخواست اجازه دریافت اعلان‌های از راه دور را بپذیرید.
2. مطمئن شوید که برنامه در پس‌زمینه دستگاه فعال است.
3. در کنسول فایربیس، صفحه پیام‌رسانی (Messaging) را باز کنید.
4. اگر این اولین پیام شماست، گزینه «ایجاد اولین کمپین» را انتخاب کنید.
   1. پیام‌های اعلان فایربیس و سپس ایجاد را انتخاب کنید.
5. در غیر این صورت، در برگه کمپین‌ها ، کمپین جدید و سپس اعلان‌ها را انتخاب کنید.
6. متن پیام را وارد کنید.
7. از پنل سمت راست، گزینه ارسال پیام آزمایشی را انتخاب کنید.
8. در فیلدی با عنوان « افزودن یک توکن ثبت نام FCM ، توکن ثبت نام خود را وارد کنید.
9. آزمون را انتخاب کنید.

پس از انتخاب Test ، دستگاه کلاینت مورد نظر، با برنامه در پس‌زمینه، باید اعلان را دریافت کند.

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

مدیریت تعامل

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

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

پکیج firebase-messaging دو روش برای مدیریت این تعامل ارائه می‌دهد:

1. getInitialMessage(): اگر برنامه از حالت خاتمه یافته باز شود، این متد یک Future حاوی RemoteMessage را برمی‌گرداند. پس از مصرف، RemoteMessage حذف خواهد شد.
2. onMessageOpenedApp : Stream که هنگام باز شدن برنامه از حالت پس‌زمینه، یک RemoteMessage ارسال می‌کند.

برای اطمینان از اینکه کاربران شما تجربه‌ای روان دارند، باید هر دو سناریو را مدیریت کنید. مثال کد زیر نحوه دستیابی به این هدف را شرح می‌دهد:

class Application extends StatefulWidget {
  @override
  State createState() => _Application();
}

class _Application extends State {
  // In this example, suppose that all messages contain a data field with the key 'type'.
  Future setupInteractedMessage() async {
    // Get any messages which caused the application to open from
    // a terminated state.
    RemoteMessage? initialMessage =
        await FirebaseMessaging.instance.getInitialMessage();

    // If the message also contains a data property with a "type" of "chat",
    // navigate to a chat screen
    if (initialMessage != null) {
      _handleMessage(initialMessage);
    }

    // Also handle any interaction when the app is in the background using a
    // Stream listener
    FirebaseMessaging.onMessageOpenedApp.listen(_handleMessage);
  }

  void _handleMessage(RemoteMessage message) {
    if (message.data['type'] == 'chat') {
      Navigator.pushNamed(context, '/chat',
        arguments: ChatArguments(message),
      );
    }
  }

  @override
  void initState() {
    super.initState();

    // Run code required to handle interacted messages in an async function
    // as initState() must not be async
    setupInteractedMessage();
  }

  @override
  Widget build(BuildContext context) {
    return Text("...");
  }
}

نحوه مدیریت تعامل به تنظیمات شما بستگی دارد. مثال قبلی نشان داده شده یک مثال اساسی از استفاده از StatefulWidget است.

مراحل بعدی

پس از اتمام مراحل راه‌اندازی، در اینجا چند گزینه برای ادامه کار با FCM برای Flutter ارائه شده است:

• ارسال پیام به دستگاه‌ها
• دریافت پیام‌ها در یک برنامه Flutter
• ارسال پیام به موضوعات