الحوسبة السحابية وبدائلها الأدلة التقنية

إشعارات المتصفح Web Push وVAPID دون خدمة خارجية

كيف تطلب إذن الإشعارات في اللحظة الصحيحة، وتشفر الرسالة وتوقعها بيدك بحسب RFC 8291 وRFC 8292، وتعرف متى يموت الاشتراك حتى حين ترد الخدمة بالقبول.

إشعارات المتصفح Web Push وVAPID دون خدمة خارجية

لديك موقع متجر أو لوحة تحكم Dashboard أو تطبيق ويب داخلي، وتريد أن يصل المستخدم إشعار عندما يخرج طلبه للتوصيل أو عندما تصدر فاتورته، والطريق المعتاد أن تضيف سطراً من خدمة إشعارات تجارية مثل OneSignal أو مكتبة Firebase، فتصبح قائمة مشتركيك وتوقيت كل إشعار ومحتواه عند طرف ثالث. وفي مقال كيف تعمل الإشعارات الفورية Push Notifications شرحنا المعيار المفتوح Web Push والأطراف الثلاثة فيه، وفي إشعارات Push بدون Firebase أرسلنا أول رسالة بمفاتيح VAPID خاصة بنا عبر مكتبة web-push، وعرفنا أن خدمة الإشعارات Push Service نفسها يختارها المتصفح ولا تختارها أنت. لذلك فهذا المقال لا يعيد الأساسيات، وإنما ينزل طبقة تحت المكتبة: ماذا تفعل الصفحة قبل أن تطلب الإذن، وماذا يحدث داخل ال Service Worker، وكيف تشفر الرسالة بيدك سطراً سطراً، وما الذي تعنيه كل ترويسة Header وكل رد Response تعيده الخدمة، ومتى يموت الاشتراك دون أن يخبرك أحد.

والعنوان «دون خدمة خارجية» يعني هنا شيئاً محدداً: لا توجد خدمة إشعارات تجارية بينك وبين المتصفح، ولا مشروع Firebase، ولا مكتبة جاهزة، فكل ما يخرج من سيرفرك كتبته أنت بوحدة node:crypto في Node.js. أما خدمة المتصفح نفسها، أي خدمة Google في Chrome وخدمة Mozilla في Firefox وخدمة Apple في Safari، فهي جزء من المتصفح ولا يمكن أن تخرج من الطريق، وهذا ما بيناه بالتفصيل في المقالين السابقين. وسوف نناقش في هذا المقال ما يلي:

  • حالات الإذن Permission الثلاث، ولماذا يخسر الموقع المستخدم إلى الأبد إذا طلب الإذن في اللحظة الخطأ، ونمط السؤال التمهيدي Soft Prompt بتجربة على هاتف Android حقيقي في المحاكي Emulator.
  • ال Service Worker من الداخل: حدث push، وwaitUntil، وخيارات الإشعار، والنقر عليه، ووعد userVisibleOnly.
  • تشفير الرسالة بحسب RFC 8291 وتوقيع VAPID بحسب RFC 8292 بكود مكتوب يدوياً، ثم التحقق منه في Chrome وFirefox، وماذا يحدث إذا أخطأت في بايت واحد.
  • الترويسات TTL وUrgency وTopic في تجربة حقيقية: هاتف يدخل وضع الطيران، وخمس رسائل تصل منها اثنتان.
  • دورة حياة الاشتراك Subscription Lifecycle، ورموز الرد Status Codes، وتنظيف الاشتراكات الميتة، والحالة التي لا يصل فيها أي خطأ إلى سيرفرك.
  • Safari على iPhone وiPad: شرط الشاشة الرئيسية Home Screen، وDeclarative Web Push، من توثيق WebKit.

ما الذي تملكه أنت في Web Push؟ What You Own

قبل أن ندخل في التفاصيل لنحدد الحدود بدقة، لأن كثيراً من القرارات في هذا المقال تتبع منها. في Web Push ثلاثة أطراف: الصفحة وال Service Worker داخل المتصفح، وخدمة الإشعارات التي يملكها صانع المتصفح، وسيرفر التطبيق Application Server الذي تملكه أنت. والمعيار المفتوح يجعل الحد بين الأطراف واضحاً، فأنت تملك ثلاثة أشياء كاملة:

  • اللحظة التي يطلب فيها الإذن وطريقة طلبه: وهذه أهم قرار في تجربة المستخدم User Experience، لأن الرفض لا رجوع عنه إلا بيد المستخدم نفسه.
  • محتوى الرسالة وتشفيرها: فالرسالة تخرج من سيرفرك مشفرة بمفتاح لا يملكه إلا المتصفح، وخدمة الإشعارات تنقل بايتات لا تقرؤها.
  • جدول الاشتراكات Subscriptions وقرار حذف كل صف فيه: فلا أحد يحفظ قائمة مشتركيك غيرك، ولا أحد ينظفها لك.

وما لا تملكه هو الخدمة التي تحفظ الرسالة حتى يتصل الجهاز، وتوقيت إيقاظه، وسياسة البطارية في نظام التشغيل. وهذا هو الفرق بين الحل الذي نبنيه هنا وبين خدمة مثل OneSignal، ففي الخدمة التجارية يمر المحتوى بحسابك عندهم قبل أن يشفر، ويحفظون هم جدول الاشتراكات، أما هنا فالخدمة التي في الطريق هي خدمة المتصفح وحدها، وهي موجودة في كل الحالات.

والصورة التالية تبين دورة الحياة التي سوف نمشي عليها في المقال كله، من أول زيارة إلى لحظة حذف الاشتراك من قاعدة بياناتك Database:

مخطط من صفين: في الأعلى أربعة مربعات متتالية، الإذن default ثم سؤال تمهيدي من صفحتك ثم نافذة المتصفح بعد ضغطة المستخدم ثم granted وsubscribe وإرسال الاشتراك إلى السيرفر، وتحتها مربع أحمر denied لا رجوع إلا بيد المستخدم ومربع جدول الاشتراكات في السيرفر، وفي الصف الأسفل أربع طرق ينتهي بها الاشتراك: المتصفح غير الاشتراك pushsubscriptionchange، والمستخدم ألغى، والخدمة ترد 404 أو 410، ولا يصل شيء ولا يظهر خطأ لأن ملف المتصفح حذف
أربعة طرق ينتهي بها الاشتراك، واثنان منها لا يخبران سيرفرك بشيء

المختبر: سيرفر تطبيق وثلاثة متصفحات Lab Setup

كل ما في هذا المقال مبني على تجربة واحدة: سيرفر تطبيق ب Node.js 24.21.0 داخل Container من node:24-alpine على المنفذ 127.0.0.1:28961، ومعه صفحة متجر تجريبية وملف Service Worker، والإرسال كله بملف webpush-raw.mjs الذي كتبناه بوحدة node:crypto فقط. وفتحنا الصفحة في ثلاثة متصفحات: Google Chrome 157 على جهاز Windows في الوضع الخفي Headless نقوده عبر بروتوكول DevTools، وFirefox 157 من حزمة Playwright 1.64.0 داخل Container، وChrome 124 على Android 15 في محاكي Android Emulator، مع تحويل المنفذ إلى الهاتف بالأمر adb reverse. والسبب في استخدام العنوان localhost وليس عنوان IP أن Web Push لا يعمل إلا في السياق الآمن Secure Context، أي HTTPS أو localhost، والأمر adb reverse يجعل 127.0.0.1 على الهاتف يشير إلى جهازك:

docker run -d --name lab-wp-app -p 127.0.0.1:28961:8080 -v "$PWD:/app" -w /app node:24-alpine node server.mjs
adb -s emulator-5600 reverse tcp:28961 tcp:28961
adb -s emulator-5600 shell am start -a android.intent.action.VIEW -d http://127.0.0.1:28961/ com.android.chrome
app server on :8080, VAPID public key BFArSyvuS9Lw0KBX…

والسيرفر يولد زوج مفاتيح VAPID مرة واحدة ويحفظه في data/vapid.json، ويحفظ الاشتراكات في data/subs.json، وفي تطبيق حقيقي يكون هذا جدولاً في قاعدة البيانات كالذي صممناه في جدول الاشتراكات.

الإذن أولاً: تجربة المستخدم مع الإذن Permission UX

الإذن في Notifications API له ثلاث قيم فقط تقرؤها من Notification.permission: القيمة default تعني أن الموقع لم يسأل بعد، وgranted أن المستخدم وافق، وdenied أنه رفض. والقيمة الأخيرة هي المشكلة، فإذا رفض المستخدم مرة واحدة لا يستطيع موقعك أن يسأله مرة ثانية أبداً، فأي استدعاء بعدها للدالة requestPermission() يعود فوراً ب denied دون أن يظهر شيء، والطريق الوحيد للرجوع أن يفتح المستخدم إعدادات الموقع في المتصفح ويغيرها بيده، وأغلب الناس لا يفعلون ذلك.

