إرسال الإشعارات وتلقّيها من تطبيق Flutter باستخدام خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"

1. مقدمة

يرشدك هذا الدرس التطبيقي حول الترميز إلى عملية تطوير تطبيق متوافق مع عدّة منصات باستخدام خدمة "مراسلة Firebase السحابية" ‏ (FCM) باستخدام Flutter. ستكتب جزءًا واحدًا من عملية تنفيذ التطبيق، ثم ستنشئه وتشغّله بسلاسة على ثلاث منصات: Android وiOS والويب. ستتعرّف أيضًا على كيفية دمج FCM في Flutter وكيفية كتابة الرمز البرمجي لتلقّي الرسائل وإرسالها. أخيرًا، يقدّم هذا الدرس التطبيقي حول الترميز ميزة "الكتل الخاصة بالمنصة" في الإصدار 1 من واجهة برمجة التطبيقات HTTP لخدمة مراسلة Firebase السحابية، والتي تتيح لك إرسال رسالة واحدة تتضمّن سلوكيات مختلفة على منصات مختلفة.

المتطلّبات الأساسية

فهم أساسي لإطار عمل Flutter

ما ستتعلمه

• كيفية إعداد تطبيق Flutter وإنشائه
• كيفية إضافة تبعيات FCM
• كيفية إرسال رسائل فردية من خلال ميزة "مراسلة Firebase السحابية" إلى تطبيقك
• كيفية إرسال رسائل FCM إلى تطبيقك بشأن مواضيع معيّنة

المتطلبات

• أحدث إصدار ثابت من استوديو Android تم إعداده باستخدام المكوّنين الإضافيَّين Dart وFlutter

يمكنك تشغيل الدرس العملي باستخدام أي من الأجهزة التالية:

• جهاز Android فعلي متصل بجهاز الكمبيوتر
• محاكي Android (راجِع تشغيل التطبيقات على محاكي Android)
• متصفّح من اختيارك، مثل Chrome

اختياريًا، لتشغيل درس تطبيقي حول الترميز باستخدام منصة iOS، تحتاج إلى جهاز iOS وحساب مطوِّر على Apple وجهاز macOS مثبَّت عليه XCode.

2. إعداد Flutter

إعداد بيئة تطوير Flutter

إذا سبق لك إعداد بيئة تطوير Flutter، يمكنك تخطّي هذا القسم.

لإعداد بيئة تطوير Flutter، اتّبِع الخطوات التالية:

1. نزِّل Flutter وثبِّته لنظام التشغيل: التثبيت | Flutter
2. تأكَّد من إضافة أداة Flutter إلى مسارك.
3. يمكنك إعداد أداة التعديل لـ Flutter كما هو موضّح في إعداد أداة تعديل | Flutter. احرص على تثبيت مكوّنات Flutter وDart الإضافية لأداة التعديل. ستستخدم "استوديو Android" في بقية الدرس العملي.
4. من سطر الأوامر، شغِّل flutter doctor، الذي يفحص الإعدادات ويدرج أي تبعيات ناقصة يجب إصلاحها. اتّبِع التعليمات لحلّ أي تبعيات مهمة غير متوفّرة. يُرجى العِلم أنّ بعض التبعيات قد لا تكون ضرورية. على سبيل المثال، إذا كنت لن تطوّر تطبيقًا لنظام التشغيل iOS، لن تكون مشكلة عدم توفّر CocoaPods من المشاكل التي تمنعك من المتابعة.

إنشاء مشروع Flutter

1. نفِّذ الأوامر التالية لإنشاء تطبيق Flutter، ثم انتقِل إلى الدليل الخاص به:

   flutter create --org com.flutter.fcm --project-name fcmflutter fcmflutter
   cd fcmflutter
   

   ملاحظة: يأخذ الأمر flutter اسم نطاق الشركة بترتيب عكسي للخيار --org واسم المشروع للخيار --project-name. يتم دمج اسم نطاق الشركة واسم المشروع كاسم حزمة لنظام التشغيل Android (معرّف الحزمة لنظام التشغيل iOS)، ويُستخدَم لتحديد تطبيق بشكل فريد.

2. في "استوديو Android"، انتقِل إلى ملف (File) -> فتح (Open)، وابحث عن مسار تطبيق Flutter، ثم انقر على فتح (Open) لفتح المشروع في "استوديو Android". يتوفّر رمز التطبيق في الملف lib/main.dart.

   ملاحظة: لإعداد مسار حزمة تطوير البرامج (SDK) الخاصة بـ Flutter في "استوديو Android"، افتح الإعدادات المفضّلة -> اللغة والإطار -> Flutter واختَر مسار تثبيت Flutter كمسار حزمة تطوير البرامج (SDK).

