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

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

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

iOS+‎

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

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

Android

خدمات Google Play

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

برنامه‌هایی که به «کیت توسعه نرم‌افزار خدمات 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)، ابتدا باید شناسه‌های نصب را در پیکربندی برنامه‌تان برای پلاتفرم‌های 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 همچنان FID ثبت‌شده را منتشر می‌کند).
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: AStream که وقتی برنامه از حالت پس‌زمینه باز می‌شود 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
• ارسال پیام به موضوعات