وقد يتساءل البعض: إذن لماذا لا نطلب الإذن عند أول زيارة ونرتاح؟ والإجابة أن هذا بالضبط ما جعل المتصفحات تقيد الطلب، فالمواقع التي تطلب الإذن قبل أن يعرف الزائر ماذا سيصله تحصل على رفض أكثر بكثير من الموافقة، والمتصفحات ردت على ذلك: Firefox منذ الإصدار 72 لا يعرض نافذة الإذن إلا إذا جاء الطلب من تفاعل للمستخدم مثل الضغط على زر، وChrome أضاف واجهة هادئة Quieter Permission UI تخفي الطلب في شريط العنوان للمواقع التي يرفضها أغلب زوارها، وSafari على iPhone لا يقبل الطلب إلا بعد ضغطة كما سوف نرى في قسم Safari.

السؤال التمهيدي Soft Prompt

الحل الأنسب هو السؤال التمهيدي: بدل أن تستدعي نافذة المتصفح مباشرة، تعرض صفحتك سؤالاً من تصميمها في اللحظة التي يكون فيها للإشعار معنى واضح، مثل صفحة الطلب بعد الدفع، وتشرح فيه ما الذي سوف يصله بالضبط، ولا تستدعي requestPermission() إلا إذا ضغط الزائر «نعم». فإذا ضغط «ليس الآن» لم تخسر شيئاً، لأن الإذن بقي default وتستطيع أن تسأله مرة أخرى في لحظة أنسب. والكود التالي من صفحة المختبر يفعل ذلك:

<div class="card">
  <h1>طلبك رقم 1042 قيد التجهيز</h1>
  <p>هل تريد أن نخبرك عندما يخرج طلبك للتوصيل؟ سوف نرسل لك إشعاراً واحداً لكل تغيير في حالة الطلب فقط.</p>
  <button class="yes" id="yes">نعم، أخبرني</button><button class="later" id="later">ليس الآن</button>
</div>
<script>
// the real permission prompt only after a click on our own button (the soft prompt)
window.subscribe = async () => {
  const reg = await navigator.serviceWorker.register('/sw.js'); await navigator.serviceWorker.ready
  if (Notification.permission === 'default' && await Notification.requestPermission() !== 'granted') { await show(); return 'not granted' }
  const { publicKey } = await (await fetch('/vapid')).json()
  const sub = await reg.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: publicKey })
  await fetch('/subscribe', { method: 'POST', body: JSON.stringify({ sub }) })
  await show(); return sub.endpoint
}
document.getElementById('yes').onclick = () => window.subscribe()
document.getElementById('later').onclick = () => document.querySelector('.card').remove()
</script>

في الكود أعلاه لاحظ التالي:

  • الاستدعاء requestPermission() داخل معالج النقر Click Handler مباشرة، فالمتصفح يعرف أن الطلب جاء من فعل المستخدم، وهذا شرط Firefox وSafari، ويحسب له Chrome عند تقييم الموقع.
  • الزر «ليس الآن» يخفي البطاقة فقط ولا يلمس الإذن، فيبقى الطريق مفتوحاً.
  • المفتاح العام لسيرفرك applicationServerKey يأتي من السيرفر في كل مرة، فإذا غيرته يوماً تعرف الصفحة المفتاح الجديد، ولا تكتبه ثابتاً في كود الواجهة.
  • الصفحة تعرض حالة الإذن والاشتراك في صندوق أسفلها، وهذا للمختبر فقط حتى نرى ما يحدث.

والصورة التالية من Chrome على Android في المحاكي: على اليمين السؤال التمهيدي من صفحتنا والإذن ما زال default، وعلى اليسار نافذة المتصفح التي ظهرت بعد الضغط على «نعم، أخبرني»:

لقطتان من Chrome على Android: الأولى صفحة متجر المثال وفيها بطاقة طلبك رقم 1042 قيد التجهيز وسؤال هل تريد أن نخبرك عندما يخرج طلبك للتوصيل مع زري نعم أخبرني وليس الآن، وتحتها صندوق أسود يعرض Notification.permission = default وservice worker = none وsubscription = none، والثانية الصفحة نفسها معتمة وفوقها نافذة المتصفح http://127.0.0.1:28961 wants to send you notifications مع زري Block وAllow
نافذة المتصفح لا تظهر إلا بعد أن يختار الزائر «نعم» في سؤالنا

ولاحظنا في المحاكي شيئاً يستحق الذكر: عندما فتحنا Chrome لأول مرة عرض هو نفسه سؤالاً تمهيدياً من تصميمه «Chrome notifications make things easier» قبل نافذة نظام Android التي تسأل «Allow Chrome to send you notifications?»، أي أن المتصفح يطبق النمط نفسه على نظام التشغيل. فعلى Android 13 وما بعده هناك طبقتان من الإذن: إذن النظام للمتصفح كله، وهو الإذن POST_NOTIFICATIONS الذي شرحناه في الروابط العميقة والإشعارات، ثم إذن موقعك داخل المتصفح، فإذا رفض المستخدم الأول لا يصل أي إشعار من أي موقع مهما كان إذن موقعك.

ماذا يحدث عندما يرفض المستخدم؟ Permission States

شغلنا سكربتاً يقود Chrome 157 على ملف تعريف Profile جديد، ويمر على الحالات واحدة واحدة، والمخرج سوف يكون كما يلي:

chrome Chrome/157.0.8103.79
1 permission at start          -> default
2 requestPermission, no click  -> denied
3 permission after             -> denied
4 user blocked, subscribe      -> THROWS NotAllowedError: Registration failed - permission denied
5 requestPermission when denied -> denied
6 userVisibleOnly: false       -> THROWS NotAllowedError: Registration failed - permission denied
7 subscribe (our key)          -> https://fcm.googleapis.com/fcm/send/fCC2pJr3r6E:APA91bGr3a2Z…
8 subscribe with another key   -> THROWS InvalidStateError: Registration failed - A subscription with a different applicationServerKey (or gcm_sender_id) already exists; to change the applicationServerKey, unsubscribe then resubscribe.
9 state:
Notification.permission = granted
service worker        = activated
subscription          = fcm.googleapis.com …yv7PU03E-LPm
expirationTime        = null
10 keys: {"p256dh":87,"auth":22,"p256dhBytes":65,"authBytes":16}

في المخرج أعلاه لاحظ التالي:

  • السطر 2 مضلل إذا لم تفهمه: Chrome في الوضع الخفي لا يملك نافذة يعرض فيها السؤال، فيرد بالرفض حتى عندما جربنا الطلب نفسه من داخل حدث نقر في تجربة ثانية، لذلك لا تختبر تجربة الإذن في متصفح Headless، فهو يخبرك عن نفسه وليس عن مستخدميك. أما Firefox في الحالة نفسها، أي طلب دون نقر، فلم يرد بشيء خلال خمس ثوان وبقي الإذن default.
  • السطران 4 و5: بعد الرفض يفشل الاشتراك برسالة NotAllowedError، والطلب الجديد يعود ب denied فوراً، فكودك يجب أن يقرأ Notification.permission قبل أن يعرض السؤال التمهيدي أصلاً، فإذا كانت denied فاعرض بدل السؤال شرحاً قصيراً لطريقة التفعيل من إعدادات المتصفح، أو لا تعرض شيئاً.
  • السطر 6: الاشتراك بالقيمة userVisibleOnly: false، أي إشعارات صامتة لا يراها المستخدم، يرفضه Chrome حتى بعد الموافقة على الإذن، ورسالة الخطأ نفسها «permission denied» لا تشرح السبب، وهذا ما نعود إليه في قسم ال Service Worker.
  • السطر 8: لا يقبل المتصفح اشتراكاً ثانياً بمفتاح VAPID مختلف ما دام الأول قائماً، والرسالة نفسها تقول الحل: ألغ الاشتراك ثم اشترك من جديد، وهذا ما تحتاجه يوم تغير مفاتيح سيرفرك.
  • السطر 9: القيمة expirationTime هي null في Chrome، أي أن المتصفح لا يعلن تاريخ انتهاء للاشتراك، فلا تبن منطق التنظيف على هذا الحقل.
  • السطر 10: المفتاح العام p256dh طوله 65 بايت، وهو نقطة على المنحنى P-256 بالصيغة غير المضغوطة، والسر auth طوله 16 بايت، وكلاهما يصل إلى سيرفرك بترميز base64url، وهما ما سوف نشفر به الرسالة بعد قليل.