3. في شريط أدوات استوديو Android، انقر على السهم المتّجه للأسفل لاختيار جهاز Android. إذا كان أداة اختيار الهدف فارغة، ثبِّت أجهزة Android الافتراضية أو متصفّح Chrome أو محاكي iOS إذا كنت تفضّل تشغيل التطبيق من متصفّح ويب أو جهاز iOS. قد تحتاج إلى تشغيل الجهاز يدويًا وإعادة تحميل القائمة للعثور على جهاز الاختبار.

انقر على تشغيل لتشغيل التطبيق.

تهانينا! لقد أنشأت تطبيق Flutter بنجاح.

3- إعداد Firebase وFlutterFire

لتطوير تطبيق يتكامل مع خدمة "مراسلة Firebase السحابية" باستخدام Flutter، يجب استيفاء المتطلبات التالية:

• مشروع على Firebase
• واجهة سطر الأوامر Firebase CLI تعمل بشكل سليم.
• تثبيت FlutterFire
• تطبيق تم إعداده وإنشاؤه باستخدام flutterfire configure

إنشاء مشروع Firebase

إذا كان لديك مشروع Firebase حالي، يمكنك تخطّي هذه الخطوة.

1. سجِّل الدخول إلى وحدة تحكّم Firebase باستخدام حساب Google.
2. انقر على الزر لإنشاء مشروع جديد، ثم أدخِل اسم المشروع (على سبيل المثال، fcm4flutter).
   

   يُستخدَم اسم المشروع هذا كاسم معروض في واجهات Firebase، وتنشئ Firebase تلقائيًا رقم تعريف مشروع فريدًا استنادًا إلى اسم المشروع هذا. يُرجى العِلم أنّه يمكنك اختياريًا النقر على رمز تعديل الآن لضبط رقم تعريف المشروع المفضّل، ولكن لا يمكنك تغيير رقم التعريف هذا بعد إنشاء المشروع.

   تذكَّر رقم تعريف مشروعك لأنّك ستحتاج إليه لاحقًا لتحديد مشروع Firebase الخاص بك في Firebase CLI. إذا نسيت رقم التعريف، يمكنك العثور عليه لاحقًا في إعدادات المشروع.

3. انقر على متابعة.
4. إذا طُلب منك ذلك، راجِع بنود Firebase واقبلها، ثم انقر على متابعة.
5. (اختياري) فعِّل ميزة "المساعدة المستندة إلى الذكاء الاصطناعي" في وحدة تحكّم Firebase (المعروفة باسم "Gemini في Firebase").
6. في هذا الدرس العملي، لا تحتاج إلى "إحصاءات Google"، لذا أوقِف خيار "إحصاءات Google".
7. انقر على إنشاء مشروع، وانتظِر إلى أن يتم توفير مشروعك، ثم انقر على متابعة.

تهانينا! لقد أنشأت مشروع Firebase بنجاح.

إعداد Firebase CLI

إذا سبق لك إعداد Firebase CLI، يمكنك تخطّي هذه الخطوة.

انتقِل إلى مرجع Firebase CLI لتنزيل وتثبيت Firebase CLI. سجِّل الدخول إلى Firebase باستخدام حساب Google من خلال الأمر التالي:

firebase login

إعداد FlutterFire

افتح سطر الأوامر في مشروعك في "استوديو Android" (عرض -> نوافذ الأدوات -> الوحدة الطرفية) ونفِّذ الأوامر التالية لإعداد FlutterFire:

1. ثبِّت المكوّن الإضافي FlutterFire:

   flutter pub add firebase_core
   

2. ثبِّت المكوّن الإضافي لخدمة FCM:

   flutter pub add firebase_messaging
   

3. إعداد FlutterFire CLI:

   dart pub global activate flutterfire_cli
   

4. إعداد مشروع Firebase على Flutter:

   flutterfire configure --PROJECT_ID
   

   استبدِل PROJECT_ID برقم تعريف مشروع Firebase الذي أنشأته في الخطوة الأولى. استخدِم مفاتيح الأسهم ومفتاح المسافة لاختيار المنصات أو اضغط على مفتاح Enter لاستخدام المنصات التلقائية.

