شروع به کار با «پیام‌رسانی ابریِ Firebase» در برنامه‌های Flutter

این راهنما نحوه شروع به کار با Firebase Cloud Messaging را در برنامه‌های مشتری Flutter شرح می‌دهد تا بتوانید پیام‌ها را به‌طور قابل‌اعتماد ارسال کنید.

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

iOS+‎

روش تغییر پیاده‌سازی

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

Android

خدمات Google Play

کارخواه‌های FCM به دستگاه‌های دارای Android نسخه ۷.۰ یا بالاتر که خدمات Google Play نیز در آن‌ها نصب شده باشد، یا شبیه‌ساز دارای Android نسخه ۷.۰ با Google APIs نیاز دارند. توجه داشته باشید که شما محدود به استقرار برنامه‌های Android خود ازطریق «فروشگاه Google Play» نیستید.

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

اگر دستگاه نسخه سازگاری از «خدمات Google Play» نداشته باشد، برنامه شما می‌تواند GoogleApiAvailability.makeGooglePlayServicesAvailable() را فراخوانی کند تا به کاربران اجازه دهد «خدمات Google Play» را از «فروشگاه Play» بارگیری کنند.

وب

پیکربندی کردن «اطلاعات کاربری وب» با FCM

میانای وب FCM از اطلاعات اعتباری وب به‌نام «شناسایی داوطلبانه سرور برنامه» یا کلیدهای VAPID برای مجاز کردن درخواست‌های ارسال به سرویس‌های وب‌فشار پشتیبانی‌شده استفاده می‌کند. برای مشترک کردن برنامه‌تان در اعلان‌های لحظه‌ای، باید یک جفت کلید را با پروژه Firebase خود مرتبط کنید. می‌توانید جفت کلید جدیدی تولید کنید یا جفت کلید موجودتان را ازطریق کنسول Firebase وارد کنید.

نصب افزایه FCM

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

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

   flutter pub add firebase_messaging
   

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

   flutter run
   

درخواست اجازه اعلان

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

// 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...
}

دسترسی به شناسه نصب Firebase

فعال کردن ثبت‌نام بااستفاده از «شناسه نصب Firebase»

برای فعال کردن ثبت نمونه برنامه‌تان با FCM بااستفاده از شناسه نصب Firebase (FID)، ابتدا باید شناسه‌های نصب Firebase را در پیکربندی برنامه‌تان برای پلاتفرم‌های Android و Apple فعال کنید (هیچ پیکربندی موافقت ثابتی در وب لازم نیست):

<meta-data android:name="firebase_messaging_installation_id_enabled"
           android:value="true" />

<key>FirebaseMessagingInstallationIdEnabled</key>
<true/>

مشترک شدن در جاری‌سازی onRegistered

برای ارسال پیام به نمونه برنامه در دستگاهی خاص، به شناسه نصب Firebase (FID) آن نمونه برنامه پس‌از ثبت شدن در FCM نیاز دارید. FID به‌صورت ناهمگام ازطریق جاری‌سازی onRegistered ارائه می‌شود.

در پلاتفرم‌های Android و Apple، وقتی مقداردهی اولیه خودکار فعال باشد (پیش‌فرض)، FCM به‌طور خودکار نمونه برنامه را در زمان راه‌اندازی ثبت می‌کند. بااین‌حال، فراخوانی صریح برای register() لازم است:

• در وب. درصورت تمایل می‌توانید vapidKey و serviceWorkerScriptPath را ارسال کنید.
• در پلاتفرم‌های Android و Apple اگر مقداردهی اولیه خودکار غیرفعال باشد یا پس‌از فراخوانی unregister(). همچنین می‌توانید هرزمان خواستید با register() تماس بگیرید تا onRegistered را با FID ثبت‌شده راه‌اندازی کنید.

همیشه قبل‌از فراخوانی register()، در onRegistered مشترک شوید تا شنونده شما هنگام انتشار رویداد ثبت فعال باشد:

final messaging = FirebaseMessaging.instance;

messaging.onRegistered
    .listen((String installationId) {
      // TODO: Send the Firebase Installation ID (FID) to your application server.
    })
    .onError((err) {
      // Error getting Firebase Installation ID.
    });

