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

1- مقدمة

تاريخ التعديل الأخير: 04-04-2022

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

شرط أساسي

فهم أساسيات Flutter

المعلومات التي ستطّلع عليها

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

المتطلبات

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

يمكنك تنفيذ الدرس التطبيقي حول الترميز باستخدام أي من الأجهزة التالية:

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

2- إعداد Flutter

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

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

  1. تنزيل برنامج Flutter وتثبيته لنظام التشغيل: تثبيت | مرفرفة
  2. تأكَّد من إضافة أداة Flutter إلى مسارك.
  3. إعداد المحرِّر لتطبيق Flutter كما هو موضَّح في إعداد محرِّر | Flutter تأكَّد من تثبيت المكوّنَين الإضافيَين Flutter وDart في المحرِّر. ستستخدم استوديو Android في بقية الدرس التطبيقي حول الترميز.
  4. من سطر الأوامر، شغِّل flutter doctor، الذي يفحص عملية الإعداد ويسرد أي تبعيات مفقودة يجب إصلاحها. اتبع التعليمات لإصلاح أي تبعيات مفقودة مهمة. لاحظ أن بعض التبعيات قد لا تكون ضرورية. على سبيل المثال، إذا كنت لا تريد التطوير لنظام التشغيل iOS، لن يكون عدم وجود تبعية CocoaPods مشكلة في الحظر.
  5. نفِّذ هذا الأمر لإنشاء تطبيق Flutter في دليل fcmflutter (flutter create --org com.flutter.fcm --project-name fcmflutter fcmflutter)، ثم غيِّر الأدلة إلى fcmflutter.
  1. في "استوديو Android"، انتقِل إلى ملف -> افتح وابحث عن مسار تطبيق Flutter ثم انقر على فتح لفتح المشروع في "استوديو Android". يتوفّر رمز التطبيق في ملف lib/main.dart.

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

شريط أدوات على "استوديو Android" مع تمييز سهم القائمة المنسدلة لقائمة إنشاء الاستهداف

انقر على تشغيل زر التشغيل في "استوديو Android" لتشغيل التطبيق.

واجهة المستخدم لتطبيق Flutter التجريبي الذي تم إطلاقه

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

3- إعداد Firebase وFlutterFire

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

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

إنشاء مشروعك على Firebase

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

  1. إذا كان لديك حساب على Google، افتح Firebase وسجِّل الدخول باستخدام حسابك على Google، ثم انقر على الانتقال إلى وحدة التحكّم.
  2. في "وحدة تحكُّم Firebase"، انقر على إضافة مشروع. اتّبِع التعليمات لإنشاء مشروع. لا تضع علامة في المربّع تفعيل "إحصاءات Google" لهذا المشروع لأنّك لن تستخدمه فيه.
  3. بعد إنشاء المشروع، انتقِل إلى إعدادات المشروع الخاصة به من خلال النقر على رمز الترس بجانب نظرة عامة على المشروع.

لقطة شاشة تم اقتصاصها من "وحدة تحكُّم Firebase" لتمييز رمز قائمة إعدادات المشروع

يتم استخدام رقم تعريف المشروع لتعريف المشروع بشكلٍ فريد، وقد يختلف عن اسم المشروع. سيتم استخدام رقم تعريف المشروع لإعداد FlutterFire لاحقًا.

لقطة شاشة تم اقتصاصها من "وحدة تحكُّم Firebase" تُبرز رقم تعريف المشروع

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

إعداد واجهة سطر الأوامر في Firebase

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

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

firebase login

إعداد FlutterFire

  1. ثبِّت المكوّن الإضافي FlutterFire باستخدام الأمر: flutter pub add firebase_core
  2. تثبيت المكوّن الإضافي لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase": flutter pub add firebase_messaging
  3. إعداد واجهة سطر الأوامر FlutterFire: dart pub global activate flutterfire_cli
  4. ضبط مشروع Firebase على Flutter: flutterfire configure --project=fcm4flutter. استخدِم مفاتيح الأسهم والمسافة لاختيار الأنظمة الأساسية، أو اضغط على Enter لاستخدام المنصات التلقائية.

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

لقطة شاشة تم اقتصاصها من "وحدة تحكُّم Firebase" تعرض التطبيقات التي تم إنشاؤها للمنصّات المحدّدة.

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

إعداد خدمة "المراسلة عبر السحابة الإلكترونية" لنظام التشغيل iOS

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