ال Service Worker من الداخل: حدث push والنقر على الإشعار

ال Service Worker هو ملف JavaScript يسجله موقعك، ويعيش خارج أي صفحة، ويوقظه المتصفح عند حدث معين ثم يطفئه بعد ثوان، وقد شرحنا دوره في التخزين والعمل دون إنترنت في التخزين في المتصفح وتطبيقات الويب التقدمية PWA. وفي الإشعارات يهمنا منه ثلاثة أحداث، والملف التالي هو ملف المختبر كاملاً:

// The service worker: decrypted payload in, one visible notification out (userVisibleOnly), click opens the order.
self.addEventListener('push', (event) => {
  let data;
  try { data = event.data.json(); } catch { data = { title: 'متجر المثال', body: event.data ? event.data.text() : '' }; }
  event.waitUntil(Promise.all([
    self.registration.showNotification(data.title, {
      body: data.body,
      tag: data.tag,                      // same tag = replace the older notification on screen
      renotify: Boolean(data.tag),
      data: { url: '/?order=1042' },
      actions: [{ action: 'open', title: 'عرض الطلب' }],
    }),
    fetch('/got', { method: 'POST', body: JSON.stringify({ body: data.body, tag: data.tag, sentAt: data.sent, bytes: event.data ? event.data.arrayBuffer().byteLength : 0 }) }),
  ]));
});

self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  event.waitUntil(clients.matchAll({ type: 'window' }).then((list) => {
    const open = list.find((c) => new URL(c.url).pathname === '/');
    return open ? open.focus() : clients.openWindow(event.notification.data.url);
  }));
});

// The browser may replace a subscription on its own (key rotation, expiry): subscribe again and tell the server
self.addEventListener('pushsubscriptionchange', (event) => {
  event.waitUntil((async () => {
    const { publicKey } = await (await fetch('/vapid')).json();
    const sub = await self.registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: publicKey });
    await fetch('/subscribe', { method: 'POST', body: JSON.stringify({ sub, old: event.oldSubscription?.endpoint }) });
  })());
});

في الملف أعلاه لاحظ التالي:

  • event.data يصل مفكوك التشفير، فالمتصفح يفك الرسالة قبل أن يوقظ ال Service Worker، وإذا فشل الفك لا يستيقظ أصلاً، وهذه نقطة مهمة جداً عند التشخيص كما سوف نرى.
  • event.waitUntil() يقول للمتصفح «لا تطفئني حتى ينتهي هذا الوعد Promise»، وبدونه قد يطفئ المتصفح ال Service Worker قبل أن يظهر الإشعار.
  • الخيار tag يجعل الإشعار الجديد يحل محل القديم الذي يحمل الوسم نفسه على الشاشة، فعشرة تحديثات لطلب واحد تظهر كإشعار واحد، وrenotify يجعل الهاتف يهتز مرة أخرى عند الاستبدال، والخيارات كلها في توثيق showNotification. ولاحظ أن الوسم هنا على الجهاز، ويختلف عن الترويسة Topic التي تعمل في خدمة الإشعارات قبل أن تصل الرسالة، وسوف نجرب الاثنين.
  • الطلب إلى /got للمختبر فقط، فهو يخبر السيرفر أن الرسالة وصلت فعلاً، فنقيس زمن الوصول دون أن ننظر إلى الشاشة، وفي الإنتاج يصبح هذا الطلب نفسه أداة مهمة سوف نشرحها في قسم التنظيف.
  • pushsubscriptionchange يطلق عندما يغير المتصفح الاشتراك من نفسه، والمعالج يشترك من جديد ويرسل العنوان القديم مع الجديد، فيحذف السيرفر الصف القديم بدل أن يتركه يموت.

وعد userVisibleOnly: لماذا لا توجد إشعارات صامتة؟

عندما يشترك موقعك يعطي المتصفح وعداً بالقيمة userVisibleOnly: true، أي أن كل رسالة سوف ينتج عنها إشعار يراه المستخدم. والسبب أن Web Push ليس دعوة لتشغيل كود في الخلفية متى شئت، فلو سمح المتصفح بإشعارات صامتة لاستطاع أي موقع أن يوقظ جهاز المستخدم ويعرف أنه متصل وأين هو دون أن يرى المستخدم شيئاً، ولذلك رأينا أن Chrome يرفض الاشتراك بالقيمة false. ومدونة WebKit في Meet Web Push تقولها صراحة: «Violations of the userVisibleOnly promise will result in a push subscription being revoked»، أي أن Safari يلغي اشتراك الموقع الذي يستقبل رسائل ولا يعرض إشعاراً. وChrome يتصرف بطريقة أخرى، فإذا انتهى حدث push دون إشعار يعرض هو إشعاراً عاماً بأن الموقع تحدث في الخلفية. والقاعدة العملية من هذا كله: لا ترسل رسالة إلا ومعها نص يعرض، وإذا أردت مزامنة بيانات في الخلفية فهذه وظيفة Background Sync وليست وظيفة Push.

تشفير الرسالة بيدك بحسب RFC 8291 Message Encryption

مكتبة web-push وأخواتها في اللغات الأخرى تخفي عنك سطور التشفير، وهذا مريح إلى أن يحدث خطأ لا تعرف مكانه، أو تحتاج أن ترسل من بيئة لا تعمل فيها المكتبة، كمحرك JavaScript داخل PocketBase الذي ذكرناه في مقال الخروج من Firebase. لذلك كتبنا التشفير بأنفسنا في أقل من 30 سطراً، والفكرة كلها في RFC 8291: سيرفرك ينشئ لكل رسالة زوج مفاتيح مؤقتاً على المنحنى P-256، ويحسب مع المفتاح العام للمتصفح سراً مشتركاً بتبادل المفاتيح ECDH، ثم يشتق من هذا السر ومن السر auth مفتاح التشفير بدالة HKDF المعرفة في RFC 5869، ويشفر بخوارزمية AES-128-GCM، ويضع النتيجة في الصيغة aes128gcm المعرفة في RFC 8188. وقد شرحنا تبادل المفاتيح نفسه في التشفير للمطورين، والصورة التالية تبين السلسلة كاملة:

مخطط اشتقاق المفاتيح: من اليسار p256dh وauth من المتصفح، ومن اليمين زوج مفاتيح مؤقت وملح salt من السيرفر، يلتقي المفتاح الخاص المؤقت مع p256dh في ECDH فينتج ecdh_secret، ثم HKDF مع auth والنص WebPush: info وبعده بايت صفر والمفتاحان العامان فينتج IKM، ثم HKDF مع الملح فينتج CEK بطول 16 بايت وNONCE بطول 12 بايت، ثم AES-128-GCM على النص مع البايت 0x02 ووسم 16 بايت، وفي الأسفل شكل الرسالة: salt 16 وrs 4 وidlen 1 وas_public 65 وهي ترويسة 86 بايت ثم النص المشفر
كل ما تراه خدمة الإشعارات هو السطر الأخير

والملف التالي هو الجزء الخاص بالتشفير من webpush-raw.mjs، ولا يستورد إلا وحدة node:crypto:

// Web Push by hand, with node:crypto only (no web-push library):
//   RFC 8291 message encryption (aes128gcm, RFC 8188) and RFC 8292 VAPID (ES256 JWT).
import { createECDH, createHmac, createCipheriv, createPrivateKey, randomBytes, sign } from 'node:crypto';

const b64u = (b) => Buffer.from(b).toString('base64url');
const hkdf = (salt, ikm, info, len) => {                       // HKDF-SHA-256, one output block is enough here
  const prk = createHmac('sha256', salt).update(ikm).digest();
  return createHmac('sha256', prk).update(Buffer.concat([info, Buffer.from([1])])).digest().subarray(0, len);
};

