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

1. مقدمة

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

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

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

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

ما ستتعلمه

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

المتطلبات

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

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

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

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

2. إعداد Flutter

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

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

1. نزِّل Flutter وثبِّته لنظام التشغيل: التثبيت | 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.

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

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

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

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

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

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

3- إعداد Firebase وFlutterFire

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

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

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

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

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

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

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

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

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

إعداد Firebase CLI

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

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

firebase login

إعداد 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=fcm4flutter. استخدِم مفاتيح الأسهم ومفتاح المسافة لاختيار المنصات أو اضغط على 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، انتقِل إلى إعدادات المشروع واختَر علامة التبويب Cloud Messaging.

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

 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 Studio، انقر على Chrome (web) من أداة اختيار الهدف، ثم شغِّل التطبيق مرة أخرى.

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

التسجيل

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

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

ملاحظة: إذا واجهت الخطأ التالي، اتّبِع التعليمات الواردة بعد رسالة الخطأ وحدِّد قيمة أعلى لـ minSdkVersion (مثلاً ‫19) في ملف 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: "...",
 databaseURL: "...",
 projectId: "...",
 storageBucket: "...",
 messagingSenderId: "...",
 appId: "...",
};

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

// todo Set up background message handler

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

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

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

تهانينا، لقد سجّلت تطبيقك بنجاح في خدمة 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 أن يتضمّن طلب إرسال رسالة سلوكيات مختلفة على أنظمة أساسية مختلفة. من حالات استخدام هذه الميزة عرض محتوى مختلف لرسالة الإشعار استنادًا إلى المنصة. يتم استخدام الميزة بشكل كامل عند استهداف أجهزة متعددة (قد تشمل منصات متعددة) باستخدام رسائل المواضيع. يوضّح لك هذا القسم الخطوات اللازمة لجعل تطبيقك يتلقّى رسالة موضوع مخصّصة لكل نظام أساسي.

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

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

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

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

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

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

 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:

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

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

• يمكنك إنشاء طلب إرسال يتضمّن رسالة أساسية وعنوانًا "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 وFCM، ويشمل ذلك إعداد البيئة ودمج التبعيات وتلقّي الرسائل وإرسالها. لمزيد من التفاصيل، يُرجى الاطّلاع على المواد التالية:

Codelabs

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

المراجع

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