NahdaAIنهضة
Firebase & Supabase • المستوى الرابع • الدرس 2

الإشعارات الفورية والتنبيهات (Firebase Cloud Messaging - FCM)

العودة لفهرس المستوى

أهداف الدرس العلمية

  • فهم آلية عمل Push Notifications في الويب والجوال.
  • طلب إذن المستخدم والحصول على FCM Token.
  • الاستماع للإشعارات في المقدمة والخلفية.
  • حفظ Token في Firestore وإرسال إشعارات مخصصة.

1. ما هو Firebase Cloud Messaging (FCM)؟

FCM هي خدمة مجانية من Google لإرسال إشعارات Push إلى تطبيقات الويب، Android، و iOS. تتيح لك الوصول للمستخدمين حتى لو كان التطبيق مغلقاً.

Foreground Messages

إشعارات تظهر أثناء فتح الصفحة.

تُستقبل عبر onMessage()

Background Messages

إشعارات تظهر حتى لو كانت الصفحة مغلقة.

تُعالَج عبر Service Worker

2. خطوات الإعداد الكاملة

  1. إنشاء مشروع في Firebase Console.
  2. إضافة تطبيق ويب (Web App) والحصول على firebaseConfig.
  3. توليد VAPID Key من Project Settings → Cloud Messaging.
  4. إنشاء ملف firebase-messaging-sw.js في مجلد public/.
  5. طلب إذن المستخدم والحصول على Token.
javascript
// public/firebase-messaging-sw.js
importScripts('https://www.gstatic.com/firebasejs/10.0.0/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.0.0/firebase-messaging-compat.js');

firebase.initializeApp({
  apiKey: "YOUR_API_KEY",
  projectId: "your-app",
  messagingSenderId: "123456789",
  appId: "1:123:web:abc"
});

const messaging = firebase.messaging();

// استقبال الإشعارات في الخلفية
messaging.onBackgroundMessage((payload) => {
  console.log('[SW] إشعار في الخلفية:', payload);

  const notificationTitle = payload.notification?.title || "إشعار جديد";
  const notificationOptions = {
    body: payload.notification?.body,
    icon: '/icon-192.png',
    data: payload.data
  };

  self.registration.showNotification(notificationTitle, notificationOptions);
});

// معالجة النقر على الإشعار
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  event.waitUntil(clients.openWindow('/'));
});

3. أنواع الإشعارات

Notification Message

إشعار بسيط (عنوان + محتوى).

{
  notification: {
    title: 'رسالة جديدة',
    body: 'لديك رسالة من أحمد'
  }
}
Data Message

بيانات مخصصة (بدون إشعار تلقائي).

{
  data: {
    type: 'chat',
    roomId: 'room-1'
  }
}

4. إرسال الإشعارات (من Cloud Function)

الطريقة الاحترافية: أرسل الإشعارات من Cloud Function عند حدوث حدث معين:

javascript
// functions/index.js
import { onDocumentCreated } from "firebase-functions/v2/firestore";
import { getMessaging } from "firebase-admin/messaging";
import { initializeApp } from "firebase-admin/app";

initializeApp();

export const sendChatNotification = onDocumentCreated(
  "messages/{messageId}",
  async (event) => {
    const message = event.data.data();
    const recipientToken = message.recipientFCMToken;

    if (!recipientToken) return;

    try {
      await getMessaging().send({
        token: recipientToken,
        notification: {
          title: "رسالة جديدة",
          body: message.content
        },
        data: {
          type: "chat",
          roomId: message.roomId
        }
      });
      console.log("✓ تم إرسال الإشعار");
    } catch (error) {
      console.error("خطأ:", error);
    }
  }
);

5. أفضل الممارسات

افعل
  • • تحقق من isSupported() أولاً
  • • احفظ Token في Firestore
  • • احذف Token عند تسجيل الخروج
  • • استخدم Topics للإشعارات الجماعية
تجنّب
  • • طلب الإذن مباشرة عند فتح الصفحة
  • • إرسال إشعارات بدون إذن
  • • نسيان إلغاء الاشتراك
  • • إرسال إشعارات متكررة مزعجة
التطبيق العملي المباشر

تحدي الدرس الثاني: بناء نظام إشعارات كامل

قم بالتعديل على الكود بداخل المحرر أدناه لتطبيق المتطلبات التالية:

  1. احتفظ بدالة requestNotificationPermission و getFCMToken.
  2. أضف دالة checkSupport تستخدم isSupported().
  3. أضف دالة saveTokenToFirestore تحفظ Token في Firestore.
  4. أضف دالة listenToForegroundMessages تستخدم onMessage.
  5. أضف دالة removeFCMToken تستخدم deleteToken.
  6. أضف دالة registerForNotifications تجمع كل شيء.
⏳ جارٍ التحميل...