// info: the RFC 8291 label; the lab passes a wrong one on purpose to see what the browser does
export function encrypt(sub, plaintext, { trace = false, info = 'WebPush: info\0' } = {}) {
  const uaPublic = Buffer.from(sub.keys.p256dh, 'base64url');   // the browser's P-256 public key (65 bytes)
  const authSecret = Buffer.from(sub.keys.auth, 'base64url');   // 16 random bytes from the browser
  const as = createECDH('prime256v1'); as.generateKeys();       // a fresh key pair for this one message
  const asPublic = as.getPublicKey();
  const ecdhSecret = as.computeSecret(uaPublic);                // shared secret: only the browser can compute it too
  const salt = randomBytes(16);
  // RFC 8291 section 3.4: mix the auth secret in, bound to both public keys
  const keyInfo = Buffer.concat([Buffer.from(info), uaPublic, asPublic]);
  const ikm = hkdf(authSecret, ecdhSecret, keyInfo, 32);
  const cek = hkdf(salt, ikm, Buffer.from('Content-Encoding: aes128gcm\0'), 16);
  const nonce = hkdf(salt, ikm, Buffer.from('Content-Encoding: nonce\0'), 12);
  // one record: the plaintext, then 0x02, the delimiter of the last record (RFC 8188)
  const c = createCipheriv('aes-128-gcm', cek, nonce);
  const body = Buffer.concat([c.update(Buffer.concat([Buffer.from(plaintext), Buffer.from([2])])), c.final(), c.getAuthTag()]);
  const rs = Buffer.alloc(4); rs.writeUInt32BE(4096);
  const header = Buffer.concat([salt, rs, Buffer.from([asPublic.length]), asPublic]);   // 16 + 4 + 1 + 65 = 86 bytes
  if (trace) console.log({ ecdhSecret: ecdhSecret.toString('hex').slice(0, 16) + '…', ikm: ikm.toString('hex').slice(0, 16) + '…',
    cek: cek.toString('hex'), nonce: nonce.toString('hex'), header: header.length, body: body.length });
  return Buffer.concat([header, body]);
}

في الكود أعلاه لاحظ التالي:

  • دالة HKDF هنا من خطوتين: استخراج Extract بالدالة HMAC والملح مفتاحاً، ثم توسيع Expand بإضافة البايت 0x01، وكتلة واحدة من SHA-256 أي 32 بايت تكفي لأن أطول مخرج نحتاجه 32 بايت.
  • السر auth يدخل كملح في الاشتقاق الأول، والنص "WebPush: info" يتبعه بايت صفر ثم المفتاحان العامان، فيربط هذا المفتاح الناتج بهذا المتصفح وهذه الرسالة معاً، وأي بايت مختلف في هذا النص ينتج مفتاحاً آخر تماماً.
  • المفتاح المؤقت والملح جديدان في كل رسالة، فالرسالة نفسها تشفر في كل مرة ببايتات مختلفة، ولا تستطيع الخدمة أن تعرف أن رسالتين متطابقتان.
  • البايت 0x02 بعد النص هو فاصل آخر سجل Record في RFC 8188، وبعده يمكن إضافة حشو Padding من أصفار لإخفاء الطول الحقيقي للرسالة، ونحن لم نضف حشواً.
  • الترويسة 86 بايت ثابتة: الملح 16، وحجم السجل 4 بايت بقيمة 4096، وبايت طول المفتاح، والمفتاح العام المؤقت 65، ولا تحتاج المتصفحات أي ترويسة HTTP إضافية للتشفير غير Content-Encoding: aes128gcm.

هل التشفير صحيح؟ المتصفح هو الحكم

لا توجد طريقة أصدق لاختبار التشفير من أن يفكه متصفح حقيقي، فإذا أخطأنا لن يصل شيء إلى ال Service Worker. وأرسلنا الرسالة نفسها إلى اشتراك في Firefox 157 وآخر في Chrome على Android، فكان مخرج سكربت Firefox كما يلي:

permission at start       -> default
requestPermission no click -> no answer after 5 s
permission after           -> default
after the user allows      -> granted
endpoint https://updates.push.services.mozilla.com/wpush/v2/gAAAAABq_57Wa…
send -> [{"host":"fcm.googleapis.com","status":201,"verdict":"ok","bytes":224},{"host":"updates.push.services.mozilla.com","status":201,"verdict":"ok","bytes":224}]
service worker got it after 4905 ms
version 157.0

فالخدمتان قبلتا الرسالة بالرد 201، وFirefox فكها وأيقظ ال Service Worker بعد 4.9 ثانية، أي أن الاشتقاق والتشفير والترويسة كلها صحيحة بالبايت. والرسالة على Android وصلت كما في الصورة التالية في قسم دورة الحياة، وقسنا وصولها والهاتف مفتوح على الشاشة الرئيسية وChrome مغلق بالأمر am force-stop، فكان الزمن من طلب الإرسال إلى ال Service Worker 2162 مللي ثانية، لأن خدمات Google Play هي التي تحمل الاتصال وتوقظ Chrome.

ماذا يحدث إذا أخطأت في بايت واحد؟

الآن نخطئ عن قصد: نرسل الرسالة نفسها، لكن النص في الاشتقاق الأول دون بايت الصفر في نهايته، أي "WebPush: info" بدل "WebPush: info\0"، وهو خطأ يقع فيه كل من يكتب التشفير بنفسه. والسؤال: من سيخبرك؟ أرسلنا إلى Chrome على جهاز Windows بعد أن فتحنا صفحة chrome://gcm-internals وفيها سجل لكل ما يستقبله المتصفح من خدمة Google:

good -> [{"host":"fcm.googleapis.com","status":201,"verdict":"ok","bytes":188}, …]
bad  -> [{"host":"fcm.googleapis.com","status":201,"verdict":"ok","bytes":186}, …]
Receive Message Log
Message Decryption Failure Log
Fri Nov 20 2026 04:23:41 GMT+0300 (التوقيت العربي الرسمي)	wp:http://localhost:28961/#B953984D-8663-4FE9-9FED-4C55CE11C-V2	AES-GCM decryption failed
جزء من صفحة GCM Internals في Chrome: جدول Receive Message Log فيه رسالتان مستقبلتان بحجم 513 و515 بايت من المفتاح العام لسيرفرنا، وتحته جدول Message Decryption Failure Log فيه سطر واحد بتاريخ 20 نوفمبر 2026 لتطبيق wp:http://localhost:28961 والتفصيل AES-GCM decryption failed
الرسالة وصلت إلى المتصفح، وفشل فكها، ولم يعلم سيرفرنا بشيء

والنتيجة مهمة جداً: الخدمة ردت بالقبول 201 على الرسالة الخاطئة كما ردت على الصحيحة، لأنها لا تستطيع أن تقرأ المحتوى أصلاً، والمتصفح استلمها ثم فشل في فكها فرماها بصمت، وال Service Worker لم يستيقظ، والمستخدم لم ير شيئاً، وسيرفرك لم يصله أي خطأ. والشيء نفسه رأيناه في UnifiedPush على Android حين أرسلنا بسر auth خاطئ، فالخطأ يظهر في سجلات الجهاز فقط. لذلك اختبر كود التشفير عند كل تغيير فيه بمتصفح حقيقي يستلم ويؤكد، كما يفعل الطلب /got في المختبر، ولا تعتمد على رد الخدمة.

كم بايتاً تحمل الرسالة؟ Payload Size

يلزم RFC 8030 خدمة الإشعارات أن تقبل محتوى حتى 4096 بايت على الأقل، وبعد ترويسة التشفير 86 بايت وفاصل السجل بايت واحد ووسم التحقق 16 بايت يبقى للنص 3993 بايت. وجربنا الحد بالضبط على خدمة Google، مرة بنص طوله 3993 بايت ومرة 3994:

ok, 3993-byte plaintext      -> 201 4096B
3994-byte plaintext          -> 400 4097B binary data passed in the request must be less than 4096 bytes.

ولاحظ أن الرد 400 وليس 413 كما قد تتوقع من RFC 8030، فخدمة Google تعامل الحجم كطلب خاطئ، وهذا يعني أن كود التنظيف يجب ألا يربط 400 بحذف الاشتراك، فالاشتراك سليم والمشكلة في رسالتك. وتذكر أن النص العربي في UTF-8 بايتان لكل حرف تقريباً، فالحد عملياً قرابة 1900 حرف عربي، ولكن الإشعار ليس مكاناً للبيانات أصلاً، والتصميم الذي يعمل في كل المنصات عنوان ونص قصيران ومعرف الشيء الذي يتعلق به الإشعار، ويطلب التطبيق التفاصيل من سيرفرك عندما يفتح المستخدم الإشعار.

توقيع VAPID بيدك بحسب RFC 8292

التشفير يحمي المحتوى من خدمة الإشعارات، أما VAPID فيثبت للخدمة أن الطلب جاء من السيرفر نفسه الذي اشترك المتصفح بمفتاحه العام، فلا يستطيع من سرق عنوان اشتراك أن يرسل إليه دون المفتاح الخاص. والتوقيع توكن JWT بخوارزمية ES256، والجزء الثاني من الملف يكتبه:

export function vapidKeys() {
  const k = createECDH('prime256v1'); k.generateKeys();
  return { publicKey: b64u(k.getPublicKey()), privateKey: b64u(k.getPrivateKey()) };
}