يستخدم هذا الدرس التطبيقي حول الترميز المنصات التلقائية (Android وiOS والويب)، ولكن يمكنك اختيار منصة واحدة أو اثنتين فقط. إذا طُلب منك إدخال معرّف حزمة iOS، أدخِل com.flutter.fcm.fcmflutter أو معرّف حزمة iOS الخاص بك بالتنسيق [company domain name].[project name]. بعد اكتمال الأمر، أعِد تحميل صفحة "وحدة تحكّم Firebase". سيظهر لك أنّه تم إنشاء تطبيقات للمنصات المحدّدة ضمن مشروع Firebase.

ينشئ هذا الأمر ملف firebase_options.dart ضمن الدليل lib، ويحتوي على جميع الخيارات المطلوبة لعملية الإعداد.

إعداد خدمة المراسلة عبر السحابة الإلكترونية على أجهزة iOS

1. انتقِل إلى صفحة المطوّرين على Apple، ثم انقر على إنشاء مفتاح في علامة التبويب المفاتيح.

2. أدخِل اسم المفتاح وضع علامة في المربّع بجانب خدمات الإشعارات الفورية في Apple ‏ (APNs).
3. نزِّل ملف المفتاح الذي يحمل الامتداد .p8.
4. في وحدة تحكّم Firebase، انتقِل إلى إعدادات المشروع واختَر علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية.

5. حمِّل ملف مفتاح APNs لتطبيق iOS في علامة التبويب Cloud Messaging. أدخِل معرّف مفتاح APNs من علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية ومعرّف الفريق الذي يمكن العثور عليه في مركز عضوية Apple.

4. التحضير لاستخدام "مراسلة Firebase السحابية"

قبل أن يتمكّن التطبيق من تلقّي الرسائل من خدمة "مراسلة Firebase السحابية"، عليه تنفيذ ما يلي:

• إعداد FlutterFire
• طلب أذونات إرسال الإشعارات
• سجِّل في FCM للحصول على رمز تسجيل.

الإعداد

لبدء الخدمة، استبدِل الدالة الرئيسية (lib/main.dart) بالرمز التالي:

// core Flutter primitives
import 'package:flutter/foundation.dart';
// core FlutterFire dependency
import 'package:firebase_core/firebase_core.dart';
// generated by flutterfire configure
import 'firebase_options.dart';
// FlutterFire's Firebase Cloud Messaging plugin
import 'package:firebase_messaging/firebase_messaging.dart';

// TODO: Add stream controller
// TODO: Define the background message handler

Future<void> main() async {
 WidgetsFlutterBinding.ensureInitialized();
 await Firebase.initializeApp(
   options: DefaultFirebaseOptions.currentPlatform,
 );

 // TODO: Request permission
 // TODO: Register with FCM
 // TODO: Set up foreground message handler
 // TODO: Set up background message handler
 // TODO: Subscribe to a topic

 runApp(MyApp());
}

بعد ذلك، شغِّل Tools -> Flutter -> Flutter Pub Get في "استوديو Android" لتحميل الحِزم التي تمت إضافتها في إعداد FlutterFire، وعرْض الرمز مع إعداد Intellisense المناسب في "استوديو Android".

يؤدي ذلك إلى تهيئة FlutterFire للنظام الأساسي الحالي DefaultFirebaseOptions.currentPlatform، والذي يتم استيراده من الملف firebase_options.dart الذي تم إنشاؤه. يُرجى العِلم أنّ initializeApp هي دالة غير متزامنة، وتضمن الكلمة الرئيسية await اكتمال عملية التهيئة قبل تشغيل التطبيق.

ملاحظة: يتوفّر الرمز الكامل لهذا الدرس التطبيقي حول الترميز على الرابط https://github.com/FirebaseExtended/firebase_fcm_flutter

طلب الإذن

يجب أن يطلب التطبيق إذن المستخدم لتلقّي الإشعارات. تعرض الطريقة requestPermission التي توفّرها firebase_messaging مربّع حوار أو نافذة منبثقة تطلب من المستخدم السماح بالإذن أو رفضه.

أولاً، انسخ هذا الرمز إلى الدالة الرئيسية تحت التعليق TODO: Request permission. يخبرك الرمز settings الذي تم عرضه بما إذا كان المستخدم قد منح الإذن.

final messaging = FirebaseMessaging.instance;

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

 if (kDebugMode) {
   print('Permission granted: ${settings.authorizationStatus}');
 }