لقطة شاشة تم اقتصاصها لصفحة مطوّر برامج Apple تُبرز مكوّنات الصفحة لإنشاء المفتاح

  1. أدخِل اسم المفتاح وحدِّد خدمات الإشعارات الفورية في Apple (APN). لقطة شاشة تم اقتصاصها لصفحة مطوِّر البرامج من Apple مع إبراز مربّع نص اسم المفتاح الجديد
  2. نزِّل ملف المفتاح الذي يحتوي على امتداد الملف .p8. لقطة شاشة تم اقتصاصها لصفحة مطوِّر برامج Apple تُبرز زر تنزيل مفتاح.
  3. في وحدة تحكُّم Firebase، انتقِل إلى إعدادات المشروع للمشروع واختَر علامة التبويب المراسلة عبر السحابة الإلكترونية.

لقطة شاشة تم اقتصاصها لصفحة "وحدة تحكُّم Firebase" تُبرز مكونات تعديل إعدادات المشروع.

لقطة شاشة تم اقتصاصها لصفحة "وحدة تحكُّم Firebase" تُبرز علامة التبويب "المراسلة عبر السحابة الإلكترونية"

  1. حمِّل ملف مفتاح أسماء نقاط الوصول (APNs) لتطبيق iOS في علامة التبويب المراسلة عبر السحابة الإلكترونية. أدخِل معرّف مفتاح أسماء نقاط الوصول (APN) من علامة التبويب المراسلة في السحابة الإلكترونية ورقم تعريف الفريق الذي يمكن العثور عليه في مركز اشتراك Apple. لقطة شاشة تم اقتصاصها لصفحة "وحدة تحكُّم Firebase" تبرز الأزرار الخاصة بتحميل مفتاح مصادقة أسماء نقاط الوصول (APN).

4. التحضير لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase"

قبل أن يتلقى التطبيق الرسائل من ميزة "المراسلة عبر السحابة الإلكترونية من Firebase"، يجب:

  • إعداد FlutterFire
  • اطلب أذونات إرسال الإشعارات.
  • سجِّل من خلال خدمة "المراسلة عبر السحابة الإلكترونية من Firebase" للحصول على الرمز المميّز للتسجيل.

الإعداد

لإعداد الخدمة، استبدل الدالة الرئيسية (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

 runApp(MyApp());
}

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

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

طلب الإذن

يجب أن يطلب التطبيق إذن المستخدم لتلقّي الإشعارات. تعرض طريقة 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) من أداة اختيار الاستهداف، ثم شغِّل التطبيق مرة أخرى.

لقطة شاشة تم اقتصاصها لشريط أدوات &quot;استوديو Android&quot; مع أداة الاختيار المستهدفة والزر &quot;تشغيل&quot;

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

التسجيل

انسخ هذا الرمز إلى الوظيفة الرئيسية أسفل التعليق 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');
}

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

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

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

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

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

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

أولاً، افتح علامة التبويب المراسلة عبر السحابة الإلكترونية لمشروع Firebase في "وحدة تحكُّم Firebase"، ثم مرِّر للأسفل إلى القسم ضبط الويب للعثور على مفتاحَي التشفير الحاليين أو أنشئ مفتاحَي تشفير جديدَين. انقر على الزر المميّز لنسخ المفتاح حتى يمكن استخدامه كمفتاح vapid.

لقطة شاشة تم اقتصاصها لمكوّن شهادات Web Push في صفحة إعداد الويب التي تُبرز مفتاحَي التشفير

بعد ذلك، استبدِل رمز التسجيل في قسم التسجيل بهذا الرمز، ثم عدِّل 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: "...",
 databaseURL: "...",
 projectId: "...",
 storageBucket: "...",
 messagingSenderId: "...",
 appId: "...",
};

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

// todo Set up background message handler

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

وأخيرًا، في شريط أدوات "استوديو 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"، يجب تفعيل الإشعارات الفورية وأوضاع الخلفية على Xcode على أجهزة iOS:

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

لقطة شاشة تم اقتصاصها لتطبيق iOS يطلب الإذن بإرسال إشعارات.

تهانينا، لقد سجّلت تطبيقك بنجاح من خلال خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". ستكون جاهزًا لتلقي الرسائل، كما هو موضح في القسم التالي.

5- تلقي رسائل من خدمة "المراسلة عبر السحابة الإلكترونية من Firebase"

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