// the JWT the push service checks: aud = origin of the endpoint, exp at most 24 hours ahead, sub = how to reach you
export function vapidHeader(endpoint, keys, { subject = 'mailto:[email protected]', expSeconds = 12 * 3600, aud } = {}) {
  const pub = Buffer.from(keys.publicKey, 'base64url');
  const jwk = { kty: 'EC', crv: 'P-256', x: b64u(pub.subarray(1, 33)), y: b64u(pub.subarray(33, 65)), d: keys.privateKey };
  const head = b64u(JSON.stringify({ typ: 'JWT', alg: 'ES256' }));
  const claims = b64u(JSON.stringify({ aud: aud ?? new URL(endpoint).origin, exp: Math.floor(Date.now() / 1000) + expSeconds, sub: subject }));
  const sig = sign('sha256', Buffer.from(`${head}.${claims}`), { key: createPrivateKey({ key: jwk, format: 'jwk' }), dsaEncoding: 'ieee-p1363' });
  return `vapid t=${head}.${claims}.${b64u(sig)}, k=${keys.publicKey}`;
}

export async function send(sub, payload, keys, { ttl = 60, urgency = 'normal', topic, trace, info, vapid = {}, noAuth = false } = {}) {
  const body = encrypt(sub, payload, { trace, info });
  const headers = { 'Content-Encoding': 'aes128gcm', 'Content-Type': 'application/octet-stream', TTL: String(ttl), Urgency: urgency };
  if (!noAuth) headers.Authorization = vapidHeader(sub.endpoint, keys, vapid);
  if (topic) headers.Topic = topic;
  const r = await fetch(sub.endpoint, { method: 'POST', headers, body });
  return { status: r.status, text: (await r.text()).trim().slice(0, 160), bytes: body.length, retryAfter: r.headers.get('retry-after') };
}

في الكود أعلاه لاحظ التالي:

  • المفتاح الخاص يتحول إلى صيغة JWK بإحداثيي النقطة x وy من المفتاح العام، فلا نحتاج ملف PEM.
  • الخيار dsaEncoding: 'ieee-p1363' أهم سطر في التوقيع: Node.js يخرج توقيع ECDSA افتراضياً بصيغة DER، أما JWT فيطلب الرقمين r وs متتاليين بطول 64 بايت، وبدون هذا الخيار ترفض كل الخدمات التوقيع.
  • الحقل aud هو أصل Origin عنوان الاشتراك فقط، أي https://fcm.googleapis.com دون المسار، فالتوكن الواحد يصلح لكل اشتراكات الخدمة نفسها، وتستطيع أن تحفظه مؤقتاً Cache حتى قرب انتهائه بدل أن توقع لكل رسالة.
  • الحقل sub بريد أو رابط تتواصل به معك الخدمة إذا أساء سيرفرك الاستخدام، فضع فيه بريداً حقيقياً يقرؤه أحد.
  • المفتاح العام يرسل في الجزء k= من الترويسة نفسها، وهذه الصيغة الحالية في RFC 8292، أما الترويسة Crypto-Key التي تجدها في أمثلة قديمة فهي من مسودات سابقة.

ثم أفسدنا التوقيع بثلاث طرق مختلفة لنرى ما تقوله الخدمة، فكان المخرج كما يلي:

no VAPID header              -> 401 154B Authorization header must be specified: unauthenticated
exp 25 hours ahead           -> 403 153B permission denied: exp claim MUST NOT be more than 24 hours from the time of the request
aud = another origin         -> 403 155B permission denied: aud claim in the token MUST include the origin of the push resource URL

والرسائل هنا واضحة على عكس خطأ التشفير، لأن الخدمة تستطيع أن تقرأ التوكن. ولاحظ أن الحد 24 ساعة صارم، فإذا كانت ساعة سيرفرك متقدمة بساعة وجعلت exp بعد 24 ساعة تماماً ترفض كل رسائلك، لذلك اجعلها 12 ساعة كما فعلنا، وشغل مزامنة الوقت NTP على السيرفر. وتذكر من المقال الأول الرد الرابع: مفتاح VAPID آخر غير الذي اشترك به المتصفح يعطي 403 أيضاً، وهذا ما يجعل الرد 403 من أخطر الردود عند التنظيف كما سوف نرى.

الترويسات TTL وUrgency وTopic في هاتف دون شبكة

في RFC 8030 ثلاث ترويسات تتحكم في سلوك الخدمة عندما لا يكون الجهاز متصلاً، وشرحها بالكلام سهل، لكن رؤيتها تعمل أوضح:

  • TTL: كم ثانية تحفظ الخدمة الرسالة إذا كان الجهاز غير متصل، والقيمة صفر تعني «الآن أو لا».
  • Urgency: الأولوية، من very-low إلى low إلى normal إلى high، والخدمة والنظام يقرران بها هل يوقظان الجهاز الآن أم ينتظران وقتاً أوفر للبطارية.
  • Topic: اسم من 32 حرفاً على الأكثر من حروف base64url، فإذا وصلت رسالة جديدة بالاسم نفسه والقديمة ما زالت محفوظة في الخدمة حلت الجديدة محلها.

ولنرى ذلك وضعنا هاتف المحاكي في وضع الطيران Airplane Mode، وأرسلنا خمس رسائل بترويسات مختلفة، وانتظرنا 20 ثانية، ثم أعدنا الشبكة، وانتظرنا 90 ثانية:

adb('cmd', 'connectivity', 'airplane-mode', 'enable'); await sleep(4000);
console.log('A TTL=0                      ->', await post({ text: 'A: TTL صفر', ttl: 0 }));
console.log('B TTL=600 Topic=order-1042  ->', await post({ text: 'B: الطلب قيد التجهيز', ttl: 600, topic: 'order-1042' }));
console.log('C TTL=600 Topic=order-1042  ->', await post({ text: 'C: الطلب خرج للتوصيل', ttl: 600, topic: 'order-1042' }));
console.log('D TTL=600 Topic=order-1042  ->', await post({ text: 'D: السائق على بعد 5 دقائق', ttl: 600, topic: 'order-1042' }));
console.log('E TTL=600 no Topic          ->', await post({ text: 'E: كوبون خصم', ttl: 600, urgency: 'low' }));
await sleep(20000);
adb('cmd', 'connectivity', 'airplane-mode', 'disable');
airplane mode on
A TTL=0                      -> 201,201
B TTL=600 Topic=order-1042  -> 201,201
C TTL=600 Topic=order-1042  -> 201,201
D TTL=600 Topic=order-1042  -> 201,201
E TTL=600 no Topic          -> 201,201
airplane mode off after 20 s
got "D: السائق على بعد 5 دقائق" 5.8 s after the network came back
got "E: كوبون خصم" 6.1 s after the network came back
2 of 5 arrived
مخطط من جزأين: على اليسار خلفية صفراء بعنوان وضع الطيران وفيه خمس رسائل، A بقيمة TTL صفر ضاعت، وB وC بالموضوع order-1042 حلت محل كل منهما التي بعدها، وD الأحدث في الموضوع، وE دون موضوع بأولوية low تنتظر كما هي، وعلى اليمين خلفية خضراء بعنوان عادت الشبكة فيها الرسالتان D بعد 5.8 ثانية وE بعد 6.1 ثانية، وملاحظة أن الطلبات الخمسة ردت كلها 201
خمس رسائل بالرد 201، ورسالتان فقط وصلتا، وكلاهما سلوك صحيح

في المخرج أعلاه لاحظ التالي:

  • الرقمان في كل سطر هما ردا الخدمة على اشتراكين في السيرفر، وكلها 201، فالخدمة قبلت الخمسة ولم تقل لك ماذا ستفعل بها.
  • الرسالة A ضاعت، وهذا هو المقصود من TTL صفر: إشعار «السائق أمام الباب» لا قيمة له بعد أن يدخل المستخدم بيته، فلا معنى أن يصل بعد ساعة.
  • الرسائل B وC وD لها الموضوع نفسه، فحلت كل واحدة محل التي قبلها في الخدمة، ووصلت D وحدها، وهي الحالة الأحدث للطلب، وهذا ما تريده تماماً في تحديثات الحالة، فالمستخدم الذي يفتح هاتفه لا يحتاج تاريخ الطلب كاملاً في ثلاثة إشعارات.
  • الرسالة E بقيت لأن لها TTL عشر دقائق ولا موضوع لها، ووصلت بعد D بثلث ثانية.
  • وصلت الرسالتان بعد قرابة ست ثوان من عودة الشبكة، وهو الوقت الذي احتاجه الهاتف ليعيد اتصاله بخدمة Google.

