إرسال إشعارات FCM HTTP v1 من خادم Node.js بتوكن OAuth مؤقت وبنية message.topic، مع فحص الاستجابة وحماية بيانات اعتماد الخادم.
ما الفرق بين HTTP v1 والطريقة القديمة؟
واجهة HTTP v1 تستخدم نقطة إرسال مرتبطة بمعرف المشروع وتفويض OAuth قصير العمر. جسم الطلب يبدأ بحقل message ويحدد هدفًا واحدًا مثل fid المسجل أو topic. صيغة to ومفتاح Server Key في أمثلة Legacy القديمة ليستا الصيغة التي يعتمد عليها هذا الدليل. المثال التالي لخادم موثوق باستخدام Node.js يدعم fetch، ولا يوضع داخل تطبيق Flutter أو صفحة ويب متاحة للمستخدم.
إعداد هوية الخادم
فعّل واجهة Firebase Cloud Messaging API للمشروع، وأعط هوية الخادم الصلاحيات المطلوبة للإرسال فقط. تستخدم google-auth-library بيانات Application Default Credentials؛ في بيئة Google المستضافة يمكن إسناد هوية للخدمة، وفي التطوير يمكن ضبط بيانات اعتماد محلية مناسبة. إذا اضطررت لملف حساب خدمة فاحفظه خارج المستودع والمجلد العام، ولا تطبع private_key أو access token. معرف المشروع ليس ملف التهيئة ولا رقم المرسل.
بناء رسالة الموضوع
اسم topic في message.topic يكتب دون البادئة /topics/. اشترك جهاز الاختبار في الاسم نفسه قبل التجربة، واجعل data خريطة قيم نصية. مثال title وbody يعرض تنبيهًا للمستخدم، أما data فيحمل تعليمات مختصرة يمكن التحقق منها داخل التطبيق. الموضوع ليس وسيلة لحصر إشعار حساس في مستخدم معين؛ الاشتراك من العميل ممكن، ولذلك تحتاج الرسائل الخاصة لاستهداف وتفويض على خادمك.
فحص النتائج وإعادة المحاولة
الاستجابة الناجحة تعني قبول الرسالة للإرسال، ولا تضمن أن المستخدم شاهدها. افحص HTTP status والتفاصيل المعادة؛ فرّق بين 401 للتفويض و403 للصلاحيات وبين بيانات طلب غير صالحة. لا تكرر أخطاء التهيئة بلا حد، واستخدم تأخيرًا متزايدًا فقط للأخطاء المؤقتة المناسبة مع احترام تعليمات الخدمة. خزّن معرفًا تجاريًا للحدث عند الحاجة لمنع إرسال النسخة نفسها مرتين بسبب إعادة تنفيذ مهمة الخادم.
المثال التطبيقي وحدوده
import {GoogleAuth} from 'google-auth-library';
const projectId = process.env.FIREBASE_PROJECT_ID;
if (!projectId) throw new Error('Set FIREBASE_PROJECT_ID');
const auth = new GoogleAuth({scopes: ['https://www.googleapis.com/auth/firebase.messaging']});
const client = await auth.getClient();
const {token} = await client.getAccessToken();
if (!token) throw new Error('No OAuth access token');
const response = await fetch(
`https://fcm.googleapis.com/v1/projects/${encodeURIComponent(projectId)}/messages:send`,
{method: 'POST', headers: {Authorization: `Bearer ${token}`, 'Content-Type': 'application/json'},
body: JSON.stringify({message: {topic: 'news', notification: {title: 'تحديث', body: 'مقال جديد'}, data: {screen: 'news'}}})}
);
const result = await response.json();
if (!response.ok) throw new Error(`FCM failed: ${response.status}`);
console.log(result.name);