ملاحظة: ننصحك بطلب الإذن فقط عندما يحتاج المستخدم إلى استخدام ميزة تتطلّب الوصول إلى البيانات (على سبيل المثال، عندما يفعّل المستخدم الإشعارات في إعدادات التطبيق). في هذا الدرس التطبيقي حول الترميز، يطلب التطبيق الإذن عند بدء التشغيل لتسهيل الأمر.

بعد ذلك، في شريط أدوات استوديو Android، انقر على Chrome (web) من أداة اختيار الهدف، ثم شغِّل التطبيق مرة أخرى.

بعد ذلك، يتم فتح علامة تبويب في Chrome مع نافذة منبثقة تطلب الإذن. إذا نقرت على Allow، سيظهر لك سجلّ في وحدة تحكّم "استوديو Android": Permission granted: AuthorizationStatus.authorized. بعد السماح بطلب الحصول على إذن أو حظره، يتم تخزين ردّك مع تطبيقك في المتصفّح، ولا يتم عرض النافذة المنبثقة مرة أخرى. يُرجى العِلم أنّه عند تشغيل تطبيق الويب مرة أخرى على استوديو Android، قد يُطلب منك منح الإذن مرة أخرى.

التسجيل

انسخ هذا الرمز إلى الدالة الرئيسية أسفل التعليق TODO: Register with FCM للتسجيل في FCM. تعرض الدالة getToken رمز تسجيل يمكن أن يستخدمه خادم التطبيق أو بيئة الخادم الموثوق بها لإرسال رسائل إلى المستخدمين.

// It requests a registration token for sending messages to users from your App server or other trusted server environment.
String? token = await messaging.getToken();

if (kDebugMode) {
  print('Registration Token=$token');
}

ملاحظة: الرمز أعلاه مخصّص لأغراض العرض التوضيحي فقط. في الظروف العادية:

• يطلب التطبيق عادةً رمز تسجيل عندما ينفّذ المستخدم إجراءً. يجب عدم طلب رمز مميّز أثناء بدء تشغيل التطبيق، لأنّ ذلك يؤدي إلى إجراء مكالمة حظر إلى "مراسلة Firebase السحابية" قد يستغرق إكمالها بعض الوقت.
• يرسل التطبيق الرمز المميّز إلى خادم التطبيق الذي عادةً ما يخزّنه في مكان مخصّص. في وقت لاحق، يستردّ خادم التطبيق الرمز المميّز من المتجر ويستخدمه لتوجيه الرسائل المرسَلة إلى المستخدم.

في شريط أدوات "استوديو Android"، اختَر جهاز Android وشغِّل التطبيق. في وحدة تحكّم "استوديو Android"، تتم طباعة رمز التسجيل على النحو التالي:

I/flutter ( 3717): Permission granted: AuthorizationStatus.authorized
I/flutter ( 3717): Registration Token=dch. . . D2P:APA9. . .kbb4

انسخها إلى محرر نصوص، لأنّك ستستخدمها لإرسال الرسائل لاحقًا.

ملاحظة: إذا واجهت أخطاءً بسبب إصدارات غير صحيحة من حزمة تطوير البرامج (SDK) أو "حزمة تطوير التطبيقات الأصلية" (NDK)، اتّبِع التعليمات الواردة في نافذة الوحدة الطرفية وحدِّد minSdkVersion (على سبيل المثال، 19) وndkVersion (على سبيل المثال، 27) الصحيحَين في ملف android/app/build.gradle في دليل المشروع.

uses-sdk:minSdkVersion 16 cannot be smaller than version 19 declared in library [:firebase_messaging]

خطوات إضافية لتلقّي الرسائل على الويب

تتطلّب تطبيقات الويب خطوتَين إضافيتَين للحصول على رمز التسجيل والاستماع إلى الرسائل الواردة. يجب أن يمرّر الويب مفتاح VAPID إلى getToken من أجل السماح بإرسال الطلبات إلى خدمات الإشعارات الفورية المتوافقة على الويب.

أولاً، افتح علامة التبويب خدمة المراسلة عبر السحابة الإلكترونية في مشروع Firebase في "وحدة تحكّم Firebase"، ثم انتقِل للأسفل إلى قسم إعدادات الويب للعثور على مفتاحي التشفير الحاليين أو إنشاء مفتاحي تشفير جديدين. انقر على الزر المميّز لنسخ المفتاح حتى يمكن استخدامه كـ vapidKey.