وجربنا أيضاً قيمة TTL أكبر من أربعة أسابيع، فقبلتها الخدمة ب 201 ووصلت الرسالة، لأن RFC 8030 يسمح للخدمة أن تحفظ الرسالة مدة أقصر مما طلبت دون أن ترفضها، فلا تعتمد على TTL طويلة لرسائل مهمة، واجعل القيمة بحسب عمر المعلومة الحقيقي: دقائق للتوصيل، وساعات للتذكير، ويوم للفاتورة. وأما Urgency فاستخدم high للرسائل التي تحتاج إيقاظ الجهاز فقط، لأن أنظمة الهواتف تخفض أولوية التطبيقات التي تجعل كل رسائلها عاجلة، وهذه هي الفكرة نفسها في التنبيهات Alerting: ما يوقظ المستخدم يجب أن يستحق ذلك.

دورة حياة الاشتراك Subscription Lifecycle

الاشتراك عنوان Endpoint ومفتاحان، ويبقى صالحاً إلى أن يحدث واحد من أربعة أشياء رأيناها في الصورة الأولى، ولكل واحد منها طريقة مختلفة يعرف بها سيرفرك، أو لا يعرف أبداً.

المستخدم ألغى من صفحتك: أخبر السيرفر أولاً

إذا وضعت في إعدادات حسابك زر «إيقاف الإشعارات» فهذا أسهل الحالات، لأنك تعرف بالإلغاء لحظة حدوثه، والترتيب الصحيح أن تخبر السيرفر أولاً ثم تلغي في المتصفح، لأن العكس قد ينجح في المتصفح ويفشل الطلب إلى السيرفر فيبقى الصف عندك:

window.unsubscribe = async () => {
  const sub = await (await navigator.serviceWorker.ready).pushManager.getSubscription()
  if (!sub) return 'none'
  await fetch('/unsubscribe', { method: 'POST', body: JSON.stringify({ endpoint: sub.endpoint }) })   // tell the server first
  const ok = await sub.unsubscribe(); await show(); return ok
}

المستخدم ألغى من الإشعار نفسه

هنا رأينا في المحاكي شيئاً لم يكن في تصميم صفحتنا: Chrome على Android يضيف إلى كل إشعار من موقع زراً من عنده اسمه «Unsubscribe» بجانب أزرارنا، وعند الضغط عليه يلغي الاشتراك فوراً ويعرض إشعاراً بدله فيه «Undo» و«Okay»، كما في الصورة:

لقطتان من شريط الإشعارات في Android: الأولى إشعار من Chrome للموقع 127.0.0.1:28961 عنوانه متجر المثال ونصه طلبك رقم 1042 خرج للتوصيل، وتحته زرا عرض الطلب وUnsubscribe، والثانية بعد الضغط على Unsubscribe وفيها Unsubscribed from notifications وYou'll no longer receive notifications from 127.0.0.1:28961 مع زري Undo وOkay
زر عرض الطلب من ال Service Worker، وزر Unsubscribe أضافه Chrome نفسه

وهذا يعني أن الإلغاء قد يحدث دون أن تفتح صفحتك أصلاً، فلا تفترض أن صفحة الإعدادات هي الطريق الوحيد. وأرسل السيرفر بعدها مباشرة إلى كل اشتراكاته، فكان الرد على اشتراك الهاتف كما يلي:

[{"host":"fcm.googleapis.com","status":201,"verdict":"ok","bytes":220},{"host":"fcm.googleapis.com","status":410,"verdict":"drop","bytes":220,"text":"push subscription has unsubscribed or expired."},{"host":"fcm.googleapis.com","status":201,"verdict":"ok","bytes":220},{"host":"fcm.googleapis.com","status":201,"verdict":"ok","bytes":220}]

فالرد 410 جاء من أول إرسال بعد الإلغاء، وحذف السيرفر الصف، وفي الإرسال التالي بعد 30 ثانية لم يعد هذا الاشتراك في القائمة أصلاً. وتذكر أن هذا يختلف عما رأيناه في مقال الخروج من Firebase، حين ألغينا من Chrome على سطح المكتب فبقيت الخدمة ترد 201 دقائق قبل أن ترد 410، فتوقيت الرد يختلف بين متصفح وآخر ونظام وآخر، والثابت فقط أن 410 يأتي في النهاية.

الاشتراك الذي يموت بصمت

والحالة الأخطر هي التي لا يأتي فيها 410 أبداً. ففي المختبر حذفنا ملف تعريف Chrome على سطح المكتب بعد كل تجربة، كما يحدث عندما يعيد المستخدم تثبيت المتصفح أو يغير جهازه أو يمسح كل بياناته، ولاحظ في المخرج أعلاه الردود الثلاثة 201 الأخرى: هي اشتراكات ملفات محذوفة، والخدمة ما زالت تقبل الرسائل إليها بعد أكثر من ساعة، لأنها لا تعرف أن هذا المتصفح لن يعود، فتحفظ كل رسالة حتى تنتهي مدة TTL ثم ترميها. وهنا اكتشفنا خطأ في سيرفر المختبر نفسه: كنا نحدث العمود lastSuccess عند كل رد 201، فكانت الاشتراكات الميتة تبدو ناجحة دائماً، والصحيح أن «النجاح» لا يعرف من رد الخدمة، وإنما من تأكيد الاستلام الذي يرسله ال Service Worker، كالطلب /got في المختبر. والقاعدة التي نقترحها:

  • احفظ لكل اشتراك تاريخ آخر استلام مؤكد last_received، يحدثه ال Service Worker بطلب صغير بعد عرض الإشعار.
  • احذف الاشتراك الذي لم يؤكد أي استلام منذ مدة تناسب تطبيقك، شهرين مثلاً، حتى لو كانت الخدمة ترد 201.
  • لا تجعل طلب التأكيد شرطاً لعرض الإشعار، فإذا فشل الطلب يبقى الإشعار ظاهراً، ولذلك وضعناه في Promise.all بجانب showNotification وليس قبله.
  • تأكيد الاستلام يعطيك فوق ذلك رقماً حقيقياً للمراقبة: نسبة الرسائل التي وصلت فعلاً من كل ما أرسلت، وهذا لا تعطيك إياه الخدمة.

المتصفح غير الاشتراك: pushsubscriptionchange

الحالة الرابعة أن يستبدل المتصفح الاشتراك من نفسه، لأن الخدمة أنهته أو لأن المفاتيح تغيرت، فيطلق الحدث pushsubscriptionchange في ال Service Worker. ولا يوجد طريق آمن لإطلاق هذا الحدث عن قصد في تجربة، لذلك نكتفي بما في توثيق MDN وبالمعالج الذي رأيته في ملف ال Service Worker: اشترك من جديد بالمفتاح نفسه، وأرسل العنوانين القديم والجديد، والسيرفر يحذف القديم ويضيف الجديد في عملية واحدة. وتذكر من السطر 8 في تجربة الإذن أن المتصفح لا يقبل اشتراكاً بمفتاح آخر ما دام الأول قائماً، فإذا أردت تغيير مفاتيح VAPID فالطريق هو: الصفحة عند الفتح تقرأ الاشتراك بالدالة getSubscription()، وتقارن مفتاحه options.applicationServerKey بمفتاحك الجديد، فإذا اختلفا ألغته واشتركت من جديد دون أن تطلب الإذن مرة ثانية، لأن الإذن للموقع وليس للاشتراك.

رموز الرد وتنظيف الاشتراكات Status Codes and Cleanup

جمعنا كل ما رأيناه في المختبر في دالة واحدة في السيرفر تقرر ماذا يفعل بالصف بعد كل رد، وهي أهم 10 أسطر في سيرفر الإشعارات:

// what to do with each answer: keep, drop the subscription, or fix our own configuration
function verdict(status) {
  if (status === 201 || status === 202) return 'ok';
  if (status === 404 || status === 410) return 'drop';           // gone for good: delete the row now
  if (status === 413) return 'too-large';                         // our payload, not the subscription
  if (status === 429) return 'retry-later';                       // honour Retry-After
  if (status === 400 || status === 401 || status === 403) return 'fix-config';   // VAPID or headers: never delete for this
  return 'retry-later';                                           // 5xx and anything else
}
سيرفر التطبيق يرسل سهماً إلى سحابة fcm.googleapis.com، وعلى اليمين خمسة صفوف: 201 قبلت الخدمة الرسالة وحفظتها وليس دليلاً على الوصول، و404 أو 410 الاشتراك انتهى إلى الأبد فاحذف الصف، و400 أو 413 المحتوى أكبر من 4096 بايت أو الطلب خاطئ فأصلح الرسالة، و401 أو 403 توقيع VAPID غائب أو exp أو aud أو مفتاح آخر فأصلح إعدادك ولا تحذف أي اشتراك، و429 أو 5xx ضغط أو عطل مؤقت فأعد لاحقاً واحترم Retry-After
الحذف عند 404 و410 فقط، وكل ما عداه خطأ عندك أو عطل مؤقت