يحتاج التطبيق إلى معالجة أحداث 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 في "استوديو 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);
 });

بعد ذلك، استبدِل تطبيق "الولاية" المصغّر الأصلي في الملف main.dart بهذا الرمز، ما يؤدي إلى إضافة مشترك إلى وحدة التحكّم بالبث في تطبيق "الولاية" المصغّر، ثم عرض الرسالة الأخيرة على التطبيق المصغّر.

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 من FlutterFire firebase_messaging، أصبح التعامل مع الرسائل في الخلفية على الأنظمة الأساسية المستنِدة إلى الويب يتطلب مسارًا مختلفًا. لذا، يجب إضافة معالج رسائل منفصل في عامل الخدمة 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، التي توفر وظيفة إرسال الرسائل عبر خدمة FCM.
  2. عليك إعداد حساب خدمة Firebase يسمح لحزمة تطوير البرامج (SDK) لمشرف Firebase بمنح الإذن باستدعاء واجهات برمجة تطبيقات المراسلة عبر السحابة الإلكترونية من Firebase. افتح إعدادات المشروع في وحدة تحكُّم Firebase واختَر علامة التبويب حسابات الخدمة. اختيار "Java" وانقر على Generate new private key لتنزيل مقتطف الإعدادات. لقطة شاشة تم اقتصاصها تبرز مقتطف إعداد &quot;SDK للمشرف&quot; لمكوِّن حسابات الخدمة في صفحة &quot;إعدادات المشروع&quot;.
  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. انقر على تشغيل زر التشغيل في &quot;استوديو Android&quot; لتشغيل الدالة الرئيسية وإرسال الرسالة إلى المستخدم من خلال خدمة "المراسلة عبر السحابة الإلكترونية من Firebase". لقطة شاشة تم اقتصاصها لرمز &quot;التشغيل&quot; الذي يظهر بجانب الوظيفة الرئيسية FcmSender.java في &quot;استوديو Android&quot;

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

لقطة شاشة تم اقتصاصها لرسالة تظهر في درج إشعارات Android

عندما يكون تطبيق Android في المقدّمة، سيظهر لك سجلّ في وحدة تحكّم "استوديو Android" بعنوان "التعامل مع الرسالة التي تعمل في المقدّمة". ويظهر محتوى الرسالة أيضًا في واجهة المستخدم لأنّ واجهة المستخدم مشتركة في وحدة التحكّم بالبث للرسائل الجديدة.

لقطة شاشة تم اقتصاصها لمحتوى الرسالة المعروض في تطبيق Android

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

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

لقطة شاشة تم اقتصاصها لإشعار ويب يظهر في متصفّح Chrome

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

6- إرسال رسالة حول الموضوع

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

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

للاشتراك في موضوع، يمكنك استدعاء الإجراء messaging.subscribeToTopic في نهاية الوظيفة الرئيسية في ملف main.dart لتطبيق Flutter.

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

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

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

لا يمكن حاليًا استخدام "حزمة تطوير البرامج (SDK) JavaScript لخدمة "المراسلة عبر السحابة الإلكترونية من Firebase" (FCM) مع الاشتراك في المواضيع من جهة العميل. بدلاً من ذلك، يمكنك الاشتراك باستخدام واجهة برمجة تطبيقات إدارة المواضيع من جهة الخادم في "SDK للمشرف". يوضِّح هذا الرمز البرمجي الاشتراك في الموضوع من جهة الخادم باستخدام حزمة تطوير البرامج (SDK) لمشرف Java.

 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());
 }

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

لقطة شاشة تم اقتصاصها لرمز &quot;التشغيل&quot; الذي يظهر بجانب الوظيفة الرئيسية FcmSUBSCRIPTIONManager.java في &quot;استوديو Android&quot;

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

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

  • تُنشئ طلب إرسال مع رسالة أساسية وعنوان "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();. انقر على تشغيل زر التشغيل في &quot;استوديو Android&quot; لإرسال رسالة الموضوع.

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

للتلخيص، تعرّفت على كيفية تطوير التطبيقات المتعدّدة الأنظمة الأساسية باستخدام Flutter وFCM، والتي تتضمّن عملية إعداد البيئة ودمج التبعية وتلقّي الرسائل وإرسالها. لمزيد من التفاصيل، يمكنك الاطّلاع على المواد التالية:

دروس تطبيقية حول الترميز

المراجع