بعد ذلك، استبدِل رمز التسجيل في قسم "التسجيل" بهذا الرمز، ثم عدِّل vapidKey:

// TODO: replace with your own VAPID key
 const vapidKey = "<YOUR_PUBLIC_VAPID_KEY_HERE>";

 // use the registration token to send messages to users from your trusted server environment
 String? token;

 if (DefaultFirebaseOptions.currentPlatform == DefaultFirebaseOptions.web) {
   token = await messaging.getToken(
     vapidKey: vapidKey,
   );
 } else {
   token = await messaging.getToken();
 }

 if (kDebugMode) {
   print('Registration Token=$token');
 }

بعد ذلك، أنشئ ملف firebase-messaging-sw.js أسفل الدليل web/ في جذر مشروعك. انسخ ما يلي إلى firebase-messaging-sw.js للسماح لتطبيق الويب بتلقّي أحداث onMessage. لمزيد من المعلومات، اطّلِع على ضبط خيارات الإشعارات في عامل الخدمة.

importScripts("https://www.gstatic.com/firebasejs/9.6.10/firebase-app-compat.js");
importScripts("https://www.gstatic.com/firebasejs/9.6.10/firebase-messaging-compat.js");

// todo Copy/paste firebaseConfig from Firebase Console
const firebaseConfig = {
 apiKey: "...",
 authDomain: "...",
 projectId: "...",
 storageBucket: "...",
 messagingSenderId: "...",
 appId: "...",
};

firebase.initializeApp(firebaseConfig);
const messaging = firebase.messaging();

// todo Set up background message handler

بعد ذلك، ضمن علامة التبويب إعدادات المشروع -> عام، انتقِل للأسفل وابحث عن تطبيق الويب، وانسخ قسم الرمز firebaseConfig والصِقه في firebase-messaging-sw.js.

أخيرًا، في شريط أدوات استوديو Android، انقر على Chrome (web) في أداة اختيار الهدف وشغِّل التطبيق. في وحدة تحكّم استوديو Android، تتم طباعة رمز التسجيل على النحو التالي:

Debug service listening on ws://127.0.0.1:61538/BLQQ3Fg-h7I=/ws
Permission granted: AuthorizationStatus.authorized
Registration Token=fH. . .ue:APA91. . .qwt3chpv

انسخ رمز التسجيل المميز في محرر نصوص لتتمكّن من استخدامه لإرسال الرسائل لاحقًا.

خطوات إضافية لتلقّي الرسائل على أجهزة iOS

لتلقّي الرسائل من مراسلة Firebase السحابية، يجب أن تفعِّل الأجهزة التي تعمل بنظام التشغيل iOS الإشعارات الفورية وأوضاع التشغيل في الخلفية على Xcode.

1. في "استوديو Android"، انقر على المجلد ios في شجرة ملفات المشروع، ثم اختَر الأدوات (Tools) -> Flutter -> فتح وحدة iOS في XCode (Open iOS module in XCode).
2. بعد تشغيل Xcode، فعِّل الإشعارات الفورية وأوضاع التشغيل في الخلفية في علامة التبويب التوقيع والقدرات لهدف المشروع. لمزيد من المعلومات، اطّلِع على مقالة ضبط تطبيقك.
3. في شريط أدوات "استوديو Android"، اختَر جهاز iOS في أداة اختيار الهدف وشغِّل التطبيق. وبعد منح إذن إرسال الإشعارات، تتم طباعة رمز التسجيل في وحدة تحكّم "استوديو Android".

ملاحظة: إذا واجهت خطأ أثناء إنشاء التطبيق بسبب نظام التشغيل iOS غير الصحيح، اضبط المنصة المستهدفة platform :ios على 13.0 أو إصدار أحدث في podfile الموجود في الدليل ios.

تهانينا، لقد سجّلت تطبيقك بنجاح في خدمة FCM. أنت الآن جاهز لتلقّي الرسائل، كما هو موضّح في القسم التالي.

5- تلقّي الرسائل من FCM

إعداد معالجات الرسائل

يحتاج التطبيق إلى معالجة أحداث onMessage عند وصول الرسائل أثناء عمل التطبيق في وضع المقدّمة، وأحداث onBackgroundMessage عندما يعمل التطبيق في الخلفية.

معالج الرسائل في المقدّمة

أولاً، أضِف أداة تحكّم في البث بعد التعليق TODO: Add stream controller في الملف main.dart من أجل تمرير الرسائل من معالج الأحداث إلى واجهة المستخدم.