والسبب في التشدد مع 403 تحديداً قصة متكررة: فريق ينقل السيرفر إلى جهاز جديد وينسى ملف مفاتيح VAPID، فيولد السيرفر مفاتيح جديدة، فترد الخدمة 403 على كل الاشتراكات في دقيقة واحدة، وإذا كان كود التنظيف يحذف عند كل خطأ فقد حذف قائمة مشتركيه كاملة، ولا يوجد طريق لاستعادتها إلا أن يعود كل مستخدم إلى الموقع ويضغط «نعم» مرة ثانية. لذلك اجعل الحذف عند 404 و410 فقط، وراقب نسبة الردود 403 في كل ساعة، فإذا ارتفعت فجأة فأوقف الإرسال وابدأ بالمفاتيح. وفي الجدول التالي ملخص ما رأيناه من خدمة Google في هذا المقال والمقالين السابقين:

الردمتى رأيناهما يفعله السيرفر
201كل رسالة مقبولة، ومنها رسائل إلى ملفات متصفح محذوفة ورسائل بتشفير خاطئلا يعتبرها وصولاً، وينتظر تأكيد الاستلام
410بعد Unsubscribe من الإشعار مباشرة، وبعد الإلغاء من Chrome سطح المكتب بدقائقيحذف الصف فوراً
400نص طوله 3994 بايتيصلح الرسالة، والاشتراك سليم
401طلب دون ترويسة Authorizationيصلح الكود
403exp بعد 25 ساعة، وaud لخدمة أخرى، ومفتاح VAPID آخريصلح الإعداد، ولا يحذف شيئاً

وفي الإنتاج اجعل الإرسال في طابور Queue وليس في طلب المستخدم نفسه، فالحدث الذي يطلق إشعاراً لألف مشترك لا يجب أن ينتظر ألف طلب HTTP، واحترم الترويسة Retry-After مع الرد 429، وأعد المحاولة مع 5xx بانتظار يتزايد، وكل هذا شرحناه بالتفصيل في كيف تبني نظام إشعارات يصل إلى ملايين المستخدمين.

Safari وiPhone وiPad: شرط الشاشة الرئيسية

Safari يدعم Web Push بالمعيار نفسه، والكود الذي كتبناه لا يتغير فيه سطر، لكن الشروط على iPhone وiPad مختلفة، وهي من توثيق WebKit لأن هذه التجربة لا تعمل إلا على جهاز من Apple:

  • على macOS: أضافت Apple دعم Web Push إلى Safari 16 على macOS Ventura كما في Meet Web Push، دون حاجة إلى حساب في برنامج المطورين، والعنوان على نطاقات Apple.
  • على iOS وiPadOS 16.4 وما بعده: بحسب Web Push for Web Apps on iOS and iPadOS، لا يستطيع الموقع أن يطلب الإذن في Safari العادي أصلاً، وإنما يجب أن يضيفه المستخدم إلى الشاشة الرئيسية Home Screen، وأن يكون في ملف البيان Manifest الحقل display بقيمة standalone أو fullscreen، وأن يأتي طلب الإذن «in response to direct user interaction»، أي بعد ضغطة على زر مثل زر سؤالنا التمهيدي.
  • عناوين الاشتراك: على نطاقات فرعية من push.apple.com، فإذا كان سيرفرك يمنع الاتصالات الخارجية إلا لقائمة محددة فأضف *.push.apple.com إليها، كما يذكر التوثيق.
  • ما يأتي معه: واجهة الشارة Badging API لتغيير الرقم على أيقونة التطبيق، والتكامل مع أوضاع التركيز Focus، وظهور الإشعارات على شاشة القفل وفي ساعة Apple.
أربع خطوات مرقمة: هاتف وتحته Safari ثم مشاركة ثم إضافة إلى الشاشة الرئيسية والبيان display standalone، ثم هاتف يفتح التطبيق من أيقونته ويضغط زر الاشتراك requestPermission، ثم سحابة عليها *.push.apple.com العنوان على خدمة Apple دون حساب مطور وبالمعيار نفسه، ثم سيرفرك يرسل كما يرسل لأي متصفح بمفاتيح VAPID وRFC 8291، وفي الأسفل ملاحظة أن iOS 18.4 يقبل Declarative Web Push دون Service Worker
على iPhone لا يظهر طلب الإذن إلا داخل تطبيق ويب أضيف إلى الشاشة الرئيسية

وهذا الشرط يغير تصميم السؤال التمهيدي على iPhone: إذا كان الزائر في Safari العادي فلا فائدة من زر «نعم، أخبرني»، والأنسب أن تعرض له شرحاً قصيراً لطريقة إضافة الموقع إلى الشاشة الرئيسية، ثم تعرض السؤال عندما يفتح التطبيق من أيقونته، وتستطيع أن تعرف ذلك من الشرط window.matchMedia('(display-mode: standalone)').matches.

Declarative Web Push: إشعار دون Service Worker

وفي iOS وiPadOS 18.4 أضافت Apple طريقة جديدة اسمها Declarative Web Push، فبدل أن يفك ال Service Worker الرسالة ويقرر ماذا يعرض، تحمل الرسالة نفسها وصف الإشعار بصيغة JSON محددة، فيعرضه المتصفح مباشرة، ومثال المقال نفسه هو:

{
    "web_push": 8030,
    "notification": {
        "title": "Webkit.org — Meet Declarative Web Push",
        "lang": "en-US",
        "dir": "ltr",
        "body": "Send push notifications without JavaScript or service worker!",
        "navigate": "https://webkit.org/blog/16535/meet-declarative-web-push/",
        "silent": false,
        "app_badge": "1"
    }
}

في المثال أعلاه لاحظ التالي:

  • القيمة "web_push": 8030 هي العلامة التي تجعل المتصفح يقرأ الرسالة بهذه الطريقة، والرقم إشارة إلى RFC 8030.
  • title مطلوب، وnavigate مطلوب، وهو الرابط الذي يفتح عند النقر، أي أن النقر نفسه لا يحتاج كوداً.
  • الحقل dir يقبل rtl للعربية، وهذا ما تضعه في رسائلك.
  • إذا كان للموقع Service Worker يصله حدث push كالعادة ومعه الإشعار المقترح، فإذا عرض بديلاً في الوقت المحدد أخذ به المتصفح، وإلا عرض المقترح، ولذلك يذكر المقال أن عقوبات الإشعارات الصامتة لا تطبق على هذه الرسائل، لأن الإشعار المرئي مضمون.

والجميل أن هذه الصيغة لا تكسر شيئاً في المتصفحات الأخرى، فإذا جعلت رسائلك كلها بهذا الشكل وجعلت ال Service Worker يقرأ notification.title وnotification.body منها، عملت الرسالة نفسها في Chrome وFirefox بالطريقة القديمة وفي Safari الجديد دون كود، وهذا ما ينصح به المقال نفسه. ولاحظ أن التشفير وتوقيع VAPID لا يتغيران، فالرسالة الوصفية تشفر بالطريقة نفسها التي كتبناها.

قبل الإنتاج Production Notes

  • HTTPS: الموقع على HTTPS إلزامي خارج localhost، وال Service Worker يسجل من الأصل Origin نفسه، فإذا غيرت النطاق Domain يوماً فكل الاشتراكات تبقى مربوطة بالنطاق القديم.
  • مفاتيح VAPID: تولد مرة واحدة، وتحفظ مع أسرار الإنتاج Secrets وفي النسخة الاحتياطية Backup، ولا تولد عند تشغيل السيرفر إذا لم تجدها، لأن هذا ما يحول نسيان ملف إلى خسارة كل المشتركين.
  • ساعة السيرفر: NTP شغال، لأن exp يقارن بساعة الخدمة.
  • الإرسال في طابور: عمال Workers يرسلون، والطلب الذي يطلق الحدث لا ينتظرهم، وقد شرحنا الطوابير وإعادة المحاولة في نظام الإشعارات.
  • الجدول: عمود لنوع الاشتراك، وتاريخ آخر استلام مؤكد، وعدد الأخطاء المتتالية، وفهرس فريد على العنوان.
  • المراقبة: نسبة الردود 201 و403 و410 في كل ساعة، ونسبة الاستلام المؤكد من المرسل، فالأولى تخبرك عن إعدادك والثانية عن مستخدميك.
  • المحتوى: لا بيانات حساسة في النص، فالرسالة مشفرة في الطريق لكنها تظهر على شاشة القفل.

