دریافت پیام در برنامه‌های Flutter

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

چند پیش‌شرط وجود دارد که باید قبل‌از اینکه برنامه بتواند ازطریق FCM پیام‌های محتوا دریافت کند برآورده شوند:

• برنامه باید حداقل یک‌بار باز شده باشد (تا امکان ثبت‌نام در FCM فراهم شود).
• در iOS، اگر کاربر برنامه را از مبدل برنامه کنار بزند، باید به‌صورت دستی باز شود تا پیام‌های پس‌زمینه دوباره شروع به کار کنند.
• در Android، اگر کاربر برنامه را از تنظیمات دستگاه به‌اجبار ببندد، باید برنامه را به‌صورت دستی باز کند تا پیام‌ها شروع به کار کنند.
• در وب، باید با گواهینامه پیام آنی وب خود درخواست کد کرده باشید (بااستفاده از getToken()).

درخواست اجازه برای دریافت پیام

در iOS،‏ macOS، وب، و Android 13 (یا جدیدتر)، قبل‌از اینکه بتوانید بار داده‌های FCM را در دستگاهتان دریافت کنید، ابتدا باید از کاربر اجازه بگیرید.

بسته firebase_messaging میانای برنامه‌سازی کاربردی برای درخواست اجازه بااستفاده از روش requestPermission ارائه می‌دهد. این API تعدادی آرگومان نام‌گذاری‌شده را می‌پذیرد که نوع اجازه‌هایی را که می‌خواهید درخواست کنید تعریف می‌کنند، مثلاً اینکه آیا پیام‌رسانی حاوی پیام‌های اعلان می‌تواند باعث پخش صدا شود یا پیام‌ها را بااستفاده از Siri بخواند. به‌طور پیش‌فرض، این روش اجازه‌های پیش‌فرض منطقی را درخواست می‌کند. «میانای برنامه‌سازی کاربردی مرجع» مستندات کاملی درباره هدف هر اجازه ارائه می‌دهد.

برای شروع، روش را از برنامه‌تان فراخوانی کنید (در iOS یک مُدال داخلی نمایش داده می‌شود، در وب جریان API مرورگر راه‌اندازی می‌شود):

FirebaseMessaging messaging = FirebaseMessaging.instance;

NotificationSettings settings = await messaging.requestPermission(
  alert: true,
  announcement: false,
  badge: true,
  carPlay: false,
  criticalAlert: false,
  provisional: false,
  sound: true,
);

print('User granted permission: ${settings.authorizationStatus}');

از دارایی authorizationStatus شیء NotificationSettings برگشتی از درخواست می‌توان برای تعیین تصمیم کلی کاربر استفاده کرد:

• authorized: کاربر اجازه داد.
• ‫denied: کاربر اجازه را رد کرد.
• ‫notDetermined: کاربر هنوز انتخاب نکرده است که اجازه را اعطا کند یا نه.
• ‫provisional: کاربر اجازه موقت اعطا کرد

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

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

اداره کردن پیام

براساس وضعیت فعلی برنامه‌تان، برای مدیریت کردن باربرهای ورودی از انواع پیام مختلف به پیاده‌سازی‌های مختلفی نیاز است:

پیام‌های پیش‌زمینه‌ای

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

FirebaseMessaging.onMessage.listen((RemoteMessage message) {
  print('Got a message whilst in the foreground!');
  print('Message data: ${message.data}');

  if (message.notification != null) {
    print('Message also contained a notification: ${message.notification}');
  }
});

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

پیام‌های اعلان و پیش‌زمینه

پیام‌های اعلان که درحالی‌که برنامه در پیش‌زمینه است دریافت می‌شوند، به‌طور پیش‌فرض در Android و iOS اعلان رؤیت‌پذیر نمایش نمی‌دهند. بااین‌حال، می‌توان این رفتار را ملغی کرد:

• در Android، باید کانال اعلان «اولویت بالا» ایجاد کنید.
• در iOS، می‌توانید گزینه‌های ارائه را برای برنامه به‌روز کنید.

پیام‌های پس‌زمینه

فرایند مدیریت پیام‌های پس‌زمینه در Android،‏ Apple، و پلاتفرم‌های مبتنی بر وب متفاوت است.

پلاتفرم‌های Apple و Android