import 'package:rxdart/rxdart.dart';
// used to pass messages from event handler to the UI
final _messageStreamController = BehaviorSubject<RemoteMessage>();

لإضافة التبعية rxdart، نفِّذ الأمر التالي من دليل المشروع:

flutter pub add rxdart

بعد ذلك، شغِّل الأدوات -> Flutter -> Flutter Pub Get في "استوديو Android" لتحميل حزمة rxdart.dart وعرض الرمز مع إعدادات Intellisense المناسبة في "استوديو Android".

بعد ذلك، أضِف معالج أحداث للاستماع إلى الرسائل التي تظهر في المقدّمة بعد التعليق TODO: Set up foreground message handler. يطبع السجلّات وينشر الرسالة إلى وحدة التحكّم في البث.

 FirebaseMessaging.onMessage.listen((RemoteMessage message) {
   if (kDebugMode) {
     print('Handling a foreground message: ${message.messageId}');
     print('Message data: ${message.data}');
     print('Message notification: ${message.notification?.title}');
     print('Message notification: ${message.notification?.body}');
   }

   _messageStreamController.sink.add(message);
 });

بعد ذلك، استبدِل أداة State الأصلية الموجودة في نهاية ملف main.dart بالرمز التالي الذي يضيف مشتركًا إلى وحدة التحكّم في البث في أداة State ويعرض آخر رسالة على الأداة.

class _MyHomePageState extends State<MyHomePage> {
 String _lastMessage = "";

 _MyHomePageState() {
   _messageStreamController.listen((message) {
     setState(() {
       if (message.notification != null) {
         _lastMessage = 'Received a notification message:'
             '\nTitle=${message.notification?.title},'
             '\nBody=${message.notification?.body},'
             '\nData=${message.data}';
       } else {
         _lastMessage = 'Received a data message: ${message.data}';
       }
     });
   });
 }

 @override
 Widget build(BuildContext context) {
   return Scaffold(
     appBar: AppBar(
       title: Text(widget.title),
     ),
     body: Center(
       child: Column(
         mainAxisAlignment: MainAxisAlignment.center,
         children: <Widget>[
           Text('Last message from Firebase Messaging:',
               style: Theme.of(context).textTheme.titleLarge),
           Text(_lastMessage, style: Theme.of(context).textTheme.bodyLarge),
         ],
       ),
     ),
   );
 }
}

معالج الرسائل في الخلفية لنظام التشغيل Android/iOS

تتم معالجة الرسائل بواسطة معالج onBackgroundMessage أثناء تشغيل التطبيق في الخلفية. يجب أن يكون المعالج دالة ذات مستوى أعلى. يمكن تعديل واجهة المستخدم عند نقل التطبيق إلى المقدّمة من خلال معالجة الرسائل (راجِع التعامل مع التفاعل) أو المزامنة مع خادم التطبيق.

أنشئ دالة المعالجة بعد التعليق TODO: Define the background message handler خارج الدالة الرئيسية واستدعِها في الدالة الرئيسية بعد التعليق TODO: Set up background message handler.

// TODO: Define the background message handler
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
 await Firebase.initializeApp();

 if (kDebugMode) {
   print("Handling a background message: ${message.messageId}");
   print('Message data: ${message.data}');
   print('Message notification: ${message.notification?.title}');
   print('Message notification: ${message.notification?.body}');
 }
}

void main() {
 ...

 // TODO: Set up background message handler
 FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

 runApp(MyApp());
}

معالج الرسائل في الخلفية للويب

اعتبارًا من الإصدار 11.2.8 من حزمة firebase_messaging في FlutterFire، تتطلّب معالجة الرسائل في الخلفية على المنصات المستندة إلى الويب مسارًا مختلفًا. لذلك، عليك إضافة معالج رسائل منفصل في عامل الخدمة web/firebase-messaging-sw.js.

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

إعداد خادم التطبيق

