محتوى مموّل
جروب فيسبوك
انضم الي جروب مجتمع مبرمجي المستقبل
انضم الان
JOURNAL INDEX
إشعارات الويب في Laravel مع Firebase: دليل عملي من الاشتراك حتى وصول الإشعار
عبدالرحمن ربيع
Software Engineer & AI Builder
شرح عملي لبناء نظام إشعارات ويب في Laravel باستخدام Firebase Cloud Messaging: تسجيل Service Worker، توليد التوكن، تخزين الأجهزة، وإرسال الإشعار بلغة الجهاز.
الإشعارات الفورية (Web Push) بقت من أسرع الطرق لإرجاع الزائر لموقعك من غير بريد ولا إعلانات مدفوعة. في الدليل ده هنبني نظام إشعارات كامل على Laravel باستخدام Firebase Cloud Messaging، من لحظة ما الزائر يضغط «سماح» لحد ما يوصله إشعار بلغة جهازه.
1. ليه Firebase Cloud Messaging تحديدًا؟
معيار Push API نفسه مدعوم في المتصفحات الحديثة، لكن كل متصفح بيتكلم مع خادم دفع مختلف. Firebase Cloud Messaging بيعمل طبقة واحدة فوق دول كلهم، فبتبعت رسالة واحدة وهو بيوصلها لكروم وفايرفوكس وسفاري وأندرويد.
2. تجهيز مشروع Firebase
- من Firebase Console ← إعدادات المشروع ← General تجيب
Project IDوWeb API KeyوApp ID. - من تبويب Cloud Messaging ← Web Push certificates تولّد زوج مفاتيح وتاخد مفتاح VAPID العام.
- من تبويب Service accounts تولّد مفتاح خاص (ملف JSON) — ده اللي السيرفر هيوقّع بيه طلبات الإرسال.
الملف ده سرّي تمامًا: خزّنه خارج مجلد public ومتحطّوش في مستودع الكود.
3. Service Worker في جذر الموقع
المتصفح مش هيستقبل أي إشعار من غير Service Worker مسجَّل على نطاق الموقع. الملف لازم يكون في الجذر (/firebase-messaging-sw.js) عشان يغطي كل الصفحات:
importScripts('https://www.gstatic.com/firebasejs/10.12.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.12.2/firebase-messaging-compat.js');
firebase.initializeApp({ apiKey: '...', projectId: '...', appId: '...', messagingSenderId: '...' });
firebase.messaging();4. طلب الإذن وتوليد التوكن
أهم قاعدة في تجربة المستخدم: متطلبش الإذن أول ما الصفحة تفتح. استنى الزائر يتفاعل، أو اعرض بطاقة تشرح فايدة الإشعار قبل نافذة المتصفح — ده اللي web.dev بيوصي بيه لتقليل نسبة الرفض.
const token = await getToken(messaging, { vapidKey: VAPID_PUBLIC_KEY });
await fetch('/push/subscribe', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrf },
body: JSON.stringify({ token, lang: (navigator.language || 'en').startsWith('ar') ? 'ar' : 'en' }),
});5. تخزين الأجهزة في Laravel
خزّن مع كل توكن: لغة الجهاز، تاريخ الاشتراك، ونوع المتصفح. اللغة هي المفتاح اللي هيخليك تبعت نسخة عربية للأجهزة العربية ونسخة إنجليزية لغيرها بدل رسالة واحدة مترجمة نص ترجمة.
6. الإرسال من السيرفر عبر HTTP v1
واجهة FCM HTTP v1 بتاخد توكن وصول موقّع من ملف حساب الخدمة، وبتتوقع شكل رسالة محدد بدقة: حقل notification للعنوان والنص، وحقل webpush.fcm_options.link للرابط، والأيقونة جوه webpush.notification. أي حقل في المكان الغلط بيرجّع خطأ Invalid JSON payload.
POST https://fcm.googleapis.com/v1/projects/{project}/messages:send
{
"message": {
"token": "...",
"notification": { "title": "مقال جديد", "body": "..." },
"webpush": {
"notification": { "icon": "https://example.com/icon.png" },
"fcm_options": { "link": "https://example.com/blog/slug" }
}
}
}7. الإرسال التلقائي عند النشر
اربط الإرسال بحدث النموذج في AppServiceProvider: عند created أو عند تحوّل الحالة إلى «منشور»، ابعت الإشعار مع رابط المقال وصورة مشاركة 1200×630 مولّدة من الغلاف. خلّي الإرسال داخل try/catch عشان فشل الإشعار ما يوقفش عملية الحفظ أبدًا.
8. نقاط تُنسى كثيرًا
- نظّف التوكنات الميتة: أي توكن يرجّع
UNREGISTEREDاحذفه فورًا. - iOS بيدعم إشعارات الويب فقط لو الموقع متضاف للشاشة الرئيسية كـ PWA.
- الموقع لازم يشتغل على HTTPS — من غير كده الـ Service Worker مش هيتسجّل أصلًا.
- راجع سياسات المحتوى في Google Search Essentials لو بتبعت إشعارات ترويجية متكررة.
الخلاصة
نظام إشعارات صحّي بيتكوّن من أربع قطع: Service Worker مسجّل، توكن مخزّن مع لغة الجهاز، رسالة مطابقة لمواصفات FCM، وسبب حقيقي يخلي الزائر يقبل الإذن. لو القطع الأربعة مظبوطة، الإشعار بيوصل للجوال في أقل من ثانية من لحظة نشر المقال.
الإشعارات الفورية (Web Push) بقت من أسرع الطرق لإرجاع الزائر لموقعك من غير بريد ولا إعلانات مدفوعة. في الدليل ده هنبني نظام إشعارات كامل على Laravel باستخدام Firebase Cloud Messaging، من لحظة ما الزائر يضغط «سماح» لحد ما يوصله إشعار بلغة جهازه.
1. ليه Firebase Cloud Messaging تحديدًا؟
معيار Push API نفسه مدعوم في المتصفحات الحديثة، لكن كل متصفح بيتكلم مع خادم دفع مختلف. Firebase Cloud Messaging بيعمل طبقة واحدة فوق دول كلهم، فبتبعت رسالة واحدة وهو بيوصلها لكروم وفايرفوكس وسفاري وأندرويد.
2. تجهيز مشروع Firebase
- من Firebase Console ← إعدادات المشروع ← General تجيب
Project IDوWeb API KeyوApp ID. - من تبويب Cloud Messaging ← Web Push certificates تولّد زوج مفاتيح وتاخد مفتاح VAPID العام.
- من تبويب Service accounts تولّد مفتاح خاص (ملف JSON) — ده اللي السيرفر هيوقّع بيه طلبات الإرسال.
الملف ده سرّي تمامًا: خزّنه خارج مجلد public ومتحطّوش في مستودع الكود.
3. Service Worker في جذر الموقع
المتصفح مش هيستقبل أي إشعار من غير Service Worker مسجَّل على نطاق الموقع. الملف لازم يكون في الجذر (/firebase-messaging-sw.js) عشان يغطي كل الصفحات:
importScripts('https://www.gstatic.com/firebasejs/10.12.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.12.2/firebase-messaging-compat.js');
firebase.initializeApp({ apiKey: '...', projectId: '...', appId: '...', messagingSenderId: '...' });
firebase.messaging();4. طلب الإذن وتوليد التوكن
أهم قاعدة في تجربة المستخدم: متطلبش الإذن أول ما الصفحة تفتح. استنى الزائر يتفاعل، أو اعرض بطاقة تشرح فايدة الإشعار قبل نافذة المتصفح — ده اللي web.dev بيوصي بيه لتقليل نسبة الرفض.
const token = await getToken(messaging, { vapidKey: VAPID_PUBLIC_KEY });
await fetch('/push/subscribe', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': csrf },
body: JSON.stringify({ token, lang: (navigator.language || 'en').startsWith('ar') ? 'ar' : 'en' }),
});5. تخزين الأجهزة في Laravel
خزّن مع كل توكن: لغة الجهاز، تاريخ الاشتراك، ونوع المتصفح. اللغة هي المفتاح اللي هيخليك تبعت نسخة عربية للأجهزة العربية ونسخة إنجليزية لغيرها بدل رسالة واحدة مترجمة نص ترجمة.
6. الإرسال من السيرفر عبر HTTP v1
واجهة FCM HTTP v1 بتاخد توكن وصول موقّع من ملف حساب الخدمة، وبتتوقع شكل رسالة محدد بدقة: حقل notification للعنوان والنص، وحقل webpush.fcm_options.link للرابط، والأيقونة جوه webpush.notification. أي حقل في المكان الغلط بيرجّع خطأ Invalid JSON payload.
POST https://fcm.googleapis.com/v1/projects/{project}/messages:send
{
"message": {
"token": "...",
"notification": { "title": "مقال جديد", "body": "..." },
"webpush": {
"notification": { "icon": "https://example.com/icon.png" },
"fcm_options": { "link": "https://example.com/blog/slug" }
}
}
}7. الإرسال التلقائي عند النشر
اربط الإرسال بحدث النموذج في AppServiceProvider: عند created أو عند تحوّل الحالة إلى «منشور»، ابعت الإشعار مع رابط المقال وصورة مشاركة 1200×630 مولّدة من الغلاف. خلّي الإرسال داخل try/catch عشان فشل الإشعار ما يوقفش عملية الحفظ أبدًا.
8. نقاط تُنسى كثيرًا
- نظّف التوكنات الميتة: أي توكن يرجّع
UNREGISTEREDاحذفه فورًا. - iOS بيدعم إشعارات الويب فقط لو الموقع متضاف للشاشة الرئيسية كـ PWA.
- الموقع لازم يشتغل على HTTPS — من غير كده الـ Service Worker مش هيتسجّل أصلًا.
- راجع سياسات المحتوى في Google Search Essentials لو بتبعت إشعارات ترويجية متكررة.
الخلاصة
نظام إشعارات صحّي بيتكوّن من أربع قطع: Service Worker مسجّل، توكن مخزّن مع لغة الجهاز، رسالة مطابقة لمواصفات FCM، وسبب حقيقي يخلي الزائر يقبل الإذن. لو القطع الأربعة مظبوطة، الإشعار بيوصل للجوال في أقل من ثانية من لحظة نشر المقال.
كتبه
عبدالرحمن ربيع
Software Engineer & AI Builder
مطور برمجيات متكامل ومصمم جرافيك مع أكثر من 4 سنوات خبرة في بناء تطبيقات الويب الحديثة باستخدام PHP و JavaScript و HTML و CSS. خلفية قوية في تصميم UI/UX واستخدام متقدم لأدوات الذكاء الاصطناعي لتعزيز كفاءة التطوير والأتمتة واتخاذ القرارات. حاصل على ماجستير تنفي...
وسوم المقال
مصادر وروابط خارجية
RELATED / READ NEXT
كل المقالات
مقالات ذات صلة
2026.09.20 · 5 VIEWS
إيرادات OpenAI وAnthropic تتفوق بـ 10 أضعاف على جميع نماذج الذكاء الاصطناعي الصينية مجتمعة
اقرأ المقال
2026.09.20 · 10 VIEWS
5 Prompt Optimization Strategies That Actually Improve LLM Output
اقرأ المقال
2026.09.19 · 9 VIEWS
هل ما زالت لغة PHP حية؟ (حرق: نعم!)
اقرأ المقال
2026.09.19 · 10 VIEWS
التعليقات (0)
كن أول من يعلّق على هذا المقال.