إعداد Firebase Cloud Messaging

إعداد Firebase Cloud Messaging

Firebase Cloud Messaging (FCM) هو حل مراسلة مجاني متعدد المنصات من Google يتيح لك إرسال الإشعارات ورسائل البيانات بشكل موثوق إلى تطبيقات Android وiOS والويب. في Flutter، تُغلّف حزمة firebase_messaging حزم FCM الأصلية وتوفر واجهة برمجية موحدة بلغة Dart. قبل أن يتمكن تطبيقك من استقبال أي إشعار دفع، يجب استيفاء ثلاثة متطلبات أساسية: تسجيل التطبيق في لوحة تحكم Firebase، تنزيل ملف الإعداد الخاص بكل منصة، وإضافة تبعيات Dart الأصلية الصحيحة.

الخطوة 1 — إنشاء مشروع Firebase

انتقل إلى console.firebase.google.com وسجّل الدخول بحساب Google. انقر على Add project، امنحه اسمًا واضحًا (مثل my-flutter-app)، مكّن Google Analytics اختياريًا، ثم انقر Create project. بعد اكتمال الإنشاء، ستصل إلى لوحة تحكم المشروع حيث يمكنك تسجيل تطبيقات المنصات الفردية.

الخطوة 2 — تسجيل تطبيق Android

على لوحة تحكم المشروع انقر على أيقونة Android. ستُطلب منك اسم حزمة Android — يجب أن يطابق قيمة applicationId الموجودة في android/app/build.gradle تمامًا (مثل com.example.myflutterapp). بعد التأكيد، تُنشئ Firebase ملف google-services.json. نزّله وضعه داخل مشروع Flutter في:

android/app/google-services.json

بعد ذلك، طبّق إضافة Google Services Gradle. افتح android/build.gradle (على مستوى المشروع) وأضف تبعية classpath، ثم افتح android/app/build.gradle (على مستوى التطبيق) وطبّق الإضافة:

buildscript {
    dependencies {
        // أضف هذا السطر
        classpath 'com.google.gms:google-services:4.4.1'
    }
}

// طبّق إضافة Google Services أخيرًا
apply plugin: 'com.google.gms.google-services'

الخطوة 3 — تسجيل تطبيق iOS

عد إلى لوحة تحكم Firebase وانقر على أيقونة iOS. أدخل Bundle ID الخاص بـ iOS — يجب أن يطابق القيمة في ios/Runner.xcodeproj/project.pbxproj (مثل com.example.myFlutterApp). تُنشئ Firebase ملف GoogleService-Info.plist. نزّله وأضفه للمشروع عبر Xcode (وليس Finder فقط) لضمان تضمينه في هدف البناء:

1. افتح ios/Runner.xcworkspace في Xcode.
2. انقر بالزر الأيمن على مجلد Runner في متصفح المشروع.
3. اختر Add Files to "Runner" وحدد ملف GoogleService-Info.plist.
4. تأكد من تفعيل Copy items if needed وتحديد هدف Runner.

الخطوة 4 — إضافة حزمة firebase_messaging

بعد وضع ملفات الإعداد الأصلية، ثبّت حزم Dart. نفّذ الأوامر التالية من جذر مشروع Flutter:

# أضف إضافة FlutterFire الأساسية وإضافة المراسلة
flutter pub add firebase_core
flutter pub add firebase_messaging

يؤدي هذا إلى تحديث pubspec.yaml وجلب الحزم. يمكنك أيضًا إضافتها يدويًا إلى pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  firebase_core: ^3.6.0
  firebase_messaging: ^15.1.3

الخطوة 5 — تهيئة Firebase في main.dart

يجب تهيئة Firebase قبل استخدام أي خدمة Firebase أخرى. نقطة البداية هي دالة main(). نظرًا لأن التهيئة غير متزامنة، يجب جعل main() دالة async وانتظار النتيجة قبل استدعاء runApp():

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_messaging/firebase_messaging.dart';
import 'package:flutter/material.dart';

// معالج رسائل الخلفية على المستوى الأعلى (يجب أن يكون على مستوى أعلى، وليس method)
@pragma('vm:entry-point')
Future<void> _firebaseMessagingBackgroundHandler(RemoteMessage message) async {
  // يجب إعادة تهيئة Firebase في الـ isolate الخلفي
  await Firebase.initializeApp();
  print('تم استقبال رسالة خلفية: ${message.messageId}');
}

Future<void> main() async {
  // تأكد من جاهزية ربط Flutter قبل استدعاء الكود الأصلي
  WidgetsFlutterBinding.ensureInitialized();

  // تهيئة Firebase
  await Firebase.initializeApp();

  // تسجيل معالج رسائل الخلفية
  FirebaseMessaging.onBackgroundMessage(_firebaseMessagingBackgroundHandler);

  runApp(const MyApp());
}

الخطوة 6 — طلب أذونات الإشعارات (iOS وAndroid 13+)

في Android 13 وما بعده وجميع إصدارات iOS، يجب طلب الإذن صراحةً قبل عرض الإشعارات. يوفر كائن FirebaseMessaging دالة requestPermission():

Future<void> requestNotificationPermissions() async {
  final messaging = FirebaseMessaging.instance;

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

  if (settings.authorizationStatus == AuthorizationStatus.authorized) {
    print('منح المستخدم إذن الإشعارات');
  } else if (settings.authorizationStatus == AuthorizationStatus.provisional) {
    print('منح المستخدم إذنًا مؤقتًا');
  } else {
    print('رفض المستخدم أو لم يقبل الإذن بعد');
  }
}

ملخص

لإعداد FCM في مشروع Flutter يجب: (1) إنشاء مشروع Firebase في اللوحة، (2) تسجيل تطبيق كل منصة وتنزيل ملف الإعداد (google-services.json لـ Android وGoogleService-Info.plist لـ iOS)، (3) تطبيق إضافة Google Services Gradle لـ Android وإضافة plist عبر Xcode لـ iOS، (4) إضافة firebase_core وfirebase_messaging إلى pubspec.yaml، (5) تهيئة Firebase قبل runApp()، و(6) تسجيل معالج رسائل خلفية على المستوى الأعلى. بمجرد تجهيز هذا الهيكل، يصبح تطبيقك جاهزًا لاستقبال إشعارات الدفع والاستجابة لها.