استخدام Web Push

يمكنك في الإضافات استخدام أي مقدّم خدمة Push لإرسال الإشعارات الفورية والرسائل. ستتم معالجة الإشعار الوارد من Push API بواسطة عامل الخدمة فور تلقّيه. إذا تم تعليق عامل الخدمة، سيؤدي إرسال إشعار Push إلى إعادة تنشيطه. وتكون عملية استخدامه في الإضافات هي نفسها تمامًا كما لو كنت تستخدمه على الويب المفتوح.

الحصول على إذن لاستخدام Push API

عند تسجيل خادم إشعارات فورية على موقع إلكتروني عادي، يظهر للمستخدم طلب إذن لمنحه أو رفضه. مع الإضافات التي لن يتم عرض المطالبة بها. لاستخدام Push API في إضافتك، عليك ضبط إذن notifications في ملف manifest.json.

  {
    "manifest_version": 3,
    ...
    "permissions": ["notifications"]

إذا لم يكن لديك هذا الإذن، سيؤدي أي تفاعل مع registration.pushManager إلى حدوث خطأ على الفور، وهو النتيجة نفسها التي تحدث إذا رفض المستخدم منح الإذن. بالإضافة إلى ذلك، يُرجى العِلم أنّ إذن notifications سيؤدي إلى عرض تحذير بشأن الإذن عند التثبيت. سيوقف Chrome أيضًا الإضافة في أي عمليات تثبيت حالية إلى أن يوافق المستخدم على طلب الحصول على إذن جديد. يمكنك الاطّلاع على مزيد من المعلومات حول كيفية التعامل مع هذا الأمر في دليل تحذير الأذونات.

مقدّمو خدمات الإشعارات الفورية وخدمات الإشعارات الفورية

بعد إضافة الإذن إلى ملف manifest.json، عليك إعداد الاتصال بين الخلفية والإضافة. يمكن تقسيم هذا الربط إلى جزأين: مقدّم خدمة الإشعارات الفورية وخدمة الإشعارات الفورية. الموفِّر هو حزمة تطوير البرامج (SDK) التي تستخدمها لإرسال الرسالة إلى خدمة الإشعارات الفورية. تتوفّر العديد من الخيارات المختلفة، ويمكن لأي مقدّم خدمة إشعارات فورية أن يعمل مع واجهة برمجة التطبيقات Push API (مع أنّ بعضهم قد لا يوفّر حزمة تطوير برامج (SDK) تسهّل عملية الدمج). عليك تجربة حزمة تطوير البرامج (SDK) الخاصة بموفِّر الخدمة لمعرفة الإمكانات المتاحة. خدمة الإشعارات الفورية هي الخدمة التي يتم تسجيل جهاز المستخدم النهائي بها، وبالتالي يمكن تنبيهه بأي رسالة فورية يرسلها مقدّم خدمة الإشعارات الفورية. وهذا أمر لا يمكنك التحكّم فيه، لأنّه مبرمَج بشكل ثابت في المتصفّحات الفردية. بالنسبة إلى Chrome، المراسلة عبر السحابة الإلكترونية من Firebase هي خدمة الإشعارات الفورية. وسيتم توجيه أي رسائل يتم إرسالها إلى مستخدم Chrome من خلال هذا الخادم.

استضافة مقدّم خدمة Push ذاتيًا

يمكن استخدام أي موفّر إشعارات فورية ولكن لا يوفّر جميع الموفّرين حزمة SDK تعمل في عاملي الخدمة. عليك الرجوع إلى موفّر الخدمة إذا واجهت مشاكل في تشغيلها. ولست بحاجة إلى استخدام موفّر عام. باستخدام مكتبات مثل web-push، يمكنك استضافة الخلفية الخاصة بك.

يمكنك تجربة هذه المكتبة باستخدام web-push-codelab.glitch.me. على وجه التحديد، عليك نسخ المفتاح العام لبروتوكول VAPID الخاص بخادم الإشعارات الفورية من أجل إنشاء اشتراك في الإشعارات الفورية في المتصفح. هذا المفتاح العام هو في الواقع قيمة ثنائية مشفّرة باستخدام base64، ويجب فك تشفيرها وتحويلها إلى Uint8Array من أجل التسجيل في Push manager في المتصفح. تتوفّر مكتبات لتنفيذ هذه العملية المنطقية، ولكن كل ما هو مطلوب هو ما يلي.

function urlB64ToUint8Array(base64String) {
  const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
  const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');

  const rawData = atob(base64);
  const outputArray = new Uint8Array(rawData.length);

  for (let i = 0; i < rawData.length; ++i) {
    outputArray[i] = rawData.charCodeAt(i);
  }
  return outputArray;
}

يتم تمرير هذه القيمة إلى "مدير الإشعارات".

const SERVER_PUBLIC_KEY = '_INSERT_VALUE_HERE_';
const applicationServerKey = urlB64ToUint8Array(SERVER_PUBLIC_KEY);

async function subscribe() {
  try {
    let subscription = await self.registration.pushManager.subscribe({
      userVisibleOnly: true,
      applicationServerKey
    });

    console.log(`Subscribed: ${JSON.stringify(subscription,0,2)}`);

    return subscription
  } catch (error) {
    console.error('Subscribe error: ', error);
  }
}

const subscription = await subscribe();

تعرض الدالة subscribe PushSubscription، وهو عنصر يحتوي على البيانات الوصفية لخادم الإشعارات الفورية. بما أنّك تستخدم web-push-codelab.glitch.me، يجب نسخ هذه القيمة إلى قسم "اشتراك في الإشعارات الفورية" في الصفحة.

بعد الحصول على PushSubscription، يمكنك تسجيل متتبِّع لرسائل الإشعارات الفورية في مشغّل الخدمات الخاص بالإضافة.

self.addEventListener('push', function (event) {
  console.log(`Push had this data/text: "${event.data.text()}"`);
});

بعد إعداد متتبِّع، يمكنك إرسال رسالة على web-push-codelab.glitch.me، وسيتم تسجيل الرسائل في وحدة تحكّم مشغّل الخدمات.

بما أنّها معيار ويب مفتوح، يتوفّر الكثير من المستندات الحالية حول كيفية تنفيذ Web Push، بما في ذلك مدونة Chrome. للحصول على نسخة كاملة من المثال الموضّح هنا، يمكنك الاطّلاع على أحد الأمثلة المتوفّرة في مستودع نماذج الإضافات.

إشعار دفع صامت

أصبح بإمكانك تلقّي إشعار فوري في إضافة Manifest V3 منذ طرح الإصدار Manifest V3 في Chrome 88. ومع ذلك، كان هناك دائمًا شرط بأن يعرض الإشعار نوعًا من الطلبات المرئية للمستخدم، مثل إشعار الويب. وقد جعل ذلك الميزة أقل فائدة إذا كنت تريد إرسال أوامر أو تعديلات على البيانات إلى الإضافة بدون إزعاج المستخدم بمعلومات غير ضرورية. اعتبارًا من Chrome 121، يمكن للإضافات ضبط قيمة userVisibleOnly على false. يمكنك الآن إرسال إشعارات فورية صامتة لا تظهر للمستخدمين. لاستخدام هذه الميزة، عليك ضبط userVisibleOnly على false عند استدعاء pushManager.subscribe.

let subscription = await self.registration.pushManager.subscribe({
  userVisibleOnly: false,
  applicationServerKey
});