1. استنسِخ مستودع رموز الخادم https://github.com/FirebaseExtended/firebase_fcm_flutter/tree/main/server وافتحه في "استوديو Android" كمشروع جديد. الخادم هو مشروع Java يستند إلى Gradle ويتضمّن تبعية لحزمة تطوير البرامج (SDK) الخاصة بـ firebase-admin، والتي توفّر وظيفة إرسال الرسائل عبر خدمة "المراسلة عبر السحابة الإلكترونية من Firebase".
2. إعداد حساب خدمة Firebase الذي يتيح لحزمة تطوير البرامج (SDK) للمشرف في Firebase تفويض طلبات إلى واجهات برمجة التطبيقات في خدمة المراسلة عبر السحابة الإلكترونية Firebase (FCM) افتح إعدادات المشروع في "وحدة تحكّم Firebase" واختَر علامة التبويب حسابات الخدمة. اختَر "Java" وانقر على Generate new private key لتنزيل مقتطف الإعداد.
3. أعِد تسمية الملف إلى service-account.json وانسخه إلى مسار src/main/resources في مشروع الخادم.

إرسال رسالة اختبار

في الملف FcmSender.java، ينشئ sendMessageToFcmRegistrationToken رسالة إشعار مع عرض بيانات أساسية. يستهدف رمز التسجيل مثيل التطبيق الذي يتم إرسال الرسالة إليه.

private static void sendMessageToFcmRegistrationToken() throws Exception {
   String registrationToken = "REPLACE_WITH_FCM_REGISTRATION_TOKEN";
   Message message =
       Message.builder()
           .putData("FCM", "https://firebase.google.com/docs/cloud-messaging")
           .putData("flutter", "https://flutter.dev/")
           .setNotification(
               Notification.builder()
                   .setTitle("Try this new app")
                   .setBody("Learn how FCM works with Flutter")
                   .build())
           .setToken(registrationToken)
           .build();

   FirebaseMessaging.getInstance().send(message);

   System.out.println("Message to FCM Registration Token sent successfully!!");
 }

1. انسخ رمز التسجيل على Android الذي تم نسخه من قسم "التسجيل"، وألصِقه في قيمة المتغيّر registrationToken.
2. انقر على تشغيل لتشغيل الدالة الرئيسية وإرسال الرسالة إلى المستخدم من خلال FCM.

عندما يكون تطبيق Android يعمل في الخلفية، تظهر الرسالة في قائمة الإشعارات.

عندما يكون تطبيق Android في المقدّمة، سيظهر لك سجلّ في وحدة تحكّم "استوديو Android": "Handling a foreground message" (جارٍ التعامل مع رسالة في المقدّمة). يظهر محتوى الرسالة أيضًا في واجهة المستخدم لأنّ واجهة المستخدم مشترِكة في أداة التحكّم في البث لتلقّي الرسائل الجديدة.

إذا لصقت رمز التسجيل وأرسلت الرسالة من خادم التطبيق أو بيئة خادم موثوقة أخرى، سيظهر لك سلوك مشابه:

• عندما يكون تطبيق الويب في الخلفية (على سبيل المثال، عندما يكون مخفيًا بواسطة نافذة أخرى أو تكون علامة تبويب أخرى نشطة)، سيظهر لك إشعار على الويب.

• عندما يكون تطبيق الويب في المقدّمة، يمكنك عرض السجلّ في "وحدة تحكّم Chrome" من خلال النقر بزر الماوس الأيمن على الويب واختيار Inspect. يظهر محتوى الرسالة أيضًا في واجهة المستخدم.

ملاحظة: في كل مرة يتم فيها إغلاق تطبيق الويب وإعادة فتحه، قد يتم تعديل رمز التسجيل. احرص على تعديل الرمز المميز في الرمز إذا لم يتم تسليم الإشعار بشكل صحيح.

6. إرسال رسالة موضوع

تتيح ميزة تجاهل النظام الأساسي في واجهة برمجة التطبيقات HTTP v1 الخاصة بخدمة FCM أن يتضمّن طلب إرسال رسالة سلوكيات مختلفة على أنظمة أساسية مختلفة. من حالات استخدام هذه الميزة عرض محتوى مختلف لرسالة الإشعار استنادًا إلى المنصة. يتم استخدام الميزة على أكمل وجه عند استهداف أجهزة متعددة (قد تشمل منصات متعددة) باستخدام رسائل المواضيع. يوضّح لك هذا القسم خطوات إعداد تطبيقك لتلقّي رسالة موضوع مخصّصة لكل نظام أساسي.

الاشتراك في موضوع من العميل

للاشتراك في موضوع، انسخ هذا الرمز إلى الدالة الرئيسية أسفل التعليق TODO: Subscribe to a topic:

// subscribe to a topic.
const topic = 'app_promotion';
await messaging.subscribeToTopic(topic);

[اختياري] الاشتراك في موضوع من الخادم على الويب