با ثبت کردن کارپرداز onBackgroundMessage، پیام‌های پس‌زمینه را مدیریت کنید. وقتی پیام‌ها دریافت می‌شوند، یک ایزوله ایجاد می‌شود (فقط Android، در iOS/macOS نیازی به ایزوله جداگانه نیست) که به شما امکان می‌دهد حتی زمانی که برنامه‌تان درحال اجرا نیست پیام‌ها را مدیریت کنید.

چند نکته را درباره مدیریت پیام پس‌زمینه‌ای به‌خاطر داشته باشید:

1. نباید تابع ناشناس باشد.
2. باید یک تابع سطح بالا باشد (مثلاً روش کلاس که نیاز به مقداردهی اولیه ندارد).
3. هنگام استفاده از Flutter نسخه ۳.۳.۰ یا بالاتر، کنترل‌کننده پیام باید با @pragma('vm:entry-point') درست بالای تابع اعلان حاشیه‌نویسی شود (درغیراین‌صورت ممکن است درحین تکاندن درخت برای حالت انتشار برداشته شود).

@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  // If you're going to use other Firebase services in the background, such as Firestore,
  // make sure you call `initializeApp` before using other Firebase services.
  await Firebase.initializeApp();

  print("Handling a background message: ${message.messageId}");
}

void main() {
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);
  runApp(MyApp());
}

ازآنجایی‌که این مدیریت‌کننده در ایزوله خود خارج از زمینه برنامه‌هایتان اجرا می‌شود، امکان به‌روزرسانی وضعیت برنامه یا اجرای هرگونه منطق تأثیرگذار بر رابط کاربری وجود ندارد. بااین‌حال، می‌توانید منطقی مثل درخواست‌های HTTP، عملیات ورودی/خروجی (برای نمونه، به‌روزرسانی فضای ذخیره‌سازی محلی)، ارتباط با افزایه‌های دیگر، و غیره را انجام دهید.

همچنین توصیه می‌شود منطق خود را در اسرع وقت تکمیل کنید. اجرای طولانی‌مدت وظایف سنگین بر عملکرد دستگاه تأثیر می‌گذارد و ممکن است باعث شود سیستم‌عامل فرایند را خاتمه دهد. اگر تکالیف بیشتر از ۳۰ ثانیه اجرا شوند، ممکن است دستگاه به‌طور خودکار فرایند را متوقف کند.

وب

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

برای شروع، فایل جدیدی در دایرکتوری web خود ایجاد کنید و آن را firebase-messaging-sw.js بنامید:

// See this file for the latest firebase-js-sdk version:
// https://github.com/firebase/flutterfire/blob/main/packages/firebase_core/firebase_core_web/lib/src/firebase_sdk_version.dart
importScripts("https://www.gstatic.com/firebasejs/10.7.0/firebase-app-compat.js");
importScripts("https://www.gstatic.com/firebasejs/10.7.0/firebase-messaging-compat.js");

firebase.initializeApp({
  apiKey: "...",
  authDomain: "...",
  databaseURL: "...",
  projectId: "...",
  storageBucket: "...",
  messagingSenderId: "...",
  appId: "...",
});

const messaging = firebase.messaging();

// Optional:
messaging.onBackgroundMessage((message) => {
  console.log("onBackgroundMessage", message);
});

فایل باید هر دو کیت توسعه نرم‌افزار برنامه و پیام‌رسانی را وارد کند، Firebase را مقداردهی اولیه کند، و متغیر messaging را آشکار کند.

سپس، کارگر باید ثبت شود. در فایل index.html، کارگر را با تغییر برچسب <script> که Flutter را راه‌اندازی می‌کند ثبت کنید:

<script src="flutter_bootstrap.js" async>
  if ('serviceWorker' in navigator) {
    window.addEventListener('load', function () {
      navigator.serviceWorker.register('firebase-messaging-sw.js', {
        scope: '/firebase-cloud-messaging-push-scope',
      });
    });
  }
</script>

اگر هنوز از سیستم قدیمی الگو استفاده می‌کنید، می‌توانید کارگر را با اصلاح برچسب <script> که Flutter را راه‌اندازی می‌کند به این صورت ثبت کنید:

<html>
<body>
  <script>
      var serviceWorkerVersion = null;
      var scriptLoaded = false;
      function loadMainDartJs() {
        if (scriptLoaded) {
          return;
        }
        scriptLoaded = true;
        var scriptTag = document.createElement('script');
        scriptTag.src = 'main.dart.js';
        scriptTag.type = 'application/javascript';
        document.body.append(scriptTag);
      }

      if ('serviceWorker' in navigator) {
        // Service workers are supported. Use them.
        window.addEventListener('load', function () {
          // Register Firebase Messaging service worker.
          navigator.serviceWorker.register('firebase-messaging-sw.js', {
            scope: '/firebase-cloud-messaging-push-scope',
          });

          // Wait for registration to finish before dropping the <script> tag.
          // Otherwise, the browser will load the script multiple times,
          // potentially different versions.
          var serviceWorkerUrl =
            'flutter_service_worker.js?v=' + serviceWorkerVersion;

          navigator.serviceWorker.register(serviceWorkerUrl).then((reg) => {
            function waitForActivation(serviceWorker) {
              serviceWorker.addEventListener('statechange', () => {
                if (serviceWorker.state == 'activated') {
                  console.log('Installed new service worker.');
                  loadMainDartJs();
                }
              });
            }
            if (!reg.active && (reg.installing || reg.waiting)) {
              // No active web worker and we have installed or are installing
              // one for the first time. Simply wait for it to activate.
              waitForActivation(reg.installing ?? reg.waiting);
            } else if (!reg.active.scriptURL.endsWith(serviceWorkerVersion)) {
              // When the app updates the serviceWorkerVersion changes, so we
              // need to ask the service worker to update.
              console.log('New service worker available.');
              reg.update();
              waitForActivation(reg.installing);
            } else {
              // Existing service worker is still good.
              console.log('Loading app from service worker.');
              loadMainDartJs();
            }
          });

          // If service worker doesn't succeed in a reasonable amount of time,
          // fallback to plaint <script> tag.
          setTimeout(() => {
            if (!scriptLoaded) {
              console.warn(
                'Failed to load app from service worker. Falling back to plain <script> tag.'
              );
              loadMainDartJs();
            }
          }, 4000);
        });
      } else {
        // Service workers not supported. Just drop the <script> tag.
        loadMainDartJs();
      }
  </script>
</body>

سپس برنامه Flutter خود را بازراه‌اندازی کنید. کارگر ثبت خواهد شد و هرگونه پیام پس‌زمینه‌ای بااستفاده از این فایل مدیریت خواهد شد.

درحال مدیریت تعامل

ازآنجایی‌که اعلان‌ها نشانه‌های دیداری هستند، کاربران معمولاً با آن‌ها تعامل می‌کنند (با فشار دادن). عملکرد پیش‌فرض در Android و iOS باز کردن برنامه است. اگر برنامه بسته شده باشد، شروع می‌شود؛ اگر در پس‌زمینه باشد، به پیش‌زمینه آورده می‌شود.

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

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

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

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

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

class _Application extends State<Application> {
  // It is assumed that all messages contain a data field with the key 'type'
  Future<void> 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 نشان می‌دهد.

بومی‌سازی پیام‌ها

می‌توانید رشته‌های بومی‌سازی‌شده را به دو روش مختلف ارسال کنید:

• زبان ترجیحی هریک از کاربران را در سرورتان ذخیره کنید و اعلان‌های سفارشی‌شده برای هر زبان ارسال کنید
• رشته‌های بومی‌سازی‌شده را در برنامه‌تان جاسازی کنید و از تنظیمات منطقه زبانی داخلی سیستم‌عامل استفاده کنید

نحوه استفاده از روش دوم:

Android

1. پیام‌های زبان پیش‌فرض را در resources/values/strings.xml مشخص کنید:

   <string name="notification_title">Hello world</string>
   <string name="notification_message">This is a message</string>
   

2. پیام‌های ترجمه‌شده را در پوشه values-language مشخص کنید. برای مثال، پیام‌های فرانسوی را در resources/values-fr/strings.xml مشخص کنید:

   <string name="notification_title">Bonjour le monde</string>
   <string name="notification_message">C'est un message</string>
   

3. در بار سرور، به‌جای استفاده از کلیدهای title، message، و body، از title_loc_key و body_loc_key برای پیام بومی‌سازی‌شده‌تان استفاده کنید، و آن‌ها را روی مشخصه name پیامی که می‌خواهید نمایش دهید تنظیم کنید.

   بار پیام به این شکل خواهد بود:

   {
     "android": {
        "notification": {
          "title_loc_key": "notification_title",
          "body_loc_key": "notification_message"
        }
     }
   }
   

iOS

1. پیام‌های زبان پیش‌فرض را در Base.lproj/Localizable.strings مشخص کنید:

   "NOTIFICATION_TITLE" = "Hello World";
   "NOTIFICATION_MESSAGE" = "This is a message";
   

2. پیام‌های ترجمه‌شده را در پوشه language.lproj مشخص کنید. برای مثال، پیام‌های فرانسوی را در fr.lproj/Localizable.strings مشخص کنید:

   "NOTIFICATION_TITLE" = "Bonjour le monde";
   "NOTIFICATION_MESSAGE" = "C'est un message";
   

   بار پیام به این شکل خواهد بود:

   {
     "apns": {
        "payload": {
          "alert": {
            "title-loc-key": "NOTIFICATION_TITLE",
            "loc-key": "NOTIFICATION_MESSAGE"
          }
        }
     }
   }
   

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

می‌توانید داده‌های پیامتان را برای تجزیه‌وتحلیل بیشتر به BigQuery صادر کنید. ‫BigQuery به شما امکان می‌دهد داده‌ها را بااستفاده از BigQuery SQL تجزیه‌وتحلیل کنید، آن را به ارائه‌دهنده فضای ابری دیگری صادر کنید، یا از داده‌ها برای مدل‌های سفارشی ML خود استفاده کنید. صادر کردن به BigQuery شامل همه داده‌های دردسترس برای پیام‌ها می‌شود، صرف‌نظر از نوع پیام یا اینکه پیام بااستفاده از API یا «سازنده اعلان‌ها» ارسال شده باشد.

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

Android

می‌توانید از کد زیر استفاده کنید:

await FirebaseMessaging.instance.setDeliveryMetricsExportToBigQuery(true);

iOS

برای iOS، باید AppDelegate.m را با محتوای زیر تغییر دهید.

#import "AppDelegate.h"
#import "GeneratedPluginRegistrant.h"
#import <Firebase/Firebase.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [GeneratedPluginRegistrant registerWithRegistry:self];
  // Override point for customization after application launch.
  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
          fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  [[FIRMessaging extensionHelper] exportDeliveryMetricsToBigQueryWithMessageInfo:userInfo];
}

@end

وب

برای «وب»، باید کارگزار سرویس خود را تغییر دهید تا بتوانید از نسخه ۹ کیت توسعه نرم‌افزار استفاده کنید. نسخه v9 باید دسته‌بندی شود، بنابراین برای اینکه عامل خدماتی کار کند باید از دسته‌بند مانند esbuild استفاده کنید. برای دیدن نحوه انجام این کار، برنامه نمونه را ببینید.

پس‌از انتقال به کیت توسعه نرم‌افزار v9، می‌توانید از کد زیر استفاده کنید:

import {
  experimentalSetDeliveryMetricsExportedToBigQueryEnabled,
  getMessaging,
} from 'firebase/messaging/sw';
...

const messaging = getMessaging(app);
experimentalSetDeliveryMetricsExportedToBigQueryEnabled(messaging, true);

فراموش نکنید که yarn build را اجرا کنید تا نسخه جدید کارگزار خدماتتان را به پوشه web صادر کنید.

نمایش تصاویر در اعلان‌ها در iOS

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

اگر از اصالت‌سنجی تلفن Firebase استفاده می‌کنید، باید Firebase Auth pod را به Podfile خود اضافه کنید.

مرحله ۱ - افزودن افزونه سرویس اعلان

1. در Xcode، روی File (فایل) > New (جدید) > Target… (هدف…) کلیک کنید.
2. یک مُدال فهرستی از هدف‌های ممکن را ارائه می‌دهد؛ برای انتخاب افزونه سرویس اعلان، به پایین پیمایش کنید یا از فیلتر استفاده کنید. روی بعدی کلیک کنید.
3. نام محصولی اضافه کنید (از «ImageNotification» استفاده کنید تا این آموزش گام‌به‌گام را دنبال کنید)، Swift یا Objective-C را انتخاب کنید، و روی پایان کلیک کنید.
4. با کلیک کردن روی فعال کردن، طرح را فعال کنید.

مرحله ۲ - افزودن هدف به Podfile

مرحله ۳ - استفاده از دستیار افزونه

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

مرحله ۴ - افزودن تصویر به پایه‌بار

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