كيف تختبر هذا كله آلياً؟ Testing

ما رأيناه في المختبر يحدد ما يصلح للاختبار الآلي في خط CI وما لا يصلح. فالمتصفح في الوضع الخفي يرفض الإذن من نفسه كما رأينا، وFirefox في حزمة Playwright يطفئ الاتصال بخدمة الإشعارات عن قصد حتى نعيد إعداده، وهذا ما وصفناه في اختبار الإشعارات آلياً. والتقسيم الذي نقترحه ثلاث طبقات:

  • اختبار وحدة Unit Test للتشفير: تولد في الاختبار زوج مفاتيح يمثل المتصفح، وتشفر بكودك، ثم تفك بالمفتاح الخاص بالاشتقاق نفسه، فإذا تغير بايت في الاشتقاق يفشل الاختبار فوراً، وهذا يغطي الخطأ الصامت الذي رأيناه.
  • اختبار دالة القرار: لكل رمز رد ما يجب أن يحدث للصف، وهذه أسهل الاختبارات وأهمها.
  • اختبار حقيقي مجدول: متصفح حقيقي باشتراك ثابت، كما فعلنا في Chrome على الجهاز وفي المحاكي، يستقبل رسالة كل ساعة ويؤكد استلامها، فإذا توقف التأكيد عرفت قبل المستخدمين، وتفاصيل المحاكي في اختبار تطبيقات الجوال.

أخطاء شائعة Common Mistakes

  • طلب الإذن عند أول زيارة: الرفض لا رجوع عنه، فاسأل بسؤال تمهيدي في لحظة لها معنى.
  • اختبار الإذن في متصفح Headless: يرفض من نفسه، فالنتيجة لا تخبرك بشيء عن المستخدمين.
  • نسيان بايت الصفر في "WebPush: info\0": الخدمة ترد 201 والمتصفح يرمي الرسالة بصمت، ولا يظهر الخطأ إلا في chrome://gcm-internals.
  • توقيع ECDSA بصيغة DER: اجعل dsaEncoding: 'ieee-p1363' في Node.js.
  • exp قريب من 24 ساعة: فرق دقائق في ساعة السيرفر يجعل كل الرسائل 403.
  • حذف الاشتراك عند 403 أو 400: الخطأ عندك وليس عند المستخدم، والحذف عند 404 و410 فقط.
  • اعتبار 201 نجاحاً: الاشتراك الميت يرد 201، فاحسب النجاح من تأكيد الاستلام.
  • رسالة دون إشعار: Safari يلغي الاشتراك، وChrome يعرض إشعاراً عاماً، فلكل رسالة نص يعرض.
  • TTL واحدة لكل الرسائل: اجعلها بحسب عمر المعلومة، واستخدم Topic لتحديثات الشيء نفسه.
  • الاعتماد على زر في صفحة الإعدادات وحده: المستخدم قد يلغي من الإشعار نفسه أو من إعدادات المتصفح.

قائمة تحقق Checklist قبل الإطلاق

البندما تتحقق منه
الإذنسؤال تمهيدي، وrequestPermission() داخل معالج النقر، وحالة denied لها رسالة أخرى
ال Service WorkerwaitUntil، وإشعار لكل رسالة، وtag للتحديثات، ومعالج النقر، ومعالج pushsubscriptionchange
التشفيراختبار وحدة يفك ما يشفره الكود، وحجم النص أقل من 3993 بايت
VAPIDالمفاتيح في الأسرار والنسخة الاحتياطية، وexp 12 ساعة، وsub بريد حقيقي، وNTP
الترويساتTTL بحسب عمر المعلومة، وUrgency عالية للضروري فقط، وTopic لتحديثات الشيء نفسه
التنظيفحذف عند 404 و410 فقط، وتأكيد استلام، وحذف الخامل بتاريخ آخر استلام
Safari على iPhoneManifest بقيمة standalone، وشرح الإضافة إلى الشاشة الرئيسية، ورسائل بصيغة Declarative
المراقبةنسب الردود في كل ساعة، ونسبة الاستلام المؤكد، وتنبيه عند ارتفاع 403

تدريب عملي Practice

  • اكتب اختبار وحدة لدالة encrypt: ولد زوج مفاتيح للمتصفح، وشفر نصاً عربياً، ثم اكتب دالة الفك بالاشتقاق نفسه من جهة المتصفح وتأكد أن النص عاد كما هو، ثم احذف بايت الصفر من النص info وتأكد أن الاختبار فشل.
  • أضف إلى ال Service Worker طلب تأكيد الاستلام، وإلى الجدول العمود last_received، واكتب استعلاماً يعرض الاشتراكات التي ردت عليها الخدمة 201 خلال الشهر الأخير ولم تؤكد أي استلام.

الخلاصة

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • في Web Push تملك ثلاثة أشياء كاملة: لحظة طلب الإذن، والتشفير، وجدول الاشتراكات، ولا تملك خدمة المتصفح التي في الطريق.
  • الرفض لا رجوع عنه، فاسأل بسؤال تمهيدي في لحظة لها معنى، واستدع نافذة المتصفح من داخل النقر، والمتصفح Headless لا يصلح لاختبار ذلك.
  • التشفير بحسب RFC 8291 أقل من 30 سطراً بوحدة node:crypto، وقبله Chrome وFirefox، لكن الخطأ فيه لا يظهر لسيرفرك أبداً: الخدمة ترد 201 والمتصفح يرمي الرسالة.
  • توقيع VAPID أخطاؤه واضحة: 401 دون توقيع، و403 مع exp بعد 24 ساعة أو aud لخدمة أخرى أو مفتاح آخر.
  • في هاتف دون شبكة ضاعت رسالة TTL صفر، ووصلت من ثلاث رسائل بالموضوع نفسه الأخيرة فقط، وكل الردود كانت 201.
  • احذف الاشتراك عند 404 و410 فقط، واحسب النجاح من تأكيد الاستلام لا من رد الخدمة، لأن الاشتراك الميت يرد 201.
  • على iPhone يعمل الكود نفسه، بشرط تطبيق ويب على الشاشة الرئيسية، ورسائل Declarative Web Push تعرض دون Service Worker في iOS 18.4.
دليلكيف تعمل الإشعارات الفورية Push Notifications؟كيف يصل الإشعار إلى تطبيق مغلق عبر خدمات Apple وGoogle، وما الذي تراه هذه الخدمات من بيانات مستخدميك.دليلإشعارات Push بدون Firebase: ما يستبدل وما يبقى عند Appleما الذي تستطيع أن تخرج منه Firebase في إشعارات الويب وAndroid وiPhone، مع مختبر يرسل Web Push بمفاتيحك وUnifiedPush عبر ntfy على سيرفرك.دليلUnifiedPush: إشعارات Android دون Googleكيف يصل إشعار تطبيقك إلى هاتف Android عبر موزع وسيرفر تختارهما أنت، بتجربة على هاتف حقيقي مع ntfy وما الذي يوقف الإشعارات في الخلفية.دليلإشعارات فورية من سيرفرك إلى هاتفك مع ntfyكيف تشغل سيرفر ntfy خاصاً، وتصلك على هاتفك رسالة عندما يمتلئ القرص أو تفشل النسخة الاحتياطية أو ينتهي النشر.دليلكيف تبني نظام إشعارات يصل إلى ملايين المستخدمينكيف تصل الرسالة الصحيحة إلى المستخدم مرة واحدة وفي وقتها عبر الإشعار والرسائل والبريد، حتى عندما يتعطل المزود.دليلالتخزين في المتصفح وتطبيقات PWA: الحدود والعمل دون إنترنتقسنا في Chrome حدود الكوكيز وlocalStorage وIndexedDB وCache API حتى رفض المتصفح، ثم شغلنا تطبيقاً والسيرفر متوقف ونشرنا إصداراً جديداً لنرى متى يصل.

سجل التحديثات

  • 20 نوفمبر 2026: كتابة المقال، وتنفيذ المختبر بسيرفر Node.js 24.21.0 في Container يشفر ويوقع بوحدة node:crypto دون مكتبة web-push، مع Google Chrome 157 وFirefox 157 من Playwright 1.64.0 وChrome 124 على Android 15 في المحاكي، وقياس TTL وTopic في وضع الطيران ورموز الرد من خدمة Google.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.