يمكنك تخطّي هذا القسم إذا كنت لا تطوّر على منصة الويب.

لا تتيح حزمة تطوير البرامج (SDK) لخدمة FCM JavaScript حاليًا الاشتراك في المواضيع من جهة العميل. بدلاً من ذلك، يمكنك الاشتراك باستخدام واجهة برمجة تطبيقات إدارة المواضيع من جهة الخادم في Admin SDK. يوضّح هذا الرمز في ملف FcmSubscriptionManager.java عملية الاشتراك في المواضيع من جهة الخادم باستخدام حزمة Java Admin SDK. احرص على إضافة رمز التسجيل في FCM قبل تشغيله:

 private static void subscribeFcmRegistrationTokensToTopic() throws Exception {
   List<String> registrationTokens =
       Arrays.asList(
           "REPLACE_WITH_FCM_REGISTRATION_TOKEN"); // TODO: add FCM Registration Tokens to
   // subscribe
   String topicName = "app_promotion";

   TopicManagementResponse response =     FirebaseMessaging.getInstance().subscribeToTopic(registrationTokens, topicName);
   System.out.printf("Num tokens successfully subscribed %d", response.getSuccessCount());
 }

ملاحظة: في كل مرة يتم فيها إغلاق تطبيق الويب وإعادة فتحه، قد يتم تعديل رمز التسجيل. احرص على تعديل الرمز المميز في الرمز إذا لم يتم تسليم الإشعار بشكل صحيح.

افتح خادم التطبيق وانقر على تشغيل لتشغيل الوظيفة الرئيسية في ملف FcmSubscriptionManager.java:

إرسال رسالة تتضمّن عمليات إلغاء على مستوى النظام الأساسي إلى موضوع

أنت الآن جاهز لإرسال رسالة إلغاء لمنصة موضوع معيّن. في مقتطف الرمز البرمجي التالي:

• يمكنك إنشاء طلب إرسال يتضمّن رسالة أساسية وعنوانًا "A new app is available".
• تنشئ الرسالة إشعارًا معروضًا بالعنوان "A new app is available" على منصات iOS والويب.
• تنشئ الرسالة إشعارًا مع العنوان "A new Android app is available" على أجهزة Android.

private static void sendMessageToFcmTopic() throws Exception {
   String topicName = "app_promotion";

   Message message =
       Message.builder()
           .setNotification(
               Notification.builder()
                   .setTitle("A new app is available")
                   .setBody("Check out our latest app in the app store.")
                   .build())
           .setAndroidConfig(
               AndroidConfig.builder()
                   .setNotification(
                       AndroidNotification.builder()
                           .setTitle("A new Android app is available")
                           .setBody("Our latest app is available on Google Play store")
                           .build())
                   .build())
           .setTopic("app_promotion")
           .build();

   FirebaseMessaging.getInstance().send(message);

   System.out.println("Message to topic sent successfully!!");
 }

في الدالة الرئيسية للملف FcmSender.java، أزِل التعليق من sendMessageToFcmTopic();. انقر على تشغيل لإرسال رسالة الموضوع.

7. الملخّص والخطوات التالية

باختصار، تعرّفت على كيفية تطوير تطبيقات تفاعلية متعددة المنصات باستخدام Flutter ومراسلة Firebase السحابية، بما في ذلك إعداد البيئة ودمج الاعتماديات وتلقّي الرسائل وإرسالها. لمزيد من التفاصيل، يُرجى الاطّلاع على المواد التالية:

Codelabs

• لمزيد من المعلومات عن كيفية عمل Flutter مع منتجات Firebase الأخرى، بما في ذلك مصادقة المستخدمين ومزامنة البيانات، اطّلِع على مقالة التعرّف على كيفية الاستفادة من منصة Firebase عند تطوير التطبيقات باستخدام Flutter.
• لمزيد من المعلومات عن مراسلة Firebase السحابية، بما في ذلك الرسائل داخل التطبيق والمواضيع، يُرجى الاطّلاع على: استخدام مراسلة Firebase السحابية والرسائل داخل التطبيق لإرسال رسائل إلى المستخدمين و أول رسالة فورية متعددة الإرسال باستخدام مواضيع مراسلة Firebase السحابية

المراجع

• موقع Firebase الإلكتروني
• موقع Flutter الإلكتروني
• أدوات FlutterFire Firebase Flutter
• قناة Firebase على YouTube
• قناة Flutter على YouTube