استخدام Web Push

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

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

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

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

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

موفّرو خدمات Push وخدمات Push

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

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

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

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

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، وهو كائن يحتوي على البيانات الوصفية لخادم Push. بما أنّك تستخدم 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، وسيتم تسجيل الرسائل فيconsole لعامل الخدمة.

بما أنّه معيار ويب مفتوح، تتوفّر الكثير من المستندات الحالية حول كيفية تنفيذ 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
});