// Required on Web, and on Android/Apple if auto-initialization is disabled.
await messaging.register(
  // Optional on Web (ignored on Android and Apple platforms)
  vapidKey: "BKagOny0KF_2pCJQ3m....moL0ewzQ8rZu",
);

جاری‌سازی onRegistered در سناریوهای زیر FID را منتشر می‌کند:

1. به‌طور خودکار در راه‌اندازی اولیه برنامه و همگام‌سازی روال در پلاتفرم‌های Android و Apple وقتی مقداردهی اولیه خودکار فعال باشد.
2. هر بار که تماس دستی register() تمام می‌شود (حتی اگر نمونه برنامه ازقبل ثبت شده باشد، onRegistered همچنان شناسه نصب Firebase ازقبل ثبت‌شده را منتشر می‌کند).
3. هرزمان که تغییری در «شناسه نصب Firebase» شناسایی شود و برنامه دوباره در FCM ثبت شود، یا در وب وقتی که رویداد pushsubscriptionchange اجرا شود.

پس‌از دریافت «شناسه نصب Firebase» (FID)، آن را به سرور برنامه‌تان ارسال کنید و بااستفاده از روش دلخواهتان آن را ذخیره کنید.

دسترسی به کد ثبت‌نام (منسوخ‌شده)

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

در پلاتفرم‌های وب، کلید عمومی 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 بارگذاری می‌کند. اگر ترجیح می‌دهید از ثبت خودکار جلوگیری کنید، مقداردهی اولیه خودکار را در زمان ساخت غیرفعال کنید.

وقتی مقداردهی اولیه خودکار غیرفعال است، می‌توانید نمونه برنامه را به‌طور صریح در زمان اجرا با فراخوانی register() ثبت کنید (حتماً ابتدا در onRegistered مشترک شوید تا شناسه نصب Firebase را دریافت کنید):

await FirebaseMessaging.instance.register();

iOS

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

FirebaseMessagingAutoInitEnabled = NO

Android

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

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

بازفعال‌سازی مقداردهی اولیه خودکار FCM در زمان اجرا

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

await FirebaseMessaging.instance.setAutoInitEnabled(true);

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

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

1. برنامه را در دستگاه هدف نصب و اجرا کنید. در دستگاه‌های Apple، باید درخواست اجازه برای دریافت اعلان‌های راه دور را بپذیرید.

2. مطمئن شوید برنامه در پس‌زمینه دستگاه باشد.

3. در کنسول Firebase، به DevOps و تعامل > پیام‌رسانی بروید.

4. پویشی ایجاد کنید.

   • اگر این اولین پیام شما است:

     1. ایجاد اولین پویش را انتخاب کنید.

     2. پیام‌های اعلان Firebase و سپس ایجاد را انتخاب کنید.

   • اگر قبلاً پویش ایجاد کرده‌اید:

     1. در برگه پویش‌ها، پویش جدید را انتخاب کنید.

     2. روی اعلان‌ها کلیک کنید.

5. نوشتار پیام را وارد کنید.

6. ارسال پیام آزمایشی را از قاب سمت راست انتخاب کنید.

7. در فیلد دارای برچسب افزودن شناسه نصب Firebase یا FCM کد ثبت، شناسه نصب Firebase یا کد ثبت خود را وارد کنید.

8. آزمایش را انتخاب کنید.

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

برای دریافت اطلاعات آماری درباره تحویل پیام به برنامه‌تان، به داشبورد DevOps و تعامل > پیام‌رسانی > گزارش‌ها در کنسول Firebase بروید. این داشبورد تعداد پیام‌های ارسال‌شده و بازشده در دستگاه‌های Apple و Android را به‌همراه داده‌های مربوط به «ظهورها» (اعلان‌های دیده‌شده توسط کاربران) برای برنامه‌های Android ثبت می‌کند.

تعامل با دستگاه

وقتی کاربران روی اعلانی تک‌ضرب می‌زنند، رفتار پیش‌فرض در Android و 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
• ارسال پیام به موضوعات