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

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

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

‫iOS+‎

روش swizzling

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

Android

خدمات Google Play

FCM مشتریان به دستگاه‌هایی نیاز دارند که Android 4.4 یا بالاتر داشته باشند و همچنین «خدمات Google Play» در آن‌ها نصب شده باشد، یا شبیه‌سازی که Android 4.4 با «میاناهای برنامه‌سازی کاربردی Google» را اجرا کند. توجه داشته باشید که محدود به استقرار برنامه‌های 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
   

دسترسی به کد ثبت

برای ارسال پیام به دستگاهی خاص، باید رمز ثبت دستگاه را بدانید. برای بازیابی کردن کد ثبت برای نمونه برنامه، 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

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

FirebaseMessagingAutoInitEnabled = NO

Android

در Android، با افزودن این مقادیر فراداده به 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 مقداردهی اولیه خودکار در زمان اجرا

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

await FirebaseMessaging.instance.setAutoInitEnabled(true);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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
• ارسال پیام به موضوعات